Thu Mar 5 13:08:02 2009 UTC ()
Added DESTDIR examples and section 10.1.3. Python modules and programs


(imil)
diff -r1.32 -r1.33 pkgsrc/doc/guide/files/configuring.xml
diff -r1.7 -r1.8 pkgsrc/doc/guide/files/creating.xml
cvs diff -r1.32 -r1.33 pkgsrc/doc/guide/files/configuring.xml (switch to unified diff)

--- pkgsrc/doc/guide/files/configuring.xml 2009/01/28 23:31:39 1.32
+++ pkgsrc/doc/guide/files/configuring.xml 2009/03/05 13:08:02 1.33
@@ -1,407 +1,446 @@ @@ -1,407 +1,446 @@
1<!-- $NetBSD: configuring.xml,v 1.32 2009/01/28 23:31:39 abs Exp $ --> 1<!-- $NetBSD: configuring.xml,v 1.33 2009/03/05 13:08:02 imil Exp $ -->
2 2
3<chapter id="configuring"> 3<chapter id="configuring">
4 <title>Configuring pkgsrc</title> 4 <title>Configuring pkgsrc</title>
5 5
6<anchor id="mk.conf" /> 6<anchor id="mk.conf" />
7 7
8<para>The whole pkgsrc system is configured in a single file, usually 8<para>The whole pkgsrc system is configured in a single file, usually
9called <filename>mk.conf</filename>. In which directory pkgsrc looks for 9called <filename>mk.conf</filename>. In which directory pkgsrc looks for
10that file depends on the installation. On NetBSD, when you use 10that file depends on the installation. On NetBSD, when you use
11&man.make.1; from the base system, it is in the directory 11&man.make.1; from the base system, it is in the directory
12<filename>/etc/</filename>. In all other cases the default location is 12<filename>/etc/</filename>. In all other cases the default location is
13<literal>${PREFIX}/etc/</literal>, depending on where you told the 13<literal>${PREFIX}/etc/</literal>, depending on where you told the
14bootstrap program to install the binary packages.</para> 14bootstrap program to install the binary packages.</para>
15 15
16<para>During the bootstrap, an example configuration file is created. To 16<para>During the bootstrap, an example configuration file is created. To
17use that, you have to create the directory 17use that, you have to create the directory
18<filename>${PREFIX}/etc</filename> and copy the example file 18<filename>${PREFIX}/etc</filename> and copy the example file
19there.</para> 19there.</para>
20 20
21<para>The format of the configuration file is that of the usual 21<para>The format of the configuration file is that of the usual
22BSD-style <filename>Makefile</filename>s. The whole pkgsrc configuration 22BSD-style <filename>Makefile</filename>s. The whole pkgsrc configuration
23is done by setting variables in this file. Note that you can define all 23is done by setting variables in this file. Note that you can define all
24kinds of variables, and no special error checking (for example for 24kinds of variables, and no special error checking (for example for
25spelling mistakes) takes place, so you have to try it out to see if it 25spelling mistakes) takes place, so you have to try it out to see if it
26works.</para> 26works.</para>
27 27
28 <sect1 id="general-configuration"> 28 <sect1 id="general-configuration">
29 <title>General configuration</title> 29 <title>General configuration</title>
30 30
31 <para>In this section, you can find some variables that apply to all 31 <para>In this section, you can find some variables that apply to all
32 pkgsrc packages. A complete list of the variables that can be 32 pkgsrc packages. A complete list of the variables that can be
33 configured by the user is available in 33 configured by the user is available in
34 <filename>mk/defaults/mk.conf</filename>, together with some 34 <filename>mk/defaults/mk.conf</filename>, together with some
35 comments that describe each variable's intent.</para> 35 comments that describe each variable's intent.</para>
36 36
37 <itemizedlist> 37 <itemizedlist>
38 <listitem><para><varname>LOCALBASE</varname>: Where 38 <listitem><para><varname>LOCALBASE</varname>: Where
39 packages will be installed. The default is 39 packages will be installed. The default is
40 <filename>/usr/pkg</filename>. Do not mix binary packages 40 <filename>/usr/pkg</filename>. Do not mix binary packages
41 with different <varname>LOCALBASE</varname>s!</para> 41 with different <varname>LOCALBASE</varname>s!</para>
42 </listitem> 42 </listitem>
43 <listitem><para><varname>CROSSBASE</varname>: Where 43 <listitem><para><varname>CROSSBASE</varname>: Where
44 <quote>cross</quote> category packages will be 44 <quote>cross</quote> category packages will be
45 installed. The default is 45 installed. The default is
46 <filename>${LOCALBASE}/cross</filename>.</para> 46 <filename>${LOCALBASE}/cross</filename>.</para>
47 </listitem> 47 </listitem>
48 <listitem><para><varname>X11BASE</varname>: Where 48 <listitem><para><varname>X11BASE</varname>: Where
49 X11 is installed on the system. The default is 49 X11 is installed on the system. The default is
50 <filename>/usr/X11R6</filename>.</para> 50 <filename>/usr/X11R6</filename>.</para>
51 </listitem> 51 </listitem>
52 <listitem><para><varname>DISTDIR</varname>: Where to store the 52 <listitem><para><varname>DISTDIR</varname>: Where to store the
53 downloaded copies of the original source distributions used 53 downloaded copies of the original source distributions used
54 for building pkgsrc packages. The default is 54 for building pkgsrc packages. The default is
55 <filename>${PKGSRCDIR}/distfiles</filename>.</para> 55 <filename>${PKGSRCDIR}/distfiles</filename>.</para>
56 </listitem> 56 </listitem>
57 <listitem><para><varname>PKG_DBDIR</varname>: Where the 57 <listitem><para><varname>PKG_DBDIR</varname>: Where the
58 database about installed packages is stored. The default is 58 database about installed packages is stored. The default is
59 <filename>/var/db/pkg</filename>.</para> 59 <filename>/var/db/pkg</filename>.</para>
60 </listitem> 60 </listitem>
61 <listitem><para><varname>MASTER_SITE_OVERRIDE</varname>: 61 <listitem><para><varname>MASTER_SITE_OVERRIDE</varname>:
62 If set, override the packages' 62 If set, override the packages'
63 <varname>MASTER_SITES</varname> with this value.</para> 63 <varname>MASTER_SITES</varname> with this value.</para>
64 </listitem> 64 </listitem>
65 <listitem><para><varname>MASTER_SITE_BACKUP</varname>: 65 <listitem><para><varname>MASTER_SITE_BACKUP</varname>:
66 Backup location(s) for distribution files and patch files 66 Backup location(s) for distribution files and patch files
67 if not found locally or in 67 if not found locally or in
68 <filename>${MASTER_SITES}</filename> or 68 <filename>${MASTER_SITES}</filename> or
69 <filename>${PATCH_SITES}</filename> respectively. 69 <filename>${PATCH_SITES}</filename> respectively.
70 The defaults are 70 The defaults are
71 <filename>ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/${DIST_SUBDIR}/</filename> 71 <filename>ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/${DIST_SUBDIR}/</filename>
72 and 72 and
73 <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/</filename>.</para> 73 <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/</filename>.</para>
74 </listitem> 74 </listitem>
75 <listitem><para><varname>BINPKG_SITES</varname>: 75 <listitem><para><varname>BINPKG_SITES</varname>:
76 List of sites carrying binary pkgs. <replaceable>rel</replaceable> and 76 List of sites carrying binary pkgs. <replaceable>rel</replaceable> and
77 <replaceable>arch</replaceable> are replaced with OS 77 <replaceable>arch</replaceable> are replaced with OS
78 release (<quote>2.0</quote>, etc.) and architecture 78 release (<quote>2.0</quote>, etc.) and architecture
79 (<quote>mipsel</quote>, etc.).</para> 79 (<quote>mipsel</quote>, etc.).</para>
80 </listitem> 80 </listitem>
81 <listitem><para><varname>ACCEPTABLE_LICENSES</varname>: 81 <listitem><para><varname>ACCEPTABLE_LICENSES</varname>:
82 List of acceptable licenses. Whenever you try to build a package 82 List of acceptable licenses. Whenever you try to build a package
83 whose license is not in this list, you will get an error message 83 whose license is not in this list, you will get an error message
84 that includes instructions on how to change this variable.</para> 84 that includes instructions on how to change this variable.</para>
85 </listitem> 85 </listitem>
86 </itemizedlist> 86 </itemizedlist>
87 </sect1> 87 </sect1>
88 88
89 <sect1 id="variables-affecting-build"> 89 <sect1 id="variables-affecting-build">
90 <title>Variables affecting the build process</title> 90 <title>Variables affecting the build process</title>
91 <para>XXX 91 <para>XXX
92 <itemizedlist> 92 <itemizedlist>
93 <listitem><para><varname>PACKAGES</varname>: The top level 93 <listitem><para><varname>PACKAGES</varname>: The top level
94 directory for the binary packages. The default is 94 directory for the binary packages. The default is
95 <filename>${PKGSRCDIR}/packages</filename>.</para> 95 <filename>${PKGSRCDIR}/packages</filename>.</para>
96 </listitem> 96 </listitem>
97 <listitem><para><varname>WRKOBJDIR</varname>: 97 <listitem><para><varname>WRKOBJDIR</varname>:
98 The top level directory where, if defined, the separate 98 The top level directory where, if defined, the separate
99 working directories will get created, and symbolically 99 working directories will get created, and symbolically
100 linked to from <filename>${WRKDIR}</filename> (see below). 100 linked to from <filename>${WRKDIR}</filename> (see below).
101 This is useful for building packages on several 101 This is useful for building packages on several
102 architectures, then <filename>${PKGSRCDIR}</filename> 102 architectures, then <filename>${PKGSRCDIR}</filename>
103 can be NFS-mounted while <filename>${WRKOBJDIR}</filename> 103 can be NFS-mounted while <filename>${WRKOBJDIR}</filename>
104 is local to every architecture. (It should be noted that 104 is local to every architecture. (It should be noted that
105 <varname>PKGSRCDIR</varname> should not be set by the user 105 <varname>PKGSRCDIR</varname> should not be set by the user
106 &mdash; it is an internal definition which refers to the 106 &mdash; it is an internal definition which refers to the
107 root of the pkgsrc tree. It is possible to have many 107 root of the pkgsrc tree. It is possible to have many
108 pkgsrc tree instances.)</para> 108 pkgsrc tree instances.)</para>
109 </listitem> 109 </listitem>
110 <listitem><para><varname>LOCALPATCHES</varname>: 110 <listitem><para><varname>LOCALPATCHES</varname>:
111 Directory for local patches that aren't part of pkgsrc. 111 Directory for local patches that aren't part of pkgsrc.
112 See <xref linkend="components.patches" /> for more 112 See <xref linkend="components.patches" /> for more
113 information.</para> 113 information.</para>
114 </listitem> 114 </listitem>
115 <listitem><para><varname>PKGMAKECONF</varname>: Location of 115 <listitem><para><varname>PKGMAKECONF</varname>: Location of
116 the &mk.conf; file used by a package's 116 the &mk.conf; file used by a package's
117 BSD-style Makefile. If this is not set, 117 BSD-style Makefile. If this is not set,
118 <varname>MAKECONF</varname> is set to 118 <varname>MAKECONF</varname> is set to
119 <filename>/dev/null</filename> to avoid picking up 119 <filename>/dev/null</filename> to avoid picking up
120 settings used by builds in <filename>/usr/src</filename>.</para> 120 settings used by builds in <filename>/usr/src</filename>.</para>
121 </listitem> 121 </listitem>
122 <listitem><para><varname>DEPENDS_TARGET</varname>: 122 <listitem><para><varname>DEPENDS_TARGET</varname>:
123 By default, dependencies are only installed, and no binary 123 By default, dependencies are only installed, and no binary
124 package is created for them. You can set this variable to 124 package is created for them. You can set this variable to
125 <literal>package</literal> to automatically create binary 125 <literal>package</literal> to automatically create binary
126 packages after installing dependencies.</para> 126 packages after installing dependencies.</para>
127 </listitem> 127 </listitem>
128 128
129 <!-- DISTDIR --> 129 <!-- DISTDIR -->
130 <!-- FAILOVER_FETCH --> 130 <!-- FAILOVER_FETCH -->
131 </itemizedlist></para> 131 </itemizedlist></para>
132 </sect1> 132 </sect1>
133 133
134 <sect1 id="variables-affecting-installation"> 134 <sect1 id="variables-affecting-installation">
135 <title>Variables affecting the installation process</title> 135 <title>Variables affecting the installation process</title>
136 136
137 <para>A growing number of packages support installation into a 137 <para>A growing number of packages support installation into a
138 subdirectory of <varname>WRKDIR</varname>. This allows a package 138 subdirectory of <varname>WRKDIR</varname>. This allows a package
139 to be built, before the actual filesystem is touched. DESTDIR 139 to be built, before the actual filesystem is touched. DESTDIR
140 support exists in two variations:</para> 140 support exists in two variations:</para>
141 <itemizedlist> 141 <itemizedlist>
142 <listitem><para>Basic DESTDIR support means that the package 142 <listitem><para>Basic DESTDIR support means that the package
143 installation and packaging is still run as 143 installation and packaging is still run as
144 root.</para></listitem> 144 root.</para></listitem>
145 <listitem><para>Full DESTDIR support can run the complete build, 145 <listitem><para>Full DESTDIR support can run the complete build,
146 installation and packaging as normal user. Root privileges are 146 installation and packaging as normal user. Root privileges are
147 only needed to add packages.</para></listitem> 147 only needed to add packages.</para></listitem>
148 </itemizedlist> 148 </itemizedlist>
149 <para>To use the DESTDIR support, set either 149 <para>To use the DESTDIR support, set either
150 <varname>USE_DESTDIR=yes</varname> to use the basic support for 150 <varname>USE_DESTDIR=yes</varname> to use the basic support for
151 packages that offer it or <varname>USE_DESTDIR=full</varname> to 151 packages that offer it or <varname>USE_DESTDIR=full</varname> to
152 get the full support with fallback to basic 152 get the full support with fallback to basic
153 support. <varname>USE_DESTDIR=full</varname> needs <filename 153 support. <varname>USE_DESTDIR=full</varname> needs <filename
154 role="pkg">pkgtools/pkg_install</filename> version 20070802 (or 154 role="pkg">pkgtools/pkg_install</filename> version 20070802 (or
155 newer). It might become the default DESTDIR support later.</para> 155 newer). It might become the default DESTDIR support later.</para>
156 <para>DESTDIR support changes the behaviour of various targets 156 <para>DESTDIR support changes the behaviour of various targets
157 slightly. To install a package after building it, use 157 slightly. To install a package after building it, use
158 <literal>package-install</literal>. <literal>package</literal> and 158 <literal>package-install</literal>. <literal>package</literal> and
159 <literal>install</literal> don't do that any 159 <literal>install</literal> don't do that any
160 longer. <literal>package-install</literal> can be used as 160 longer. <literal>package-install</literal> can be used as
161 <varname>DEPENDS_TARGET</varname>. <literal>bin-install</literal> 161 <varname>DEPENDS_TARGET</varname>. <literal>bin-install</literal>
162 will ask for the root password to install the package and fail, 162 will ask for the root password to install the package and fail,
163 <literal>package-install</literal> will ask again.</para> 163 <literal>package-install</literal> will ask again.</para>
164 <para>With basic DESTDIR support, <userinput>make 164 <para>With basic DESTDIR support, <userinput>make
165 clean</userinput> needs to be run as root.</para> 165 clean</userinput> needs to be run as root.</para>
 166
 167 <para>Considering the <filename>foo/bar</filename> package,
 168 DESTDIR full support can be tested using the following commands
 169
 170<programlisting>
 171&uprompt; id
 172uid=1000(myusername) gid=100(users) groups=100(users),0(wheel)
 173&uprompt; mkdir $HOME/packages
 174&uprompt; cd $PKGSRCDIR/foo/bar
 175</programlisting>
 176
 177 Verify <varname>DESTDIR</varname> full support, no root privileges
 178 should be needed
 179
 180<programlisting>
 181&uprompt; make USE_DESTDIR=full install
 182</programlisting>
 183
 184 Create a package without root privileges
 185
 186<programlisting>
 187&uprompt; make USE_DESTDIR=full PACKAGES=$HOME/packages package
 188</programlisting>
 189
 190 For the following command, you must be able to gain root
 191 privileges using &man.su.1;
 192
 193<programlisting>
 194&uprompt; make USE_DESTDIR=full PACKAGES=$HOME/packages package-install
 195</programlisting>
 196
 197 Then, as a simple user
 198
 199<programlisting>
 200&uprompt; make clean
 201</programlisting>
 202
 203 </para>
 204
