blob: 4699e4b175e064baf16c0fc0d60720e952b54a82 [file] [log] [blame]
cristyebe41ab2010-01-14 02:58:18 +00001Download & 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
19Configure
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
cristy3ed852e2009-09-05 21:47:34 +000036 In addition to these runtimes, the VisualMagick build environment allows
cristyebe41ab2010-01-14 02:58:18 +000037 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
cristy3ed852e2009-09-05 21:47:34 +000055 Build and execute the configure program and follow the on-screen
cristyebe41ab2010-01-14 02:58:18 +000056 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
cristy71709bf2011-09-25 13:10:29 +000063 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.
cristyebe41ab2010-01-14 02:58:18 +000070
71 Key user defines in magick_config.h include:
72
cristy3ed852e2009-09-05 21:47:34 +000073 MAGICKCORE_QUANTUM_DEPTH (default 16)
cristy71709bf2011-09-25 13:10:29 +000074 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.
cristyebe41ab2010-01-14 02:58:18 +000079
cristy3ed852e2009-09-05 21:47:34 +000080 MAGICKCORE_INSTALLED_SUPPORT (default undefined)
cristyebe41ab2010-01-14 02:58:18 +000081 Define to build a ImageMagick which uses registry settings or embedded
cristy3ed852e2009-09-05 21:47:34 +000082 paths to locate installed components (coder modules and configuration
cristyebe41ab2010-01-14 02:58:18 +000083 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
cristy3ed852e2009-09-05 21:47:34 +000087 ProvideDllMain (default defined)
cristy3ed852e2009-09-05 21:47:34 +000088 Define to include a DllMain() function ensures that the ImageMagick
89 DLL is properly initialized without participation from dependent
cristyebe41ab2010-01-14 02:58:18 +000090 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
100Build
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
cristy3ed852e2009-09-05 21:47:34 +0000124 and test files that can be found in ImageMagick\Magick++\demo, and
cristyebe41ab2010-01-14 02:58:18 +0000125 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
cristy3ed852e2009-09-05 21:47:34 +0000134 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.
cristyebe41ab2010-01-14 02:58:18 +0000137
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
cristy3ed852e2009-09-05 21:47:34 +0000159 VisualMagick\Magick++\demo\UTIL_demo_xxx_exe.dsp (for C++)
cristyebe41ab2010-01-14 02:58:18 +0000160
161 and pop it into Notepad, modify it (carefully) to your needs and be on your
162 way to happy compiling and linking.
163
cristy3ed852e2009-09-05 21:47:34 +0000164 You can feel free to pick any of the standard utilities, tests, or demo
cristyebe41ab2010-01-14 02:58:18 +0000165 programs as the basis for a new program by copying the project and the source
166 and hacking away.
167
cristy3ed852e2009-09-05 21:47:34 +0000168 The choice of what to use as a starting point is very easy.
cristyebe41ab2010-01-14 02:58:18 +0000169
cristy3ed852e2009-09-05 21:47:34 +0000170 For straight C API command line applications use something from:
cristyebe41ab2010-01-14 02:58:18 +0000171
172 ImageMagick\tests or
173 ImageMagick\utilities (source code) or
174 ImageMagick\VisualMagick\tests or
175 ImageMagick\Visualmagick\utilities (project - DSP)
176
cristy3ed852e2009-09-05 21:47:34 +0000177 For C++ and Magick++ command line applications use something from:
cristyebe41ab2010-01-14 02:58:18 +0000178
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
cristy3ed852e2009-09-05 21:47:34 +0000183 For C++ and Magick++ and MFC windows applications use:
cristyebe41ab2010-01-14 02:58:18 +0000184
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
cristy3ed852e2009-09-05 21:47:34 +0000209 With this default setup, you can use any of the command line tools and run
cristyebe41ab2010-01-14 02:58:18 +0000210 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
cristy3ed852e2009-09-05 21:47:34 +0000214 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.
cristyebe41ab2010-01-14 02:58:18 +0000217
218 ENVIRONMENT VARIABLES
219
220 You can use the System control panel to allow you to add and delete what
cristy3ed852e2009-09-05 21:47:34 +0000221 is in any of the environment variables. You can even have user specific
222 environment variables if you wish.
cristyebe41ab2010-01-14 02:58:18 +0000223
cristy3ed852e2009-09-05 21:47:34 +0000224 PATH
cristyebe41ab2010-01-14 02:58:18 +0000225
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
cristy3ed852e2009-09-05 21:47:34 +0000264 To view any image in a Microsoft window, type
cristyebe41ab2010-01-14 02:58:18 +0000265
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
cristy3ed852e2009-09-05 21:47:34 +0000275 The Win2K executables will work under Windows 98.
cristyebe41ab2010-01-14 02:58:18 +0000276
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.
cristy3ed852e2009-09-05 21:47:34 +0000282
cristyebe41ab2010-01-14 02:58:18 +0000283Install
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
Cristy4cff7472016-11-08 06:30:29 -0500294 is C:Program Files\ImageMagick-7.?.?\Q?. The exact folder name depends
cristyebe41ab2010-01-14 02:58:18 +0000295 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
299Create a Self-Installing Binary Distribution
300
301 Prerequisites
302
303 1. Download and install Inno Setup 5.
cristy9d8f7e92010-01-14 14:42:22 +0000304 2. Download and install ActiveState ActivePerl @
305 http://www.activestate.com/activeperl/downloads/.
cristyebe41ab2010-01-14 02:58:18 +0000306
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
cristy4c08aed2011-07-01 19:47:50 +0000350 1. Double-click on VisualMagick/bin/ImageMagick-7.0.0-0-Q16-windows-dll.exe
cristyebe41ab2010-01-14 02:58:18 +0000351 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
376Dealing 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
389Building 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
cristy71709bf2011-09-25 13:10:29 +0000394 Files/ImageMagick-7.0.0-0/Magick++_demos folder. If not, be sure to select
cristyebe41ab2010-01-14 02:58:18 +0000395 Configuration Properties->C/C++->Preprocessor and set these definitions:
396
397 NDEBUG
398 WIN32
399 _CONSOLE
400 _VISUALC_
401 NeedFunctionPrototypes
402 _DLL
403 _MAGICKMOD_