1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
|
HOW TO INSTALL NETPBM
---------------------
For most typical platforms, you can just do
./configure
followed by
make
To build all the programs. Then
make package
to gather all the installable parts into a specified directory, and
finally
./installnetpbm
to install it into your system.
If you have a Debian-like system, that uses Dpkg for package management,
it's better to create a Debian package file and install it as follows in
place of the 'installnetpbm' step above.
make deb
dpkg --install netpbm-sf-*.deb
More information on building and installing on Debian are in the file
buildtools/debian/README in the source tree.
The 'configure' program is not GNU Autoconf -- it is a simple program
specific to Netpbm that prompts you for information about your system.
If your system is not typical enough, you'll have to do a little more
work, as described below under "custom installation."
You need to use GNU Make even if nothing else on your system is GNU,
because the Netpbm make files exploit many advanced features of GNU
Make. Often, systems have both GNU Make and a native Make. In this
case, GNU Make is named 'gmake'. If you don't have it yet, see
www.gnu.org/software. GNU Make is free, easy to install, and works
just about anywhere.
The only tricky part about installing is setting up the shared
libraries that are part of Netpbm. Simply putting the library files
in place may not be enough. If you get mysterious "file not found"
kinds of errors and are not an expert with shared libraries, see the
section "SHARED LIBRARIES" below.
The --keep-going option to Make is handy, because it causes Make to
make anything it can, as opposed to quitting as soon as something goes
wrong. With so many parts having so many requirements, it's not
unusual for a few things to fail to build, but that doesn't affect
everything else. You can work on the failed parts and repeat the make
and it will attempt to build whatever it hasn't successfully built
yet.
CHECKING THE BUILD
------------------
The package comes with a test facility, which you can run after packaging,
against the package you created. The typical sequence is
make
make package
make check
./installnetpbm
To capture all the messages from "make check" do:
make check > test.log 2>&1
The test facility was new in Netpbm 10.61 (December 2012).
For further information on the tests read the document TESTS.
AUTOMATING THE BUILD
--------------------
The build is already as automatic as Netpbm developers know how to make
it without sacrificing your ability to build it a wide variety of ways.
But if you're building for a specific range of applications, e.g. a
particular standard system configuration, then you may want to write
programs to automate the build further.
PLEASE don't do this by writing a program that invokes Netpbm's Configure
program and tries to maintain a dialogue with Configure. This is more work
than you need to do and you will be disappointed with Configure's
unpredictability, especially from one release to the next. Configure is
specifically intended to talk to an intelligent human being.
Rather, just write a program to generate the file config.mk. That's
all Configure does in the end anyway. Like Configure, your program can
simply copy config.mk.in and add overrides to the bottom. Or you
can just package up a complete config.mk and not run any program at
all at build time. Comments in config.mk.in explain the entire
contents. You can also run Configure interactively and use its output
as an example.
THE PREREQUISITE LIBRARIES
--------------------------
Netpbm uses lots of external libraries, but you don't necessarily have
to install them all. See http://netpbm.sourceforge.net/prereq.html .
You do, however, have to tell Configure accurately whether you have the
library installed and if so, where.
INSTALLATION - WINDOWS
----------------------
For notes on building Netpbm on Windows using Cygwin, see the file
README.CYGWIN. With Cygwin, you can build Netpbm programs that use
Cygwin or Netpbm programs that use Mingw.
Netpbm has also been built for Windows using Djgpp, as late as 2001.
See also the general installation instructions above.
INSTALLATION - MAKING ONLY THE PARTS YOU NEED
---------------------------------------------
If you don't need the whole package, but just want one tool in it that you
heard about, you can make just that one. For example, to make Pnmtojpeg,
just do
configure
cd converter/other
make pnmtojpeg
It will build Pnmtojpeg and any of its dependencies, but nothing else.
You have to install it manually.
When you build just one program, you should request a static Netpbm
library in the configure step, because for just one program, the
shared library would be pure masochism.
CUSTOM BUILDING
---------------
This section explains how to customize the installation in the case
that your platform is, or your requirements are, not among the simple
cases that 'configure' understands. 'configure' is really just a
convenient way to build the config.mk file, and in the most
general case, you build that file manually.
config.mk contains settings for various things that vary from
one system to the next, like file paths. Start with the distributed
file config.mk.in. Copy it as config.mk, then edit it.
Search for your platform name (Solaris, SunOS, NetBSD, Cygwin, BeOS,
and Tru64 are among those mentioned) to see recommended settings for
your platform.
If your system is even too exotic to accommodate with settings in
config.mk, you may need to modify things in the main make files
or pm_config.h.in.
If you figure out how to install on other platforms, contact the
Netpbm maintainer to have the 'configure' program or these
instructions improved for the next person.
CUSTOM INSTALLATION
-------------------
If the Installnetpbm program doesn't install the way you want, it is
easy to install it manually using the package that 'make package'
generates. That package is just a directory full of files, and you
should be able to tell by inspection what to do with those files (copy
to /bin, etc). If not, there will be a README file in the package to
explain everything.
INSTALLATION - SHARED LIBRARIES
-------------------------------
There are over 240 programs in the Netpbm package and they do a lot of
common things. In order to avoid the expense of copying the code for
those common things into every program, Netpbm places them in a shared
library: libnetpbm. When you invoke a Netpbm program, your system
notices that it needs this library and accesses it too.
The tricky part of installing the shared (runtime) library is telling
your system where to find it in the event that you invoke a Netpbm
program. And that varies from one system to the next.
On a GNU libc system (essentially, any Linux system), if you put the
Netpbm shared library in a conventional spot (say, /lib) and reboot
your system, chances are you will have no trouble running Netpbm
programs. But if you want to fine tune things, read up on ld-linux.so
(GNU libc's dynamic linker) and Ldconfig and consider the
/etc/ld.so.conf file and LD_LIBRARY_PATH environment variables. Use
'ldd' to see if you have a shared library issue. If it shows any
shared library as "not found", you've got library trouble.
On a Solaris system, use 'crle' to set the default search path for
shared libraries (which is kept in /var/ld/ld.config). Make sure that
path includes the directory in which you installed the Netpbm shared
library. You can also use the LD_LIBRARY_PATH environment variable.
On AIX, the environment variable LIBPATH affects the shared library search
path. On AIX 5.3 and newer, you can use LD_LIBRARY_PATH as well.
Besides the Netpbm shared library, libnetpbm, several of the converter
programs, e.g. Jpegtopnm, use separately distributed libraries that
understand the graphics format involved. You need to make sure your
system knows how to find those libraries at run time too (or cause the
Netpbm build to statically bind the libraries into the Netpbm programs).
Another thing you can do is forget about library search paths and just
build into each Netpbm executable the location of the Netpbm shared
library. (I'm talking about the classic -R linker option) You set
this up with variables in config.mk. If you use Configure to
build config.mk, then for some platforms where this method is
common, the Configure dialog asks you what directory, if any, you want
built into Netpbm executables.
One final note: New Netpbm executables often can run OK with an old
Netpbm shared library. This means if you don't correctly install
the new library, you may run what you think is a new Netpbm program,
but in actuality be accessing the old Netpbm library, and you may not
even notice a problem right away. But eventually, you may find some
things not working the way they should. Again, 'ldd' will give you
peace of mind.
INSTALLATION WITHOUT SHARED LIBRARIES
-------------------------------------
Since shared libraries can be such a pain, and in fact some systems
don't even have them, you can build Netpbm with a static library
instead. Just answer "static" to the static/shared question when you
run 'configure' (if you don't use 'configure', set NETPBMLIBTYPE as
directed in config.mk.in).
If you do this, you probably want to do a merge build instead of the
normal build (there's a question for that in the Configure program).
See below.
SEPARATE BUILD TREE
-------------------
While it's traditional to build a Unix package by adding object files
to the same tree with the source files, it's actually much cleaner to
keep your source tree exactly as you got it and put the built files in
a separate directory, called the build tree.
To do this, just create an empty directory and run 'configure' in it,
then 'make':
mkdir netpbmbuild
cd netpbmbuild
/usr/src/netpbm/configure
...
make
But if you plan to work on Netpbm source code, you'll probably find it
more convenient to build the traditional way, with a single tree for
source and build.
In the source tree, you can type 'make' in any directory to do the
default make for that directory, or make FILENAME to make the file of
that name there. In the separate build tree, there are special
facilities to allow you to do a simple make from the _top level
directory_, but if you want to make a subcomponent or individual part,
you have to have a -f option and set SRCDIR and BLDDIR on your 'make'
command.
MERGE BUILD
-----------
There are two ways to build Netpbm: the standard or nonmerge build,
and the merge build. There are different make file targets for them
and which one is default is controlled by the DEFAULT_TARGET make
variable in config.mk, and its value is one of the choices you
make via the Configure dialog.
The standard build is the conventional one. The merge build is a way to
reduce disk space and other resource usage in some configurations. These are
rare configurations, mostly antique ones. The advent of shared libraries
largely obsoleted the merge build. In some configurations, Netpbm uses _more_
resources with the merge build.
In the standard build, hundreds of separate programs get built: ppmtogif,
pamcomp, etc.
But the merge build creates a single large program called 'netpbm'
instead. That single 'netpbm' program contains the functions of all
the individual programs that the standard build builds, and selects
one of them to execute based on what command name you use to invoke
'netpbm'.
For example, if you install 'netpbm' with a symbolic link to it named
'ppmtogif' and you invoke the program by typing 'ppmtogif' at a shell
prompt, 'netpbm' executes Ppmtogif.
Hence, 'make package' creates a package containing the one 'netpbm'
program and lots of symbolic links to it. With all these links
properly installed, a typical user cannot tell the merge build from the
standard build.
DOCUMENTATION
-------------
Documentation is not packaged with the program source code. See the
file doc/USERDOC for information on installing documentation.
|