166 </sect1> 205 </sect1>
167 206
168<sect1 id="conf.compiler"> 207<sect1 id="conf.compiler">
169<title>Selecting and configuring the compiler</title> 208<title>Selecting and configuring the compiler</title>
170 209
171 <sect2 id="selecting-the-compiler"> 210 <sect2 id="selecting-the-compiler">
172 <title>Selecting the compiler</title> 211 <title>Selecting the compiler</title>
173 212
174 <para>By default, pkgsrc will use GCC to build packages. This may be 213 <para>By default, pkgsrc will use GCC to build packages. This may be
175 overridden by setting the following variables in /etc/mk.conf:</para> 214 overridden by setting the following variables in /etc/mk.conf:</para>
176 215
177 <variablelist> 216 <variablelist>
178 <varlistentry> 217 <varlistentry>
179 <term><varname>PKGSRC_COMPILER</varname>:</term> 218 <term><varname>PKGSRC_COMPILER</varname>:</term>
180 219
181 <listitem> 220 <listitem>
182 <para>This is a list of values specifying the chain of 221 <para>This is a list of values specifying the chain of
183 compilers to invoke when building packages. Valid values 222 compilers to invoke when building packages. Valid values
184 are:</para> 223 are:</para>
185 224
186 <!-- TODO: update this list after jlam's changes in May 2005 --> 225 <!-- TODO: update this list after jlam's changes in May 2005 -->
187 <itemizedlist> 226 <itemizedlist>
188 <listitem><para><varname>distcc</varname>: 227 <listitem><para><varname>distcc</varname>:
189 distributed C/C++ (chainable)</para> 228 distributed C/C++ (chainable)</para>
190 </listitem> 229 </listitem>
191 230
192 <listitem><para><varname>ccache</varname>: 231 <listitem><para><varname>ccache</varname>:
193 compiler cache (chainable)</para> 232 compiler cache (chainable)</para>
194 </listitem> 233 </listitem>
195 234
196 <listitem><para><varname>gcc</varname>: 235 <listitem><para><varname>gcc</varname>:
197 GNU C/C++ Compiler</para> 236 GNU C/C++ Compiler</para>
198 </listitem> 237 </listitem>
199 238
200 <listitem><para><varname>mipspro</varname>: 239 <listitem><para><varname>mipspro</varname>:
201 Silicon Graphics, Inc. MIPSpro (n32/n64)</para> 240 Silicon Graphics, Inc. MIPSpro (n32/n64)</para>
202 </listitem> 241 </listitem>
203 242
204 <listitem><para><varname>mipspro</varname>: 243 <listitem><para><varname>mipspro</varname>:
205 Silicon Graphics, Inc. MIPSpro (o32)</para> 244 Silicon Graphics, Inc. MIPSpro (o32)</para>
206 </listitem> 245 </listitem>
207 246
208 <listitem><para><varname>sunpro</varname>: 247 <listitem><para><varname>sunpro</varname>:
209 Sun Microsystems, Inc. WorkShip/Forte/Sun ONE Studio</para> 248 Sun Microsystems, Inc. WorkShip/Forte/Sun ONE Studio</para>
210 </listitem> 249 </listitem>
211 </itemizedlist> 250 </itemizedlist>
212 251
213 <para>The default is 252 <para>The default is
214 <quote><varname>gcc</varname></quote>. You can use 253 <quote><varname>gcc</varname></quote>. You can use
215 <varname>ccache</varname> and/or 254 <varname>ccache</varname> and/or
216 <varname>distcc</varname> with an appropriate 255 <varname>distcc</varname> with an appropriate
217 <varname>PKGSRC_COMPILER</varname> setting, 256 <varname>PKGSRC_COMPILER</varname> setting,
218 e.g. <quote><varname>ccache gcc</varname></quote>. This 257 e.g. <quote><varname>ccache gcc</varname></quote>. This
219 variable should always be terminated with a value for 258 variable should always be terminated with a value for
220 a real compiler. Note that only one real compiler 259 a real compiler. Note that only one real compiler
221 should be listed (e.g. <quote><varname>sunpro gcc</varname></quote> 260 should be listed (e.g. <quote><varname>sunpro gcc</varname></quote>
222 is not allowed).</para> 261 is not allowed).</para>
223 </listitem> 262 </listitem>
224 </varlistentry> 263 </varlistentry>
225 264
226 <varlistentry> 265 <varlistentry>
227 <term><varname>GCC_REQD</varname>:</term> 266 <term><varname>GCC_REQD</varname>:</term>
228 <!-- 267 <!--
229 TODO: what are the effects of setting GCC_REQD if PKGSRC_COMPILER 268 TODO: what are the effects of setting GCC_REQD if PKGSRC_COMPILER
230 is not gcc? 269 is not gcc?
231 --> 270 -->
232 <listitem> 271 <listitem>
233 <para>This specifies the minimum version of GCC to use 272 <para>This specifies the minimum version of GCC to use
234 when building packages. If the system GCC doesn't 273 when building packages. If the system GCC doesn't
235 satisfy this requirement, then pkgsrc will build and 274 satisfy this requirement, then pkgsrc will build and
236 install one of the GCC packages to use instead.</para> 275 install one of the GCC packages to use instead.</para>
237 </listitem> 276 </listitem>
238 </varlistentry> 277 </varlistentry>
239 </variablelist> 278 </variablelist>
240 </sect2> 279 </sect2>
241 280
242<sect2 id="conf.cflags"> 281<sect2 id="conf.cflags">
243<title>Additional flags to the compiler (<varname>CFLAGS</varname>)</title> 282<title>Additional flags to the compiler (<varname>CFLAGS</varname>)</title>
244 283
245 <para>If you wish to set the <varname>CFLAGS</varname> variable, 284 <para>If you wish to set the <varname>CFLAGS</varname> variable,
246 please make sure to use the <literal>+=</literal> operator 285 please make sure to use the <literal>+=</literal> operator
247 instead of the <literal>=</literal> operator:</para> 286 instead of the <literal>=</literal> operator:</para>
248 287
249<programlisting> 288<programlisting>
250CFLAGS+= -your -flags 289CFLAGS+= -your -flags
251</programlisting> 290</programlisting>
252 291
253 <para>Using <varname>CFLAGS=</varname> (i.e. without the 292 <para>Using <varname>CFLAGS=</varname> (i.e. without the
254 <quote>+</quote>) may lead to problems with packages that 293 <quote>+</quote>) may lead to problems with packages that
255 need to add their own flags. You may want to take a look 294 need to add their own flags. You may want to take a look
256 at the <filename role="pkg">devel/cpuflags</filename> 295 at the <filename role="pkg">devel/cpuflags</filename>
257 package if you're interested in optimization for the current 296 package if you're interested in optimization for the current
258 CPU. Setting <varname>USE_CPUFLAGS</varname> to yes in 297 CPU. Setting <varname>USE_CPUFLAGS</varname> to yes in
259 &mk.conf; will cause pkgsrc to automatically use cpuflags.</para> 298 &mk.conf; will cause pkgsrc to automatically use cpuflags.</para>
260 299
261</sect2> 300</sect2>
262 301
263<sect2 id="conf.ldflags"> 302<sect2 id="conf.ldflags">
264<title>Additional flags to the linker (<varname>LDFLAGS</varname>)</title> 303<title>Additional flags to the linker (<varname>LDFLAGS</varname>)</title>
265 304
266<para>If you want to pass flags to the linker, both in the configure 305<para>If you want to pass flags to the linker, both in the configure
267step and the build step, you can do this in two ways. Either set 306step and the build step, you can do this in two ways. Either set
268<varname>LDFLAGS</varname> or <varname>LIBS</varname>. The difference 307<varname>LDFLAGS</varname> or <varname>LIBS</varname>. The difference
269between the two is that <varname>LIBS</varname> will be appended to 308between the two is that <varname>LIBS</varname> will be appended to
270the command line, while <varname>LDFLAGS</varname> come earlier. 309the command line, while <varname>LDFLAGS</varname> come earlier.
271<varname>LDFLAGS</varname> is pre-loaded with rpath settings for ELF 310<varname>LDFLAGS</varname> is pre-loaded with rpath settings for ELF
272machines depending on the setting of <varname>USE_IMAKE</varname> or 311machines depending on the setting of <varname>USE_IMAKE</varname> or
273the inclusion of <filename>mk/x11.buildlink3.mk</filename>. As with 312the inclusion of <filename>mk/x11.buildlink3.mk</filename>. As with
274<varname>CFLAGS</varname>, if you do not wish to override these 313<varname>CFLAGS</varname>, if you do not wish to override these
275settings, use the <literal>+=</literal> operator:</para> 314settings, use the <literal>+=</literal> operator:</para>
276<programlisting> 315<programlisting>
277LDFLAGS+= -your -linkerflags 316LDFLAGS+= -your -linkerflags
278</programlisting> 317</programlisting>
279</sect2> 318</sect2>
280</sect1> 319</sect1>
281 320
282 <!-- Configuration files --> 321 <!-- Configuration files -->
283 <!-- PKG_SYSCONFBASE --> 322 <!-- PKG_SYSCONFBASE -->
284 <!-- PKG_SYSCONFDIR.foobar --> 323 <!-- PKG_SYSCONFDIR.foobar -->
285 324
286 <!-- Security --> 325 <!-- Security -->
287 <!-- PKGVULNDIR --> 326 <!-- PKGVULNDIR -->
288 327
289 <sect1 id="developer-advanced-settings"> 328 <sect1 id="developer-advanced-settings">
290 <title>Developer/advanced settings</title> 329 <title>Developer/advanced settings</title>
291 330
292 <!-- USE_ABI_DEPENDS --> 331 <!-- USE_ABI_DEPENDS -->
293 <para>XXX 332 <para>XXX
294 <itemizedlist> 333 <itemizedlist>
295 <listitem><para><varname>PKG_DEVELOPER</varname>: 334 <listitem><para><varname>PKG_DEVELOPER</varname>:
296 Run some sanity checks that package developers want: 335 Run some sanity checks that package developers want:
297 <itemizedlist> 336 <itemizedlist>
298 <listitem><para>make sure patches apply with zero 337 <listitem><para>make sure patches apply with zero
299 fuzz</para></listitem> 338 fuzz</para></listitem>
300 <listitem><para>run check-shlibs to see that all 339 <listitem><para>run check-shlibs to see that all
301 binaries will find their shared libs.</para> 340 binaries will find their shared libs.</para>
302 <!-- XXX: some more stuff --> 341 <!-- XXX: some more stuff -->
303 </listitem> 342 </listitem>
304 </itemizedlist> 343 </itemizedlist>
305 </para> 344 </para>
306 </listitem> 345 </listitem>
307 <listitem><para><varname>PKG_DEBUG_LEVEL</varname>: The level 346 <listitem><para><varname>PKG_DEBUG_LEVEL</varname>: The level
308 of debugging output which is displayed whilst making and 347 of debugging output which is displayed whilst making and
309 installing the package. The default value for this is 0, 348 installing the package. The default value for this is 0,
310 which will not display the commands as they are executed 349 which will not display the commands as they are executed
311 (normal, default, quiet operation); the value 1 will display 350 (normal, default, quiet operation); the value 1 will display
312 all shell commands before their invocation, and the value 2 351 all shell commands before their invocation, and the value 2
313 will display both the shell commands before their invocation, 352 will display both the shell commands before their invocation,
314 and their actual execution progress with <command>set 353 and their actual execution progress with <command>set
315 -x</command> will be displayed.</para></listitem> 354 -x</command> will be displayed.</para></listitem>
316 </itemizedlist> 355 </itemizedlist>
317 </para> 356 </para>
318 </sect1> 357 </sect1>
319 358
320 <!-- pkginstall-related variables --> 359 <!-- pkginstall-related variables -->
321 <!-- PKG_REGISTER_SHELLS --> 360 <!-- PKG_REGISTER_SHELLS -->
322 <!-- PKG_RCD_SCRIPTS --> 361 <!-- PKG_RCD_SCRIPTS -->
323 362
324 <sect1 id="selecting-build-options"> 363 <sect1 id="selecting-build-options">
325 <title>Selecting Build Options</title> 364 <title>Selecting Build Options</title>
326 365
327 <para>Some packages have build time options, usually to select 366 <para>Some packages have build time options, usually to select
328 between different dependencies, enable optional support for big 367 between different dependencies, enable optional support for big
329 dependencies or enable experimental features.</para> 368 dependencies or enable experimental features.</para>
330 369
331 <para>To see which options, if any, a package supports, and which 370 <para>To see which options, if any, a package supports, and which
332 options are mutually exclusive, run <command>make 371 options are mutually exclusive, run <command>make
333 show-options</command>, for example:</para> 372 show-options</command>, for example:</para>
334 373
335<programlisting> 374<programlisting>
336 The following options are supported by this package: 375 The following options are supported by this package:
337 ssl Enable SSL support. 376 ssl Enable SSL support.
338 Exactly one of the following gecko options is required: 377 Exactly one of the following gecko options is required:
339 firefox Use firefox as gecko rendering engine. 378 firefox Use firefox as gecko rendering engine.
340 mozilla Use mozilla as gecko rendering engine. 379 mozilla Use mozilla as gecko rendering engine.
341 At most one of the following database options may be selected: 380 At most one of the following database options may be selected:
342 mysql Enable support for MySQL database. 381 mysql Enable support for MySQL database.
343 pgsql Enable support for PostgreSQL database. 382 pgsql Enable support for PostgreSQL database.
344 383
345 These options are enabled by default: firefox 384 These options are enabled by default: firefox
346 These options are currently enabled: mozilla ssl 385 These options are currently enabled: mozilla ssl
347</programlisting> 386</programlisting>
348 387
349 <para>The following variables can be defined in 388 <para>The following variables can be defined in
350 &mk.conf; to select which options to 389 &mk.conf; to select which options to
351 enable for a package: <varname>PKG_DEFAULT_OPTIONS</varname>, 390 enable for a package: <varname>PKG_DEFAULT_OPTIONS</varname>,
352 which can be used to select or disable options for all packages 391 which can be used to select or disable options for all packages
353 that support them, and 392 that support them, and
354 <varname>PKG_OPTIONS.<replaceable>pkgbase</replaceable></varname>, 393 <varname>PKG_OPTIONS.<replaceable>pkgbase</replaceable></varname>,
355 which can be used to select or disable options specifically for 394 which can be used to select or disable options specifically for
356 package <replaceable>pkgbase</replaceable>. Options listed in 395 package <replaceable>pkgbase</replaceable>. Options listed in
357 these variables are selected, options preceded by <quote>-</quote> 396 these variables are selected, options preceded by <quote>-</quote>
358 are disabled. A few examples:</para> 397 are disabled. A few examples:</para>
359 398
360 <screen> 399 <screen>
361&uprompt; <command>grep "PKG.*OPTION" &mk.conf;</command> 400&uprompt; <command>grep "PKG.*OPTION" &mk.conf;</command>
362PKG_DEFAULT_OPTIONS= -arts -dvdread -esound 401PKG_DEFAULT_OPTIONS= -arts -dvdread -esound
363PKG_OPTIONS.kdebase= debug -sasl 402PKG_OPTIONS.kdebase= debug -sasl
364PKG_OPTIONS.apache= suexec </screen> 403PKG_OPTIONS.apache= suexec </screen>
365 404
366 <para>It is important to note that options that were specifically 405 <para>It is important to note that options that were specifically
367 suggested by the package maintainer must be explicitely removed if 406 suggested by the package maintainer must be explicitely removed if
368 you do not wish to include the option. If you are unsure you can view 407 you do not wish to include the option. If you are unsure you can view
369 the current state with <command>make show-options</command>.</para> 408 the current state with <command>make show-options</command>.</para>
370 409
371 <para>The following settings are consulted in the order given, and 410 <para>The following settings are consulted in the order given, and
372 the last setting that selects or disables an option is 411 the last setting that selects or disables an option is
373 used:</para> 412 used:</para>
374 413
375 <orderedlist> 414 <orderedlist>
376 <listitem><para>the default options as suggested by the package 415 <listitem><para>the default options as suggested by the package
377 maintainer</para></listitem> 416 maintainer</para></listitem>
378 417
379 <listitem><para>the options implied by the settings of legacy 418 <listitem><para>the options implied by the settings of legacy
380 variables (see below)</para></listitem> 419 variables (see below)</para></listitem>
381 420
382 <listitem><para><varname>PKG_DEFAULT_OPTIONS</varname></para></listitem> 421 <listitem><para><varname>PKG_DEFAULT_OPTIONS</varname></para></listitem>
383 422
384 <listitem><para><varname>PKG_OPTIONS.<replaceable>pkgbase</replaceable></varname></para></listitem> 423 <listitem><para><varname>PKG_OPTIONS.<replaceable>pkgbase</replaceable></varname></para></listitem>
385 </orderedlist> 424 </orderedlist>
386 425
387 <para>For groups of mutually exclusive options, the last option 426 <para>For groups of mutually exclusive options, the last option
388 selected is used, all others are automatically disabled. If an 427 selected is used, all others are automatically disabled. If an
389 option of the group is explicitly disabled, the previously 428 option of the group is explicitly disabled, the previously
390 selected option, if any, is used. It is an error if no option 429 selected option, if any, is used. It is an error if no option
391 from a required group of options is selected, and building the 430 from a required group of options is selected, and building the
392 package will fail.</para> 431 package will fail.</para>
393 432
394 <para>Before the options framework was introduced, build options 433 <para>Before the options framework was introduced, build options
395 were selected by setting a variable (often named 434 were selected by setting a variable (often named
396 <varname>USE_<replaceable>FOO</replaceable></varname>) in 435 <varname>USE_<replaceable>FOO</replaceable></varname>) in
397 &mk.conf; for each option. To ease 436 &mk.conf; for each option. To ease
398 transition to the options framework for the user, these legacy 437 transition to the options framework for the user, these legacy
399 variables are converted to the appropriate options setting 438 variables are converted to the appropriate options setting
400 (<varname>PKG_OPTIONS.<replaceable>pkgbase</replaceable></varname>) 439 (<varname>PKG_OPTIONS.<replaceable>pkgbase</replaceable></varname>)
401 automatically. A warning is issued to prompt the user to update 440 automatically. A warning is issued to prompt the user to update
402 &mk.conf; to use the options framework 441 &mk.conf; to use the options framework
403 directly. Support for the legacy variables will be removed 442 directly. Support for the legacy variables will be removed
404 eventually.</para> 443 eventually.</para>
405 </sect1> 444 </sect1>
406 445
407</chapter> 446</chapter>
cvs diff -r1.7 -r1.8 pkgsrc/doc/guide/files/creating.xml (switch to unified diff)

