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