| 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 |