Debian Codegraph @

INSTALL

raw
1 # -*- text -*-
2 # $Id: INSTALL,v 4.6 2008/10/29 00:42:27 hut66au Exp $
3 #
4
5 This is Imview's installation documentation:
6 -------------------------------------------
7
8 These instruction relate to imview 1.1.x
9
10
11 Prerequisite
12 ============
13
14 0- This software works on Unix, MacOS X and Windows. No BeOS,
15 no MacOS prior to OS/X, sorry (please help if you want a version
16 for your favourite O/S).
17
18 1- You will need a reasonably ANSI/ISO compliant C++ compiler,
19
20 The GNU Compiler Collection (GCC) version 3.1 or more recent
21 is such a compiler, that you can get from
22
23 ftp://prep.ai.mit.edu/pub/gnu/
24
25 and various mirrors. Earlier versions of GCC are no longer
26 supported, sorry!
27
28 The Intel C++ compiler, version 7.0 or later is also fine. On
29 Linux this compiler is free for non-commercial use.
30
31 On windows, MS Visual C++ version 6.0 patchlevel 3 is fine for
32 the time being but plans are to move to a more recent version
33 (probably version 7.1 a.k.a. .NET 2003).
34
35 Other compilers might be fine also, YMMV. The configure
36 script will tell you if it thinks your compiler is not
37 up to scratch (and the compilation will probably fail in
38 that case).
39
40
41 2- To build, imview *REQUIRES* FLTK, the Fast Light ToolKit.
42 Get it from
43
44 http://www.fltk.org
45
46 Compile it and install it on your machine. As of this
47 writing, the version I used was fltk-1.1.9.
48 es
49 NOTE: The flags that I used to compile FLTK were:
50
51 fltk% ./configure --enable-threads --enable-xft
52
53 Neither of the two '--enable' switches are indispensable.
54
55 NOTE: While this version of imview requires FLTK 1.1.x.
56 FLTK-1.0.x is still supported in a different imview CVS branch,
57 contact the author if you need that version.
58
59
60 FLTK works on Mac OS/X, most Unix distributions (including Linux) and
61 on Microsoft Windows (all versions >= win95) as well.
62
63 Imview will not compile at all until FLTK is available
64 on your system. An increasing number of Linux distributions come
65 with FLTK available in their repository, but this is the case
66 for Debian, and therefore Ubuntu.
67
68 FLTK itself requires the X11 windowing system OR the
69 windows win32 GDI that comes will all win32 distributions OR
70 the `carbon' environment that comes with MacOS X. All unix
71 systems I know come with X11 (even MacOS X in fact!).
72
73 Recommended add-ons
74 ===================
75
76 While FLTK is the only true requirement, Imview will
77 take advantage of the following libraries/enhancements to the
78 O/S:
79
80 1- The TIFF library (originally by Sam Leffler):
81
82 http://www.libtiff.org/
83
84 Any version after 3.4beta037 is fine. The current version
85 is 3.8.x.
86
87 2- The JPEG library
88
89 ftp://ftp.uu.net/graphics/jpeg/
90
91 I used version v6b.
92
93 3- The ImageMagick library. This will add dozens of
94 formats to those that Imview knows of natively, at the
95 cost of a relatively big library (which can be shared).
96 While ImageMagick is somewhat unstable I still recommend
97 you use it. Version 5.x or 6.x is necessary.
98
99 http://www.simplesystems.org/ImageMagick/
100
101 In turn, ImageMagick may require:
102
103 3a- the PNG library
104
105 ftp://ftp.uu.net/graphics/png/
106
107 Current version is 1.0.8
108
109 3b- the ZLIB library
110
111 ftp://ftp.uu.net/pub/archiving/zip/zlib/
112
113 Current version is 1.1.3
114
115 4- POSIX Threads. Most recent Unix systems come with POSIX-compliant
116 threads, there is a pthread library for win32 available at:
117
118 ftp://sources.redhat.com/pub/pthreads-win32/
119
120 You don't need to bother with the source, just download the DLLs.
121 Imview can compile without threads but you would be giving up
122 on the image server, which is a major feature of imview.
123
124
125 Without the image libraries, Imview will be unable to load the
126 corresponding image formats. Theoretically ImageMagick should be
127 enough (it can also read jpeg and tiff images) but its TIFF support is
128 not great. Imview can read just about any TIFF file, not just the
129 common 8 bit-per-channel ones. The native JPEG support is there for
130 historical reasons.
131
132 Without the POSIX thread library, the Imview server will not run (see the
133 Imview documentation).
134
135 Most Linux distributions come with all the libraries listed above (except
136 FLTK), one notable exception being the (now defunct) Corel distro.
137
138 Building Imview
139 ===============
140
141 1 Under Unix:
142 -------------
143
144 To build imview, normally you only need to do:
145
146 % ./configure
147 % make
148 % make install
149
150
151 1.1 Options
152 -----------
153
154 1.1.1 Standard options
155
156 As is standard with every ./configure scripts, lots of
157 options are available. Try ./configure --help for a list of them!
158 If you are not familiar with autoconf-generated ./configure, just
159 about the only really useful one is --prefix, which specifies
160 where to put your software and where to look for libraries. Normally
161 you would put everything under the one hierarchy, by default under
162 /usr/local
163
164
165 1.1.2 Imview-specific options
166
167 --enable-prof enable prof source profiling support (default is no)
168 --enable-gprof enable gprof source profiling support (default is no)
169 --enable-gcov enable gcov source profiling support (default is no)
170 --without-jpeg disable JPEG support
171 --without-tiff disable TIFF support
172 --without-magick disable ImageMagick support
173 --enable-debug turn on debugging [default=no]
174 --without-server disable image server [default=no]
175 --without-sysv disable Unix SYSV shared memory support [default=no]
176 --with-x use the X Window System
177
178 Unless you know what you are doing, you shouldn't need to mess with
179 these, except maybe --enable-debug, if you've found a bug in Imview that you
180 want to track (by default, ./configure will set things up to build a production
181 release, optimized without symbols).
182
183 1.1.3 A neat trick
184
185 If you are going to build imview for a number of platform, I suggest
186 that you create a obj/<platform> directory, that you cd to this directory
187 and that you run ../../configure from there. Then build imview the normal way
188 in this directory (just run make). This works VERY well (I use it all the time).
189 The big benefit is of course that you can have as many as these
190 <platform> subdirectories as you want and that you don't need to clean and
191 re-configure between them (if you've got the hard disk space, that is).
192
193 2 For windows:
194 ----------------
195
196 There are at least three routes to build Imview for win32:
197
198 2.1: Use a cross-compiler
199 -------------------------
200
201 It is possible to compile Imview with a cross-compiler, this is supported.
202 I cross-compile imview for win32 on both Linux and OS/X. To do that,
203 you need a mingw32 cross compiler, and at configure time, simply specify
204
205 % [./]configure --host=mingw32 <other options>
206
207 2.2: Use GCC under windows
208 --------------------------
209
210 There are at least two ways of running GCC under windows:
211
212 2.2.1: the mingw32 environment
213 ------------------------------
214
215 Mingw32 stands for "minimal" GNU for win32. It uses the GNU tools
216 together with Microsoft's implementation of the ANSI/ISO C and POSIX libraries to
217 make things work. The benefits are that executables are relatively small and
218 portable, and no extra library is necessary besides those that ship with Windows.
219
220 Point your browser to http://www.mingw.org to download the compiler and
221 the environment. The development tools are in the large MinGW.exe package, and
222 the minimal compiling enviroment (including shell) is called MSYS. This MSYS
223 environment is almost like a normal Unix environment, except it's Windows. To
224
225 Nowadays MinGW comes with pre-compiled versions of libtiff, libjpeg,
226 libpng and libz, You'll only need to compile FLTK yourself. Also you'll need
227 POSIX threads to be able to run the server, this can be provided by pthread-win32:
228
229 http://sources.redhat.com/pthreads-win32/
230
231 I've yet to succeed in compiling ImageMagick from within mingw, but
232 I'm sure it's feasible, but apart from that the rest of the libraries that
233 imview uses all compile and work fine.
234
235 To configure and compile Imview, just proceed as under Unix above.
236
237 2.2.2: the Cygwin environment
238 -----------------------------
239
240 Cygwin is an effort to port the whole Unix environment to Windows: X11,
241 shells, utilities, libraries, and development tools:
242
243 http://www.cygwin.com
244
245 From within the cygwin framework you can install pre-compiled version
246 of everything Imview uses: FLTK, libjpeg, libtiff, etc.
247
248 You can ./configure the cygwin environment exactly as with any other
249 Unix platform, the script will detect your environment and compile imview
250 correctly. It will not require X11 to run, but it will require the Cygwin
251 libraries, which in my opinion makes it an inferior solution to the mingw32
252 route for portability, but might make sense in your setup.
253
254 Cygwin provide their own posix thread library, so you don't need the
255 pthread-win32 library that you need if you compile with mingw. Also the
256 ImageMagick library that ships with Cygwin requires X11, so at the moment
257 it's not compatible with imview.
258
259 At any rate the end result works OK but there are some unresolved issues,
260 see the TODO file.
261
262
263 2.3: Use MSVC++
264 ---------------
265
266 The two solutions above work fine for 99% of cases, but I've discovered
267 a bug in the pthread-win32 library that is such that version of Imview compiled with
268 it under any version of GCC for windows will not run well on Windows NT-4.0 on true
269 SMP machines (i.e: If you are running windows NT on a dual-CPU machine or more).
270 This has to do with exception handling. The problem has been reported and might
271 have been fixed but I haven't tested it... It might have gone away with win2k or XP
272 but I seriously doubt it.
273
274 To make Imview work well with Pthreads on multiple CPUs under NT, you need
275 to compile with MSVC++. A project file is included in the obj/NT-msvc++ directory in
276 this distribution. You will need to edit it (by hand!) to indicate the location
277 of the various libraries (fltk, etc). I used MSVC++ version 6.0 patchlevel 3.
278
279 Due to poor template support in MSVC++ 6.0, some functionality is reduced,
280 but this should hardly be noticeable to the casual user.
281
282 BTW, I find MSVC++ about 5 times slower (to compile) than the cross-compiler solution.
283 The end result works fine, of course.
284
285
286 3 For Mac.
287 ---------
288
289 Imview works very well on MacOS/X. Last tested on 10.4.11, no problem reported.
290 Display uses Aqua/Carbon, not X11, thanks to FLTK support. Support for Cocoa is
291 foreseen for when FLTK-2.0 comes out of alpha.
292
293 4 Known issues
294 ================
295
296 Known platforms;
297
298 Imview is known to work on the following platforms
299
300 Linux glibc-2.x:
301 Redhat 5.x, 6.x, 7.x, 8.x and 9,
302 Fedora FC1-FC7
303 Debian 2.2, 3.0 and following, including Ubuntu up to 8.04
304
305 DEC Unix (Compaq Tru64) 3.x, 4.x, 5.x
306 Solaris 2.5.1, Solaris 7, Solaris 8, Solaris 9
307 MS-Windows win32: win9x, win-NT 3.51, win-NT 4.0, win2k, winXP
308 MacOS: Mac OS/X 10.0.3, 10.3.x, 10.4.x
309
310 I welcome any news on any other platform.
311
312 Known bugs:
313 -----------
314
315 There are a few known bugs. Please see the full documentation.
316
317
318 Compilation and installation issues:
319 -----------------------------------
320
321 Here are a few non-platform-dependent issues:
322
323 Warnings:
324
325 There should be very few warnings when you compile imview,
326 except on Solaris (see below). Depending on your compiler,
327 you will probably see a few in imtranslate.cxx. They relate
328 to template instanciation and can be ignored.
329
330 Here are a few platform-dependent issues.
331
332 Solaris: The X11 headers are stuffed, Sun does not provide a
333 set of ANSI-compliant X11 headers: the prototypes are
334 incomplete. Gcc prior to 2.95 just didn't care but
335 suddently from 2.95 it refuses to compile
336 these headers unless the -fpermissive flag is added. The
337 configure script checks for that *BUT* you will most
338 likely get a *TON* of warnings. gcc-2.95.3 has a workaround
339 that works if the set of headers that you use come from
340 /usr/include/X11. Myself I've just patched gcc so this
341 problem disappears. Contact me if you want to get it, it's
342 a one-line change.
343
344 You may have to specify --x-libraries=/usr/openwin/lib to
345 the configure script if you get an error with the
346 exception structure being multiply defined under Solaris-2.5.1
347
348
349
350 FINALLY:
351 ========
352
353
354 Thank you for your interest in Imview. Let me know how you go!
355
356 First version:
357 Hugues Talbot 22 Dec 2000
358
359 Last edited:
360 Hugues Talbot 27 Oct 2008 -- Release 1.1.9d