]> granicus.if.org Git - imagemagick/blob - Install-windows.txt
(no commit message)
[imagemagick] / Install-windows.txt
1 Download & Unpack
2   
3   Building ImageMagick source for Windows requires a modern version of Microsoft
4   Visual Studio IDE. Users have reported success with the Borland C++ compiler
5   as well. If you don't have a compiler you can still install a self-installing
6   binary release.
7   
8   Download ImageMagick-windows.zip from ftp.imagemagick.org or its mirrors
9   and verify the distribution against its message digest.
10   
11   You can unpack the distribution with WinZip or type the following from any
12   MS-DOS Command Prompt window:
13   
14     $magick> unzip ImageMagick-windows.zip
15   
16   Now that you have the ImageMagick Windows source distribution unpacked,
17   let's configure it.
18   
19 Configure
20   
21   These instructions are specific to building ImageMagick with the Visual
22   Studio under Windows XP, Win2K, or Windows 98. ImageMagick does not include
23   any workspace (DSW) or project files (DSP) except for those included with
24   third party libraries. Instead, there is a configure program that must be
25   built and run which creates the Visual Studio workspaces for ImageMagick. The
26   Visual Studio system provides four different types of runtime environments
27   that must match across all application, library, and dynamic-library (DLL)
28   code that is built. The configure program creates a set of build files that
29   are consistent for a specific runtime selection listed here:
30   
31      1. Dynamic Multi-threaded DLL runtimes (VisualDynamicMT).
32      2. Static Single-threaded runtimes (VisualStaticST).
33      3. Static Multi-threaded runtimes (VisualStaticMT).
34      4. Static Multi-threaded DLL runtimes (VisualStaticMTDLL).
35   
36   In addition to these runtimes, the VisualMagick build environment allows
37   you to select whether to include the X11 libraries in the build or not. X11
38   DLLs and headers are provided with the VisualMagick build environment. Most
39   Windows users are probably not interested in using X11, so you might prefer
40   to build without X11 support. Since the animate, display, and import program
41   depends on the X11 delegate libraries, these programs will no work if you
42   choose not to include X11 support.
43   
44   This leads to five different possible build options. The default binary
45   distribution is built using the Dynamic Multi-threaded DLL (VisualDynamicMT)
46   option with the X11 libraries included. This results in an X11 compatible
47   build using all DLL's for everything and multi-threaded support (the only
48   option for DLL's).
49   
50   To create a workspace for your requirements, simply go to the
51   VisualMagick\configure folder and open the configure.dsw workspace (for
52   Visual Studio 6) or configure.sln (for Visual Studio 7 or 8). Set the build
53   configuration to Release.
54   
55   Build and execute the configure program and follow the on-screen
56   instructions. You should not change any of the defaults unless you have a
57   specific reason to do so.
58   
59   The configure program has a button entitled:
60   
61     Edit "magick_config.h"
62   
63   Click on this button to bring up magick-config.h in Windows Notepad. Review
64   and optionally change any preprocessor defines in ImageMagick's
65   magick_config.h file to suit your needs. This file is copied to
66   magick\magick_config.h. You may safely open magick\magick_config.h, modify
67   it, and recompile without re-running the configure program. In fact, using
68   Notepad to edit the copied file may be preferable since it preserves the
69   original magick_config.h file.
70   
71   Key user defines in magick_config.h include:
72   
73     MAGICKCORE_QUANTUM_DEPTH (default 16)
74       Specify the depth of the pixel component depth (8, 16, or 32). A value of
75       8 uses half the memory than 16 and may run 30% faster, but provides 256
76       times less color resolution than a value of 16. We recommend a quantum
77       depth of 16 because 16-bit images are becoming more prevalent on the
78       Internet.
79   
80     MAGICKCORE_INSTALLED_SUPPORT (default undefined)
81       Define to build a ImageMagick which uses registry settings or embedded
82       paths to locate installed components (coder modules and configuration
83       files). The default is to look for all files in the same directory as
84       the executable. You will wand to define this value if you intend on
85       installing ImageMagick on your system.
86   
87     ProvideDllMain (default defined)
88       Define to include a DllMain() function ensures that the ImageMagick
89       DLL is properly initialized without participation from dependent
90       applications. This avoids the requirement to invoke IntializeMagick()
91       from dependent applications is only useful for DLL builds.
92   
93   ImageMagick is now configured and ready to build.
94   
95   The default build is WIN32. For 64-bit, open a newly created static solution
96   and enter Configuration Manager. Add a x64 configuration, copying the
97   configuration from WIn32. Be sure that it adds the configuration to all the
98   projects. Now compile.
99   
100 Build
101   
102   After creating your build environment, proceed to open the DSW (or SLN)
103   workspace in the VisualMagick folder. In the DSW file choose the All project
104   to make it the active project. Set the build configuration to the desired one
105   (Debug, or Release) and clean and build:
106   
107      1. Right click on the All project and select Set As Active Project
108      2. Select "Build=>Clean Solution"
109      3. Select "Build=>Build Solution"
110   
111   The clean step is necessary in order to make sure that all of the target
112   support libraries are updated with any patches needed to get them to compile
113   properly under Visual Studio.
114   
115   After a successful build, all of the required files that are needed to run
116   any of the command line tools are located in the VisualMagick\bin folder. This
117   includes EXE, DLL libraries, and ImageMagick configuration files. You should
118   be able to test the build directly from this directory without having to
119   move anything to any of the global SYSTEM or SYSTEM32 areas in the operating
120   system installation.
121   
122   The Visual Studio distribution of ImageMagick comes with the Magick++
123   C++ wrapper by default. This add-on layer has a large number of demo
124   and test files that can be found in ImageMagick\Magick++\demo, and
125   ImageMagick\Magick++\tests. There are also a variety of tests that use the
126   straight C API as well in ImageMagick\tests.
127   
128   All of these programs are not configured to be built in the default workspace
129   created by the configure program. You can cause all of these demos and test
130   programs to be built by checking the box in configure that says:
131   
132     Include all demo and test programs
133   
134   In addition, there is another related checkbox (checked by default) that
135   causes all generated project files to be created standalone so that they
136   can be copied to other areas of you system.
137   
138     This the checkbox:
139   
140   Generate all utility projects with full paths rather then relative paths.
141   
142   Visual Studio uses a concept of dependencies that tell it what other
143   components need to be build when a particular project is being build. This
144   mechanism is also used to ensure that components link properly. In my normal
145   development environment, I want to be able to make changes and debug the
146   system as a whole, so I like and NEED to use dependencies. However, most end
147   users don't want to work this way.
148   
149   Instead they really just want to build the package and then get down to
150   business working on their application. The solution is to make all the utility
151   projects (UTIL_xxxx_yy_exe.dsp) use full absolute paths to all the things they
152   need. This way the projects stand on their own and can actually be copied
153   and used as templates to get a particular custom application compiling with
154   little effort.
155   
156   With this feature enabled, you should be able to nab a copy of
157   
158     VisualMagick\utilities\UTIL_convert_xxx_exe.dsp (for C) or
159     VisualMagick\Magick++\demo\UTIL_demo_xxx_exe.dsp (for C++)
160   
161   and pop it into Notepad, modify it (carefully) to your needs and be on your
162   way to happy compiling and linking.
163   
164   You can feel free to pick any of the standard utilities, tests, or demo
165   programs as the basis for a new program by copying the project and the source
166   and hacking away.
167   
168   The choice of what to use as a starting point is very easy.
169   
170   For straight C API command line applications use something from:
171   
172     ImageMagick\tests or
173     ImageMagick\utilities (source code) or
174     ImageMagick\VisualMagick\tests or
175     ImageMagick\Visualmagick\utilities (project - DSP)
176   
177   For C++ and Magick++ command line applications use something from:
178   
179     ImageMagick\Magick++\tests or ImageMagick\Magick++\demo (source code) or
180     ImageMagick\VisualMagick\Magick++\tests or
181     ImageMagick\VisualMagick\Magick++\demo (project - DSP)
182   
183   For C++ and Magick++ and MFC windows applications use:
184   
185     ImageMagick\contrib\win32\MFC\NtMagick (source code) or
186    ImageMagick\VisualMagick\contrib\win32\MFC\NtMagick (project - DSP)
187   
188   The ImageMagick distribution is very modular. The default configuration is
189   there to get you rolling, but you need to make some serious choices when
190   you wish to change things around.
191   
192   The default options are all targeted at having all the components in one place
193   (e.g. the bin directory of the VisualMagick build tree). These components
194   may be copied to another folder (such as to another computer).
195   
196   The folder containing the executables and DLLs should contain the following
197   files:
198   
199      1. magic.xml
200      2. delegates.xml
201      3. modules.xml
202      4. colors.xml
203   
204   among others.
205   
206   The bin folder should contains all EXE's and DLL's as well as the very
207   important modules.xml file.
208   
209   With this default setup, you can use any of the command line tools and run
210   scripts as normal. You can actually get by quite nicely this way by doing
211   something like pushd e:\xxx\yyy\bin in any scripts you write to execute out
212   of this directory.
213   
214   By default the core of ImageMagick on Win32 always looks in the place were
215   the exe program is run from in order to find all of the files as well as
216   the DLL's it needs.
217   
218   ENVIRONMENT VARIABLES
219   
220   You can use the System control panel to allow you to add and delete what
221   is in any of the environment variables. You can even have user specific
222   environment variables if you wish.
223   
224   PATH
225   
226   This environmental variable sets the default list of places were Windows
227   looks for EXE's and DLL's. Windows CMD shell seems to look in the current
228   directory first no matter what, which may make it unnecessary to update the
229   PATH. If you wish to run any of utilities from another location then you
230   must add the path to your bin directory in. For instance, to do this for
231   the default build environment like I do, you might add:
232   
233     C:\ImageMagick\VisualMagick\bin
234     MAGICK_HOME
235   
236   If all you do is modify the PATH variable, the first problem you will run into
237   is that ImageMagick may not be able to find any of its modules. Modules are
238   all the IM_MOD*.DLL files you see in the distribution. There is one of these
239   for each and every file format that ImageMagick supports. This environment
240   variable tells the system were to look for these DLL's. The compiled in
241   default is execution path - which says - look in the same place that the
242   application is running in. If you are running from somewhere other then bin
243   - this will no longer work and you must use this variable. If you elect to
244   leave the modules in the same place as the EXE's (a good idea) then you can
245   simply set this to the same place as you did the PATH variable. In my case:
246   
247     C:\ImageMagick\coders
248   
249   This also the place were ImageMagick expects to find the colors.xml,
250   delegates.xml, magic.xml, modules.xml, and type.xml files.
251   
252   One cool thing about the modules build of ImageMagick is that you can now
253   leave out file formats and lighten you load. If all you ever need is GIF and
254   JPEG, then simply drop all the other DLL's into the local trash can and get
255   on with your life.
256   
257   Always keep the XC format, since ImageMagick uses it internally.
258   
259   You can elect to changes these things the good old hard-coded way. This
260   define is applicable in magick-config.h:
261   
262     #define MagickConfigurePath "C:\\ImageMagick\\"
263   
264   To view any image in a Microsoft window, type
265   
266     $magick> convert image.ext win:
267   
268   Make sure Ghostscript is installed, otherwise, you will be unable to convert
269   or view a Postscript document, and Postscript standard fonts will not be
270   available.
271   
272   You may use any standard web browser (e.g. Internet Explorer) to browse the
273   ImageMagick documentation.
274   
275   The Win2K executables will work under Windows 98.
276   
277   ImageMagick is now configured and built. You can optionally install it on
278   your system as discussed below.
279   
280   If you are looking to install the ImageMagick COM+ object, see Installing
281   the ImageMagickObject COM+ Component.
282
283 Install
284   
285   You can run ImageMagick command line utilities directly from the
286   VisualMagick\bin folder, however, in most cases you may want the convenience
287   of an installer script. ImageMagick provides Inno Setup scripts for this
288   purpose. Note, you must define MAGICKCORE_INSTALLED_SUPPORT at configure
289   time to utilize the installer scripts.
290   
291   To get started building a self-installing ImageMagick executable, go to
292   VisualMagick\installer folder and click on a script that matches your build
293   environment. Press F9 to build and install ImageMagick. The default location
294   is C:Program Files\ImageMagick-6.?.?\Q?. The exact folder name depends
295   on the ImageMagick version and quantum depth. Once installed, ImageMagick
296   command line utilities and libraries are available to the MS Command Prompt,
297   web scripts, or to meet your development needs.
298   
299 Create a Self-Installing Binary Distribution
300   
301   Prerequisites
302   
303      1. Download and install Inno Setup 5.
304      2. Download and install ActiveState ActivePerl @
305         http://www.activestate.com/activeperl/downloads/.
306   
307   Run the Configure Wizard
308   
309      1. Double-click on VisualMagick/configure/configure.sln to build the
310         configure wizard.
311      2. Select Rebuild All and launch the configure wizard.
312      3. Uncheck Use X11 Stubs and check Build demo and test programs.
313      4. Click on Edit magick_config.h and define MAGICKCORE_INSTALLED_SUPPORT.
314      5. Complete the configure wizard screens to create the ImageMagick Visual
315         C++ workspace.
316   
317   Build ImageMagick
318   
319      1. Double-click on VisualMagick/VisualDynamicMT.sln to launch the
320         ImageMagick Visual workspace.
321      2. Set the active configuration to Win32 Release.
322      3. Select Rebuild All to build the ImageMagick binary distribution.
323   
324   Build ImageMagickObject
325   
326      1. Launch the MS-DOS Command Prompt application and move to the
327         contrib\win32\ATL7\ImageMagickObject folder.
328      2. Build ImageMagickObject with these commands:
329   
330           $magick> BuildImageMagickObject clean
331           $magick> BuildImageMagickObject release
332   
333   Build PerlMagick
334   
335      1. Launch the MS-DOS Command Prompt application and move to the PerlMagick
336         folder.
337      2. Build PerlMagick with these commands:
338   
339           $magick> perl Makefile.nt
340           $magick> nmake release
341   
342   Create the Self-installing ImageMagick Binary Distribution
343   
344      1. Double-click on VisualMagick/installer/im-dll-16.iss to launch the
345         Inno Setup 5 wizard.
346      2. Select File->Compile.
347   
348   Install the Binary Distribution
349   
350      1. Double-click on VisualMagick/bin/ImageMagick-7.0.0-0-Q16-windows-dll.exe
351         to launch the ImageMagick binary distribution.
352      2. Complete the installer screens to install ImageMagick on your system.
353   
354   Test the Binary Distribution
355   
356      1. Launch the MS-DOS Command Prompt application and move to the PerlMagick
357         folder and type
358   
359           $magick> nmake test
360   
361      2. Move to the VisualMagick/tests folder and type
362   
363           $magick> validate
364   
365      3. Move to the VisualMagick/Magick++/tests folder and type
366   
367           $magick> run_tests.bat
368   
369      4. Move to the VisualMagick/Magick++/demo folder and type
370   
371           $magick> run_demos.bat
372   
373   If all the tests pass without complaint, the ImageMagick self-install binary
374   distribution is ready for use.
375   
376 Dealing with Unexpected Problems
377   
378   Chances are the download, configure, build, and install of ImageMagick went
379   flawlessly as it is intended, however, certain systems and environments may
380   cause one or more steps to fail. We discuss a few problems we've run across
381   and how to take corrective action to ensure you have a working release
382   of ImageMagick.
383   
384   If the compiler generates an error or if it quits unexpectedly, go to the
385   Visual Studio web site and look for Visual Studio service packs. Chances
386   are, after you download and install all the Visual Studio service packs,
387   ImageMagick will compile and build as expected.
388   
389 Building Your Custom Project
390   
391   The Windows binary distribution includes a number of demo projects that
392   you can use as a template for your own custom project. For example,
393   start with the Button project, generally located in the c:/Program
394   Files/ImageMagick-7.0.0-0/Magick++_demos folder. If not, be sure to select
395   Configuration Properties->C/C++->Preprocessor and set these definitions:
396   
397     NDEBUG
398     WIN32
399     _CONSOLE
400     _VISUALC_
401     NeedFunctionPrototypes
402     _DLL
403     _MAGICKMOD_