--- pkgsrc/doc/guide/files/creating.xml 2007/06/01 11:07:24 1.7
+++ pkgsrc/doc/guide/files/creating.xml 2009/03/05 13:08:02 1.8
@@ -1,382 +1,435 @@ @@ -1,382 +1,435 @@
1<!-- $NetBSD: creating.xml,v 1.7 2007/06/01 11:07:24 rillig Exp $ --> 1<!-- $NetBSD: creating.xml,v 1.8 2009/03/05 13:08:02 imil Exp $ -->
2 2
3<chapter id="creating"> 3<chapter id="creating">
4<title>Creating a new pkgsrc package from scratch</title> 4<title>Creating a new pkgsrc package from scratch</title>
5 5
6<para>When you find a package that is not yet in pkgsrc, you 6<para>When you find a package that is not yet in pkgsrc, you
7most likely have a URL from where you can download the source 7most likely have a URL from where you can download the source
8code. Starting with this URL, creating a package involves only a 8code. Starting with this URL, creating a package involves only a
9few steps.</para> 9few steps.</para>
10 10
11<procedure> 11<procedure>
12 12
13<step><para>First, install the packages <filename 13<step><para>First, install the packages <filename
14role="pkg">pkgtools/url2pkg</filename> and <filename 14role="pkg">pkgtools/url2pkg</filename> and <filename
15role="pkg">pkgtools/pkglint</filename>.</para></step> 15role="pkg">pkgtools/pkglint</filename>.</para></step>
16 16
17<step><para>Then, choose one of the top-level directories as the 17<step><para>Then, choose one of the top-level directories as the
18category in which you want to place your package. You can also create a 18category in which you want to place your package. You can also create a
19directory of your own (maybe called <filename>local</filename>). In that 19directory of your own (maybe called <filename>local</filename>). In that
20category directory, create another directory for your package and change 20category directory, create another directory for your package and change
21into it.</para></step> 21into it.</para></step>
22 22
23<step><para>Run the program <command>url2pkg</command>, which will ask 23<step><para>Run the program <command>url2pkg</command>, which will ask
24you for a URL. Enter the URL of the distribution file (in most cases a 24you for a URL. Enter the URL of the distribution file (in most cases a
25<filename>.tar.gz</filename> file) and watch how the basic ingredients 25<filename>.tar.gz</filename> file) and watch how the basic ingredients
26of your package are created automatically. The distribution file is 26of your package are created automatically. The distribution file is
27extracted automatically to fill in some details in the 27extracted automatically to fill in some details in the
28<filename>Makefile</filename> that would otherwise have to be done 28<filename>Makefile</filename> that would otherwise have to be done
29manually.</para></step> 29manually.</para></step>
30 30
31<step><para>Examine the extracted files to determine the dependencies of 31<step><para>Examine the extracted files to determine the dependencies of
32your package. Ideally, this is mentioned in some 32your package. Ideally, this is mentioned in some
33<filename>README</filename> file, but things may differ. For each of 33<filename>README</filename> file, but things may differ. For each of
34these dependencies, look where it exists in pkgsrc, and if there is a 34these dependencies, look where it exists in pkgsrc, and if there is a
35file called <filename>buildlink3.mk</filename> in that directory, add a 35file called <filename>buildlink3.mk</filename> in that directory, add a
36line to your package <filename>Makefile</filename> which includes that 36line to your package <filename>Makefile</filename> which includes that
37file just before the last line. If the 37file just before the last line. If the
38<filename>buildlink3.mk</filename> file does not exist, add a 38<filename>buildlink3.mk</filename> file does not exist, add a
39<varname>DEPENDS</varname> line to the Makefile, which specifies the 39<varname>DEPENDS</varname> line to the Makefile, which specifies the
40version of the dependency and where it can be found in pkgsrc. This line 40version of the dependency and where it can be found in pkgsrc. This line
41should be placed in the third paragraph. If the dependency is only 41should be placed in the third paragraph. If the dependency is only
42needed for building the package, but not when using it, use 42needed for building the package, but not when using it, use
43<varname>BUILD_DEPENDS</varname> instead of <varname>DEPENDS</varname>. 43<varname>BUILD_DEPENDS</varname> instead of <varname>DEPENDS</varname>.
44Your package may then look like this:</para> 44Your package may then look like this:</para>
45 45
46<programlisting> 46<programlisting>
47[...] 47[...]
48 48
49BUILD_DEPENDS+= lua>=5.0:../../lang/lua 49BUILD_DEPENDS+= lua>=5.0:../../lang/lua
50DEPENDS+= screen-[0-9]*:../../misc/screen 50DEPENDS+= screen-[0-9]*:../../misc/screen
51DEPENDS+= screen>=4.0:../../misc/screen 51DEPENDS+= screen>=4.0:../../misc/screen
52 52
53[...] 53[...]
54 54
55.include "../../<replaceable>category</replaceable>/<replaceable>package</replaceable>/buildlink3.mk" 55.include "../../<replaceable>category</replaceable>/<replaceable>package</replaceable>/buildlink3.mk"
56.include "../../devel/glib2/buildlink3.mk" 56.include "../../devel/glib2/buildlink3.mk"
57.include "../../mk/bsd.pkg.mk" 57.include "../../mk/bsd.pkg.mk"
58</programlisting> 58</programlisting>
59 59
60</step> 60</step>
61 61
62<step><para>Run <command>pkglint</command> to see what things still need 62<step><para>Run <command>pkglint</command> to see what things still need
63to be done to make your package a <quote>good</quote> one. If you don't 63to be done to make your package a <quote>good</quote> one. If you don't
64know what pkglint's warnings want to tell you, try <command>pkglint 64know what pkglint's warnings want to tell you, try <command>pkglint
65--explain</command> or <command>pkglint 65--explain</command> or <command>pkglint
66-e</command>, which outputs additional 66-e</command>, which outputs additional
67explanations.</para></step> 67explanations.</para></step>
68 68
69<step><para>In many cases the package is not yet ready to build. You can 69<step><para>In many cases the package is not yet ready to build. You can
70find instructions for the most common cases in the next section, <xref 70find instructions for the most common cases in the next section, <xref
71linkend="creating.common"/>. After you have followed the instructions 71linkend="creating.common"/>. After you have followed the instructions
72over there, you can hopefully continue here.</para></step> 72over there, you can hopefully continue here.</para></step>
73 73
74<step><para>Run <command>bmake clean</command> to clean the working 74<step><para>Run <command>bmake clean</command> to clean the working
75directory from the extracted files. Besides these files, a lot of cache 75directory from the extracted files. Besides these files, a lot of cache
76files and other system information has been saved in the working 76files and other system information has been saved in the working
77directory, which may become wrong after you edited the 77directory, which may become wrong after you edited the
78<filename>Makefile</filename>.</para></step> 78<filename>Makefile</filename>.</para></step>
79 79
80<step><para>Now, run <command>bmake</command> to build the package. For 80<step><para>Now, run <command>bmake</command> to build the package. For
81the various things that can go wrong in this phase, consult <xref 81the various things that can go wrong in this phase, consult <xref
82linkend="fixes"/>.</para></step> 82linkend="fixes"/>.</para></step>
83 83
84<step><para>When the package builds fine, the next step is to install 84<step><para>When the package builds fine, the next step is to install
85the package. Run <command>bmake install</command> and hope that 85the package. Run <command>bmake install</command> and hope that
86everything works.</para></step> 86everything works.</para></step>
87 87
88<step><para>Up to now, the file <filename>PLIST</filename>, which 88<step><para>Up to now, the file <filename>PLIST</filename>, which
89contains a list of the files that are installed by the package, is 89contains a list of the files that are installed by the package, is
90nearly empty. Run <command>bmake print-PLIST 90nearly empty. Run <command>bmake print-PLIST
91&gt;PLIST</command> to generate a probably correct list. Check 91&gt;PLIST</command> to generate a probably correct list. Check
92the file using your preferred text editor to see if the list of 92the file using your preferred text editor to see if the list of
93files looks plausible.</para></step> 93files looks plausible.</para></step>
94 94
95<step><para>Run <command>pkglint</command> again to see if the generated 95<step><para>Run <command>pkglint</command> again to see if the generated
96<filename>PLIST</filename> contains garbage or not.</para></step> 96<filename>PLIST</filename> contains garbage or not.</para></step>
97 97
98<step><para>When you ran <command>bmake install</command>, the package 98<step><para>When you ran <command>bmake install</command>, the package
99has been registered in the database of installed files, but with an 99has been registered in the database of installed files, but with an
100empty list of files. To fix this, run <command>bmake deinstall</command> 100empty list of files. To fix this, run <command>bmake deinstall</command>
101and <command>bmake install</command> again. Now the package is 101and <command>bmake install</command> again. Now the package is
102registered with the list of files from 102registered with the list of files from
103<filename>PLIST</filename>.</para></step> 103<filename>PLIST</filename>.</para></step>
104 104
105<step><para>Run <command>bmake package</command> to create a binary 105<step><para>Run <command>bmake package</command> to create a binary
106package from the set of installed files.</para></step> 106package from the set of installed files.</para></step>
107 107
108</procedure> 108</procedure>
109 109
110<sect1 id="creating.common"> 110<sect1 id="creating.common">
111<title>Common types of packages</title> 111<title>Common types of packages</title>
112 112
113<sect2 id="creating.perl-module"> 113<sect2 id="creating.perl-module">
114<title>Perl modules</title> 114<title>Perl modules</title>
115 115
116<para>Simple Perl modules are handled automatically by 116<para>Simple Perl modules are handled automatically by
117<command>url2pkg</command>, including dependencies.</para> 117<command>url2pkg</command>, including dependencies.</para>
118 118
119</sect2> 119</sect2>
120 120
121<sect2 id="creating.kde-app"> 121<sect2 id="creating.kde-app">
122<title>KDE applications</title> 122<title>KDE applications</title>
123 123
124<para>KDE applications should always include 124<para>KDE applications should always include
125<filename>meta-pkgs/kde3/kde3.mk</filename>, which contains numerous 125<filename>meta-pkgs/kde3/kde3.mk</filename>, which contains numerous
126settings that are typical of KDE packages.</para> 126settings that are typical of KDE packages.</para>
127 127
128</sect2> 128</sect2>
129 129
 130<sect2 id="creating.python-module">
 131<title>Python modules and programs</title>
 132
 133<para>Python modules and programs packages are easily created using a
 134set of predefined variables.</para>
 135
 136<para>Most Python packages use either <quote>distutils</quote> or
 137easy-setup (<quote>eggs</quote>).
 138If the software uses <quote>distutils</quote>, set the
 139<varname>PYDISTUTILSPKG</varname> variable to <quote>yes</quote> so
 140pkgsrc will make use of this framework.
 141<quote>distutils</quote> uses a script called <filename>setup.py</filename>,
 142if the <quote>distutils</quote> driver is not called
 143<filename>setup.py</filename>, set the <varname>PYSETUP</varname> variable
 144to the name of the script.</para>
 145
 146<para>
 147If the default Python versions are not supported by the software, set the
 148<varname>PYTHON_VERSIONS_ACCEPTED</varname> variable to the Python versions
 149the software is known to work with, from the most recent to the older
 150one, e.g.
 151<programlisting>
 152PYTHON_VERSIONS_ACCEPTED= 25 24 23
 153</programlisting></para>
 154
 155<para>
 156If the packaged software is a Python module, include
 157<quote><filename>../../lang/python/extension.mk</filename></quote>.
 158In this case, the package directory should be called
 159<quote>py-software</quote> and <varname>PKGNAME</varname> should be set to
 160<quote>${PYPKGPREFIX}-${DISTNAME}</quote>, e.g.
 161<programlisting>
 162DISTNAME= foopymodule-1.2.10
 163PKGNAME= ${PYPKGPREFIX}-${DISTNAME}
 164</programlisting></para>
 165
 166<para>If it is an application, also include
 167<quote><filename>../../lang/python/application.mk</filename></quote>
 168before <quote>extension.mk</quote>.</para>
 169
 170<para>If the packaged software, either it is an application or a module, is
 171egg-aware, you only need to include
 172<quote><filename>../../lang/python/egg.mk</filename></quote>.</para>
 173
 174<para>In order to correctly set the path to the Python interpreter, use the
 175<varname>REPLACE_PYTHON</varname> variable and set it to the list of files
 176that must be corrected. For example :
 177<programlisting>
 178REPLACE_PYTHON= ${WRKSRC}/*.py
 179</programlisting></para>
 180
 181</sect2>
 182
130</sect1> 183</sect1>
131 184
132<sect1 id="creating.examples"> 185<sect1 id="creating.examples">
133<title>Examples</title> 186<title>Examples</title>
134 187
135<sect2 id="creating.nvu"> 188<sect2 id="creating.nvu">
136<title>How the www/nvu package came into pkgsrc</title> 189<title>How the www/nvu package came into pkgsrc</title>
137 190
138<sect3 id="creating.nvu.init"> 191<sect3 id="creating.nvu.init">
139<title>The initial package</title> 192<title>The initial package</title>
140 193
141<para>Looking at the file <filename>pkgsrc/doc/TODO</filename>, I saw 194<para>Looking at the file <filename>pkgsrc/doc/TODO</filename>, I saw
142that the <quote>nvu</quote> package has not yet been imported into 195that the <quote>nvu</quote> package has not yet been imported into
143pkgsrc. As the description says it has to do with the web, the obvious 196pkgsrc. As the description says it has to do with the web, the obvious
144choice for the category is <quote>www</quote>.</para> 197choice for the category is <quote>www</quote>.</para>
145 198
146<programlisting> 199<programlisting>
147&uprompt; mkdir www/nvu 200&uprompt; mkdir www/nvu
148&uprompt; cd www/nvu 201&uprompt; cd www/nvu
149</programlisting> 202</programlisting>
150 203
151<para>The web site says that the sources are available as a tar file, so 204<para>The web site says that the sources are available as a tar file, so
152I fed that URL to the <command>url2pkg</command> program:</para> 205I fed that URL to the <command>url2pkg</command> program:</para>
153 206
154<programlisting> 207<programlisting>
155&uprompt; url2pkg http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2 208&uprompt; url2pkg http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
156</programlisting> 209</programlisting>
157 210
158<para>My editor popped up, and I added a <varname>PKGNAME</varname> line 211<para>My editor popped up, and I added a <varname>PKGNAME</varname> line
159below the <varname>DISTNAME</varname> line, as the package name should 212below the <varname>DISTNAME</varname> line, as the package name should
160not have the word <quote>sources</quote> in it. I also filled in the 213not have the word <quote>sources</quote> in it. I also filled in the
161<varname>MAINTAINER</varname>, <varname>HOMEPAGE</varname> and 214<varname>MAINTAINER</varname>, <varname>HOMEPAGE</varname> and
162<varname>COMMENT</varname> fields. Then the package 215<varname>COMMENT</varname> fields. Then the package
163<filename>Makefile</filename> looked like that:</para> 216<filename>Makefile</filename> looked like that:</para>
164 217
165<programlisting> 218<programlisting>
166# &#36;NetBSD&#36; 219# &#36;NetBSD&#36;
167# 220#
168 221
169DISTNAME= nvu-1.0-sources 222DISTNAME= nvu-1.0-sources
170PKGNAME= nvu-1.0 223PKGNAME= nvu-1.0
171CATEGORIES= www 224CATEGORIES= www
172MASTER_SITES= http://cvs.nvu.com/download/ 225MASTER_SITES= http://cvs.nvu.com/download/
173EXTRACT_SUFX= .tar.bz2 226EXTRACT_SUFX= .tar.bz2
174 227
175MAINTAINER= rillig@NetBSD.org 228MAINTAINER= rillig@NetBSD.org
176HOMEPAGE= http://cvs.nvu.com/ 229HOMEPAGE= http://cvs.nvu.com/
177COMMENT= Web Authoring System 230COMMENT= Web Authoring System
178 231
179# url2pkg-marker (please do not remove this line.) 232# url2pkg-marker (please do not remove this line.)
180.include "../../mk/bsd.pkg.mk" 233.include "../../mk/bsd.pkg.mk"
181</programlisting> 234</programlisting>
182 235
183<para>Then, I quit the editor and watched pkgsrc downloading a large 236<para>Then, I quit the editor and watched pkgsrc downloading a large
184source archive:</para> 237source archive:</para>
185 238
186<programlisting> 239<programlisting>
187url2pkg> Running "make makesum" ... 240url2pkg> Running "make makesum" ...
188=> Required installed package digest>=20010302: digest-20060826 found 241=> Required installed package digest>=20010302: digest-20060826 found
189=> Fetching nvu-1.0-sources.tar.bz2 242=> Fetching nvu-1.0-sources.tar.bz2
190Requesting http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2 243Requesting http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
191100% |*************************************| 28992 KB 150.77 KB/s00:00 ETA 244100% |*************************************| 28992 KB 150.77 KB/s00:00 ETA
19229687976 bytes retrieved in 03:12 (150.77 KB/s) 24529687976 bytes retrieved in 03:12 (150.77 KB/s)
193url2pkg> Running "make extract" ... 246url2pkg> Running "make extract" ...
194=> Required installed package digest>=20010302: digest-20060826 found 247=> Required installed package digest>=20010302: digest-20060826 found
195=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2 248=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
196=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2 249=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
197work.bacc -> /tmp/roland/pkgsrc/www/nvu/work.bacc 250work.bacc -> /tmp/roland/pkgsrc/www/nvu/work.bacc
198===> Installing dependencies for nvu-1.0 251===> Installing dependencies for nvu-1.0
199===> Overriding tools for nvu-1.0 252===> Overriding tools for nvu-1.0
200===> Extracting for nvu-1.0 253===> Extracting for nvu-1.0
201url2pkg> Adjusting the Makefile. 254url2pkg> Adjusting the Makefile.
202 255
203Remember to correct CATEGORIES, HOMEPAGE, COMMENT, and DESCR when you're done! 256Remember to correct CATEGORIES, HOMEPAGE, COMMENT, and DESCR when you're done!
204 257
205Good luck! (See pkgsrc/doc/pkgsrc.txt for some more help :-) 258Good luck! (See pkgsrc/doc/pkgsrc.txt for some more help :-)
206</programlisting> 259</programlisting>
207 260
208</sect3> 261</sect3>
209 262
210<sect3 id="creating.nvu.problems"> 263<sect3 id="creating.nvu.problems">
211<title>Fixing all kinds of problems to make the package work</title> 264<title>Fixing all kinds of problems to make the package work</title>
212 265
213<para>Now that the package has been extracted, let's see what's inside 266<para>Now that the package has been extracted, let's see what's inside
214it. The package has a <filename>README.txt</filename>, but that only 267it. The package has a <filename>README.txt</filename>, but that only
215says something about mozilla, so it's probably useless for seeing what 268says something about mozilla, so it's probably useless for seeing what
216dependencies this package has. But since there is a GNU configure script 269dependencies this package has. But since there is a GNU configure script
217in the package, let's hope that it will complain about everything it 270in the package, let's hope that it will complain about everything it
218needs.</para> 271needs.</para>
219 272
220<programlisting> 273<programlisting>
221&uprompt; bmake 274&uprompt; bmake
222=> Required installed package digest>=20010302: digest-20060826 found 275=> Required installed package digest>=20010302: digest-20060826 found
223=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2 276=> Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
224=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2 277=> Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
225===> Patching for nvu-1.0 278===> Patching for nvu-1.0
226===> Creating toolchain wrappers for nvu-1.0 279===> Creating toolchain wrappers for nvu-1.0
227===> Configuring for nvu-1.0 280===> Configuring for nvu-1.0
228[...] 281[...]
229configure: error: Perl 5.004 or higher is required. 282configure: error: Perl 5.004 or higher is required.
230[...] 283[...]
231WARNING: Please add USE_TOOLS+=perl to the package Makefile. 284WARNING: Please add USE_TOOLS+=perl to the package Makefile.
232[...] 285[...]
233</programlisting> 286</programlisting>
234 287
235<para>That worked quite well. So I opened the package Makefile in my 288<para>That worked quite well. So I opened the package Makefile in my
236editor, and since it already has a <varname>USE_TOOLS</varname> line, I 289editor, and since it already has a <varname>USE_TOOLS</varname> line, I
237just appended <quote>perl</quote> to it. Since the dependencies of the 290just appended <quote>perl</quote> to it. Since the dependencies of the
238package have changed now, and since a perl wrapper is automatically 291package have changed now, and since a perl wrapper is automatically
239installed in the <quote>tools</quote> phase, I need to build the package 292installed in the <quote>tools</quote> phase, I need to build the package
240from scratch.</para> 293from scratch.</para>
241 294
242<programlisting> 295<programlisting>
243&uprompt; bmake clean 296&uprompt; bmake clean
244===> Cleaning for nvu-1.0 297===> Cleaning for nvu-1.0
245&uprompt; bmake 298&uprompt; bmake
246[...] 299[...]
247*** /tmp/roland/pkgsrc/www/nvu/work.bacc/.tools/bin/make is not \ 300*** /tmp/roland/pkgsrc/www/nvu/work.bacc/.tools/bin/make is not \
248GNU Make. You will not be able to build Mozilla without GNU Make. 301GNU Make. You will not be able to build Mozilla without GNU Make.
249[...] 302[...]
250</programlisting> 303</programlisting>
251 304
252<para>So I added <quote>gmake</quote> to the 305<para>So I added <quote>gmake</quote> to the
253<varname>USE_TOOLS</varname> line and tried again (from scratch).</para> 306<varname>USE_TOOLS</varname> line and tried again (from scratch).</para>
254 307
255<programlisting> 308<programlisting>
256[...] 309[...]
257checking for GTK - version >= 1.2.0... no 310checking for GTK - version >= 1.2.0... no
258*** Could not run GTK test program, checking why... 311*** Could not run GTK test program, checking why...
259[...] 312[...]
260</programlisting> 313</programlisting>
261 314
262<para>Now to the other dependencies. The first question is: Where is the 315<para>Now to the other dependencies. The first question is: Where is the
263GTK package hidden in pkgsrc?</para> 316GTK package hidden in pkgsrc?</para>
264 317
265<programlisting> 318<programlisting>
266&uprompt; echo ../../*/gtk* 319&uprompt; echo ../../*/gtk*
267[many packages ...] 320[many packages ...]
268&uprompt; echo ../../*/gtk 321&uprompt; echo ../../*/gtk
269../../x11/gtk 322../../x11/gtk
270&uprompt; echo ../../*/gtk2 323&uprompt; echo ../../*/gtk2
271../../x11/gtk2 324../../x11/gtk2
272&uprompt; echo ../../*/gtk2/bui* 325&uprompt; echo ../../*/gtk2/bui*
273../../x11/gtk2/buildlink3.mk 326../../x11/gtk2/buildlink3.mk
274</programlisting> 327</programlisting>
275 328
276<para>The first try was definitely too broad. The second one had exactly 329<para>The first try was definitely too broad. The second one had exactly
277one result, which is very good. But there is one pitfall with GNOME 330one result, which is very good. But there is one pitfall with GNOME
278packages. Before GNOME 2 had been released, there were already many 331packages. Before GNOME 2 had been released, there were already many
279GNOME 1 packages in pkgsrc. To be able to continue to use these 332GNOME 1 packages in pkgsrc. To be able to continue to use these
280packages, the GNOME 2 packages were imported as separate packages, and 333packages, the GNOME 2 packages were imported as separate packages, and
281their names usually have a <quote>2</quote> appended. So I checked 334their names usually have a <quote>2</quote> appended. So I checked
282whether this was the case here, and indeed it was.</para> 335whether this was the case here, and indeed it was.</para>
283 336
284<para>Since the GTK2 package has a <filename>buildlink3.mk</filename> 337<para>Since the GTK2 package has a <filename>buildlink3.mk</filename>
285file, adding the dependency is very easy. I just inserted an 338file, adding the dependency is very easy. I just inserted an
286<literal>.include</literal> line before the last line of the package 339<literal>.include</literal> line before the last line of the package
287<filename>Makefile</filename>, so that it now looks like this:</para> 340<filename>Makefile</filename>, so that it now looks like this:</para>
288 341
289<programlisting> 342<programlisting>
290[...] 343[...]
291.include "../../x11/gtk2/buildlink3.mk" 344.include "../../x11/gtk2/buildlink3.mk"
292.include "../../mk/bsd.pkg.mk 345.include "../../mk/bsd.pkg.mk
293</programlisting> 346</programlisting>
294 347
295<para>After another <command>bmake clean && bmake</command>, the answer 348<para>After another <command>bmake clean && bmake</command>, the answer
296was:</para> 349was:</para>
297 350
298<programlisting> 351<programlisting>
299[...] 352[...]
300checking for gtk-config... /home/roland/pkg/bin/gtk-config 353checking for gtk-config... /home/roland/pkg/bin/gtk-config
301checking for GTK - version >= 1.2.0... no 354checking for GTK - version >= 1.2.0... no
302*** Could not run GTK test program, checking why... 355*** Could not run GTK test program, checking why...
303*** The test program failed to compile or link. See the file config.log for the 356*** The test program failed to compile or link. See the file config.log for the
304*** exact error that occured. This usually means GTK was incorrectly installed 357*** exact error that occured. This usually means GTK was incorrectly installed
305*** or that you have moved GTK since it was installed. In the latter case, you 358*** or that you have moved GTK since it was installed. In the latter case, you
306*** may want to edit the gtk-config script: /home/roland/pkg/bin/gtk-config 359*** may want to edit the gtk-config script: /home/roland/pkg/bin/gtk-config
307configure: error: Test for GTK failed. 360configure: error: Test for GTK failed.
308[...] 361[...]
309</programlisting> 362</programlisting>
310 363
311<para>In this particular case, the assumption that <quote>every package 364<para>In this particular case, the assumption that <quote>every package
312prefers GNOME 2</quote> had been wrong. The first of the lines above 365prefers GNOME 2</quote> had been wrong. The first of the lines above
313told me that this package really wanted to have the GNOME 1 version of 366told me that this package really wanted to have the GNOME 1 version of
314GTK. If the package had looked for GTK2, it would have looked for 367GTK. If the package had looked for GTK2, it would have looked for
315<command>pkg-config</command> instead of <command>gtk-config</command>. 368<command>pkg-config</command> instead of <command>gtk-config</command>.
316So I changed the <literal>x11/gtk2</literal> to 369So I changed the <literal>x11/gtk2</literal> to
317<literal>x11/gtk</literal> in the package <filename>Makefile</filename>, 370<literal>x11/gtk</literal> in the package <filename>Makefile</filename>,
318and tried again.</para> 371and tried again.</para>
319 372
320<programlisting> 373<programlisting>
321[...] 374[...]
322cc -o xpidl.o -c -DOSTYPE=\"NetBSD3\" -DOSARCH=\"NetBSD\" -I../../../dist/include/xpcom -I../../../dist/include -I/tmp/roland/pkgsrc/www/nvu/work.bacc/mozilla/dist/include/nspr -I/usr/X11R6/include -fPIC -DPIC -I/home/roland/pkg/include -I/usr/include -I/usr/X11R6/include -Wall -W -Wno-unused -Wpointer-arith -Wcast-align -Wno-long-long -pedantic -O2 -I/home/roland/pkg/include -I/usr/include -Dunix -pthread -pipe -DDEBUG -D_DEBUG -DDEBUG_roland -DTRACING -g -I/home/roland/pkg/include/glib/glib-1.2 -I/home/roland/pkg/lib/glib/include -I/usr/pkg/include/orbit-1.0 -I/home/roland/pkg/include -I/usr/include -I/usr/X11R6/include -include ../../../mozilla-config.h -DMOZILLA_CLIENT -Wp,-MD,.deps/xpidl.pp xpidl.c 375cc -o xpidl.o -c -DOSTYPE=\"NetBSD3\" -DOSARCH=\"NetBSD\" -I../../../dist/include/xpcom -I../../../dist/include -I/tmp/roland/pkgsrc/www/nvu/work.bacc/mozilla/dist/include/nspr -I/usr/X11R6/include -fPIC -DPIC -I/home/roland/pkg/include -I/usr/include -I/usr/X11R6/include -Wall -W -Wno-unused -Wpointer-arith -Wcast-align -Wno-long-long -pedantic -O2 -I/home/roland/pkg/include -I/usr/include -Dunix -pthread -pipe -DDEBUG -D_DEBUG -DDEBUG_roland -DTRACING -g -I/home/roland/pkg/include/glib/glib-1.2 -I/home/roland/pkg/lib/glib/include -I/usr/pkg/include/orbit-1.0 -I/home/roland/pkg/include -I/usr/include -I/usr/X11R6/include -include ../../../mozilla-config.h -DMOZILLA_CLIENT -Wp,-MD,.deps/xpidl.pp xpidl.c
323In file included from xpidl.c:42: 376In file included from xpidl.c:42:
324xpidl.h:53:24: libIDL/IDL.h: No such file or directory 377xpidl.h:53:24: libIDL/IDL.h: No such file or directory
325In file included from xpidl.c:42: 378In file included from xpidl.c:42:
326xpidl.h:132: error: parse error before "IDL_ns" 379xpidl.h:132: error: parse error before "IDL_ns"
327[...] 380[...]
328</programlisting> 381</programlisting>
329 382
330<para>The package still does not find all of its dependencies. Now the 383<para>The package still does not find all of its dependencies. Now the
331question is: Which package provides the 384question is: Which package provides the
332<filename>libIDL/IDL.h</filename> header file?</para> 385<filename>libIDL/IDL.h</filename> header file?</para>
333 386
334<programlisting> 387<programlisting>
335&uprompt; echo ../../*/*idl* 388&uprompt; echo ../../*/*idl*
336../../devel/py-idle ../../wip/idled ../../x11/acidlaunch 389../../devel/py-idle ../../wip/idled ../../x11/acidlaunch
337&uprompt; echo ../../*/*IDL* 390&uprompt; echo ../../*/*IDL*
338../../net/libIDL 391../../net/libIDL
339</programlisting> 392</programlisting>
340 393
341<para>Let's take the one from the second try. So I included the 394<para>Let's take the one from the second try. So I included the
342<filename>../../net/libIDL/buildlink3.mk</filename> file and tried 395<filename>../../net/libIDL/buildlink3.mk</filename> file and tried
343again. But the error didn't change. After digging through some of the 396again. But the error didn't change. After digging through some of the
344code, I concluded that the build process of the package was broken and 397code, I concluded that the build process of the package was broken and
345couldn't have ever worked, but since the Mozilla source tree is quite 398couldn't have ever worked, but since the Mozilla source tree is quite
346large, I didn't want to fix it. So I added the following to the package 399large, I didn't want to fix it. So I added the following to the package
347<filename>Makefile</filename> and tried again:</para> 400<filename>Makefile</filename> and tried again:</para>
348 401
349<programlisting> 402<programlisting>
350CPPFLAGS+= -I${BUILDLINK_PREFIX.libIDL}/include/libIDL-2.0 403CPPFLAGS+= -I${BUILDLINK_PREFIX.libIDL}/include/libIDL-2.0
351BUILDLINK_TRANSFORM+= -l:IDL:IDL-2 404BUILDLINK_TRANSFORM+= -l:IDL:IDL-2
352</programlisting> 405</programlisting>
353 406
354<para>The latter line is needed because the package expects the library 407<para>The latter line is needed because the package expects the library
355<filename>libIDL.so</filename>, but only 408<filename>libIDL.so</filename>, but only
356<filename>libIDL-2.so</filename> is available. So I told the compiler 409<filename>libIDL-2.so</filename> is available. So I told the compiler
357wrapper to rewrite that on the fly.</para> 410wrapper to rewrite that on the fly.</para>
358 411
359<para>The next problem was related to a recent change of the FreeType 412<para>The next problem was related to a recent change of the FreeType
360interface. I looked up in <filename role="pkg">www/seamonkey</filename> 413interface. I looked up in <filename role="pkg">www/seamonkey</filename>
361which patch files were relevant for this issue and copied them to the 414which patch files were relevant for this issue and copied them to the
362<filename>patches</filename> directory. Then I retried, fixed the 415<filename>patches</filename> directory. Then I retried, fixed the
363patches so that they applied cleanly and retried again. This time, 416patches so that they applied cleanly and retried again. This time,
364everything worked.</para> 417everything worked.</para>
365 418
366</sect3> 419</sect3>
367 420
368<sect3 id="creating.nvu.inst"> 421<sect3 id="creating.nvu.inst">
369<title>Installing the package</title> 422<title>Installing the package</title>
370 423
371<programlisting> 424<programlisting>
372&uprompt; bmake CHECK_FILES=no install 425&uprompt; bmake CHECK_FILES=no install
373[...] 426[...]
374&uprompt; bmake print-PLIST >PLIST 427&uprompt; bmake print-PLIST >PLIST
375&uprompt; bmake deinstall 428&uprompt; bmake deinstall
376&uprompt; bmake install 429&uprompt; bmake install
377</programlisting> 430</programlisting>
378 431
379</sect3> 432</sect3>
380</sect2> 433</sect2>
381</sect1> 434</sect1>
382</chapter> 435</chapter>