about summary refs log tree commit diff
path: root/buildtools/README.pkg
blob: f098e04bbe5cf9cb1d35c560344a26db882d863f (plain) (blame)
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
THESE ARE THE MANUAL INSTALLATION INSTRUCTIONS FOR NETPBM

Most people install using the interactive install program 'installnetpbm'
that is in the top level directory of the Netpbm source tree.  But it 
isn't right for everyone.  If it doesn't do what you need, you can use
these instructions instead.


Once you have built and packaged Netpbm, installing is pretty
straightforward.  If you browse the package directory, you can
probably figure it out without reading any further.


The parts to be installed are:

  Executables 

    These are the basic Netpbm programs, such as 'jpegtopnm'.
    You will find these in the 'bin' subdirectory of the package directory.

    You normally want to copy all of these into a directory that is in your
    default program search path (which is controlled by your PATH 
    environment variable).  Typical directories for this are /bin, /usr/bin,
    and /usr/local/bin.

  Shared Library
         
    This is the library that all Netpbm programs need to load and link
    to at run time.  It is in the 'lib' subdirectory of the package
    directory.  Building a shared library is optional; if you didn't
    do it (which means you built executables that don't require it),
    you don't have a 'lib' subdirectory.  Shared libraries are also
    known as dynamic libraries and DLLs.

    You normally want to copy the shared library to a directory that
    is in your system's default shared library search path.  On
    systems that have an 'ldconfig' program, that program controls the
    shared library search path, and you must run it after copying the
    Netpbm shared library to its directory.  Often, simply rebooting
    will cause it to run cleanly.

    Typical directories for this are /lib, /usr/lib, and /usr/local/lib.

    On Windows, the DLLs are treated like executables, so you should
    find the 'lib' directory empty and you should find the Netpbm DLL
    in the 'bin' directory.  You'll probably want to install the DLL
    and the executables in the same directory, because the shared
    library and executable search paths are the same.

  Link Library

    This is a static link library.  You don't need it to run Netpbm.  You
    need it only if you want to build your own programs that use the Netpbm
    library.  It is in the 'link' subdirectory of the package directory.

    You normally want to copy the link library into a directory that is
    in the default search path of your linker.  Typical directories for 
    this are /usr/lib and /usr/local/lib.

  Interface Headers

    These are the files that declare the interface to the Netpbm 
    programming library.  You don't need them to run Netpbm.  You need
    them only if you want to build your own programs that use the
    Netpbm library.  They are in the 'include' subdirectory of the 
    package directory.

    You normally want to copy the interface header files into a directory
    that is in the default search path of your compiler.  Typical
    directories for this are /usr/include and /usr/local/include.

    All of the files are meant to be named like <netpbm/xxx.h> for C
    #include purposes, which means on an ordinary system, they are
    installed in a directory named "netpbm".  Thus, they are organized
    this way in the package.  BUT: until Netpbm 10.41 (December 2007),
    they were packaged for, and customarily used, just as <xxx.h>.
    Therefore, for backward compatibility, it is a good idea to make
    symbolic links from the parent directory into the netpbm/
    directory.  But as that may pollute your namespace, you may prefer
    just to make all users migrate to the <netpbm/xxx.h> form.

  Data Files

    These are files that you can use for various purposes as input to
    Netpbm programs.  People rarely have uses for them, actually.  They
    are in the 'data' subdirectory of the package directory.
   
    Put these somewhere that users will be able to find them.
    /usr/lib/netpbm and /usr/share/netpbm are typical choices.

  Man Pages

    Netpbm does not have the typical Unix form of documentation.  The
    documentation is not in files that you can read with the common
    'man' program.  Instead, it is in HTML form, and it is not in the
    package directory at all.  You must install it separately.

    But so that a user who is not familiar with Netpbm documentation
    doesn't find himself out in the cold with no access to
    documentation, the package directory contains traditional man
    pages that do nothing but tell you where to get the real
    documentation.  (Exactly where that is depends on the options with
    which you built and packaged Netpbm).  We call these "pointer man
    pages."  You will find these man pages in the 'man' subdirectory
    of the package directory.

    You should copy the contents of this directory wherever your 'man'
    program looks for man pages.  Typically, this is /usr/man, which
    has subdirectories equivalent to those in the package directory's
    'man' subdirectory.


    One of the Netpbm programs is Manweb, which is designed to be a
    replacement for the classic Man program that can access both traditional
    man pages and worldwide web documentation in the Netpbm style with the
    familiar 'man jpegtopnm' kind of command.  The package contains the files
    necessary to use Manweb to access Netpbm documention on the web (on
    netpbm.sourceforge.net).  These files are the contents of the man/web
    directory and the file 'bin/doc.url'.  You should install the
    'bin/doc.url' file if you are installing the Netpbm executables in a
    directory all their own.  You should install the 'man/web' files if you
    are installing the Netpbm executables in some global directory such as
    'usr/bin'.  You should install neither of these if you don't intend to use
    Manweb.

    If you install Manweb as 'man', there is no point to installing the
    pointer man pages -- they will never be used.

    If you want to use Manweb to view the Netpbm manual but use a local
    copy of the manual instead of accessing it on the web, you can get the
    HTML files from the Sourceforge Subversion repository and install those
    instead of the .url files that appear in the 'man/web' directory of the
    package.

The instructions above suggest putting the Netpbm parts in common
directories such as /usr/bin, mingled with other packages.  This is
usually the easiest way to get Netpbm working.  But also consider
putting all Netpbm parts in separate Netpbm directories, such as
/usr/bin/netpbm/ and /usr/link/netpbm.  In fact, you can just copy the
entire package directory in one piece to some place such as
/usr/local/netpbm.  You'll have to take care to set up search paths
and such to make this kind of configuration work.  The advantage of
keeping Netpbm separate is that it makes it easy to wipe out the
entire installation when you don't want it anymore, and to keep
multiple versions around.


netpbm.pkgconfig
----------------

You should create a file named 'netpbm.pkgconfig' out of the template file
'pkgconfig_template' in the package directory, and install netpbm.pkgconfig in
your pkg-config directory (typically /usr/lib/pkgconfig).  Programs that want
to find out where you installed some part of Netpbm can use a 'pkg-config
netpbm ...' command to find out.  For example, a make file for a program that
uses the Netpbm programming library might use this facility to generate the
necessary compiler and linker options to access that library.

The pkg-config facility is fairly widely used, especially with things related
to the X Window System.


netpbm-config
-------------

You should create a shell script named 'netpbm-config' out of the template
file 'config_template' in the package directory, and install netpbm-config in
your executable search path.  Programs that want to find out where you
installed some part of Netpbm can invoke netpbm-config and it will tell them.
For example, a make file for a program that uses the Netpbm programming
library might use netpbm-config to generate the necessary compiler and linker
options to access that library.

Using netpbm-config, it's possible to have a viable Netpbm installation where
netpbm.config is the only file in any default search path.

The xxx-config concept (in general, not just Netpbm) has largely been replaced
by the pkg-config concept (see netpbm.pkgconfig above).