| @@ -1,1932 +1,1933 @@ | | | @@ -1,1932 +1,1933 @@ |
1 | <!-- $NetBSD: fixes.xml,v 1.96 2009/02/23 17:45:17 joerg Exp $ --> | | 1 | <!-- $NetBSD: fixes.xml,v 1.97 2009/03/08 15:55:32 wiz Exp $ --> |
2 | | | 2 | |
3 | <chapter id="fixes"> <?dbhtml filename="fixes.html"?> | | 3 | <chapter id="fixes"> <?dbhtml filename="fixes.html"?> |
4 | <title>Making your package work</title> | | 4 | <title>Making your package work</title> |
5 | | | 5 | |
6 | <sect1 id="general-operation"> | | 6 | <sect1 id="general-operation"> |
7 | <title>General operation</title> | | 7 | <title>General operation</title> |
8 | | | 8 | |
9 | <sect2 id="portability-of-packages"> | | 9 | <sect2 id="portability-of-packages"> |
10 | <title>Portability of packages</title> | | 10 | <title>Portability of packages</title> |
11 | | | 11 | |
12 | <para>One appealing feature of pkgsrc is that it runs on many | | 12 | <para>One appealing feature of pkgsrc is that it runs on many |
13 | different platforms. As a result, it is important to ensure, | | 13 | different platforms. As a result, it is important to ensure, |
14 | where possible, that packages in pkgsrc are portable. This | | 14 | where possible, that packages in pkgsrc are portable. This |
15 | chapter mentions some particular details you should pay | | 15 | chapter mentions some particular details you should pay |
16 | attention to while working on pkgsrc.</para> | | 16 | attention to while working on pkgsrc.</para> |
17 | </sect2> | | 17 | </sect2> |
18 | | | 18 | |
19 | <sect2 id="pulling-vars-from-etc-mk.conf"> | | 19 | <sect2 id="pulling-vars-from-etc-mk.conf"> |
20 | <title>How to pull in user-settable variables from &mk.conf;</title> | | 20 | <title>How to pull in user-settable variables from &mk.conf;</title> |
21 | | | 21 | |
22 | <para>The pkgsrc user can configure pkgsrc by overriding several | | 22 | <para>The pkgsrc user can configure pkgsrc by overriding several |
23 | variables in the file pointed to by <varname>MAKECONF</varname>, | | 23 | variables in the file pointed to by <varname>MAKECONF</varname>, |
24 | which is &mk.conf; by default. When you | | 24 | which is &mk.conf; by default. When you |
25 | want to use those variables in the preprocessor directives of | | 25 | want to use those variables in the preprocessor directives of |
26 | &man.make.1; (for example <literal>.if</literal> or | | 26 | &man.make.1; (for example <literal>.if</literal> or |
27 | <literal>.for</literal>), you need to include the file | | 27 | <literal>.for</literal>), you need to include the file |
28 | <filename>../../mk/bsd.prefs.mk</filename> before, which in turn | | 28 | <filename>../../mk/bsd.prefs.mk</filename> before, which in turn |
29 | loads the user preferences.</para> | | 29 | loads the user preferences.</para> |
30 | | | 30 | |
31 | <para>But note that some variables may not be completely defined | | 31 | <para>But note that some variables may not be completely defined |
32 | after <filename>../../mk/bsd.prefs.mk</filename> has been | | 32 | after <filename>../../mk/bsd.prefs.mk</filename> has been |
33 | included, as they may contain references to variables that are | | 33 | included, as they may contain references to variables that are |
34 | not yet defined. In shell commands this is no problem, since | | 34 | not yet defined. In shell commands this is no problem, since |
35 | variables are actually macros, which are only expanded when they | | 35 | variables are actually macros, which are only expanded when they |
36 | are used. But in the preprocessor directives mentioned above and | | 36 | are used. But in the preprocessor directives mentioned above and |
37 | in dependency lines (of the form <literal>target: | | 37 | in dependency lines (of the form <literal>target: |
38 | dependencies</literal>) the variables are expanded at load | | 38 | dependencies</literal>) the variables are expanded at load |
39 | time.</para> | | 39 | time.</para> |
40 | | | 40 | |
41 | <note><para>Currently there is no exhaustive list of all | | 41 | <note><para>Currently there is no exhaustive list of all |
42 | variables that tells you whether they can be used at load time | | 42 | variables that tells you whether they can be used at load time |
43 | or only at run time, but it is in preparation.</para></note> | | 43 | or only at run time, but it is in preparation.</para></note> |
44 | </sect2> | | 44 | </sect2> |
45 | | | 45 | |
46 | <sect2 id="user-interaction"> | | 46 | <sect2 id="user-interaction"> |
47 | <title>User interaction</title> | | 47 | <title>User interaction</title> |
48 | | | 48 | |
49 | <para>Occasionally, packages require interaction from the user, | | 49 | <para>Occasionally, packages require interaction from the user, |
50 | and this can be in a number of ways:</para> | | 50 | and this can be in a number of ways:</para> |
51 | | | 51 | |
52 | <itemizedlist> | | 52 | <itemizedlist> |
53 | | | 53 | |
54 | <listitem> | | 54 | <listitem> |
55 | <para>When fetching the distfiles, some packages require user | | 55 | <para>When fetching the distfiles, some packages require user |
56 | interaction such as entering username/password or accepting a | | 56 | interaction such as entering username/password or accepting a |
57 | license on a web page.</para> | | 57 | license on a web page.</para> |
58 | </listitem> | | 58 | </listitem> |
59 | | | 59 | |
60 | <listitem> | | 60 | <listitem> |
61 | <para>When extracting the distfiles, some packages may ask for | | 61 | <para>When extracting the distfiles, some packages may ask for |
62 | passwords.</para> | | 62 | passwords.</para> |
63 | </listitem> | | 63 | </listitem> |
64 | | | 64 | |
65 | <listitem> | | 65 | <listitem> |
66 | <para>help to configure the package before it is built</para> | | 66 | <para>help to configure the package before it is built</para> |
67 | </listitem> | | 67 | </listitem> |
68 | | | 68 | |
69 | <listitem> | | 69 | <listitem> |
70 | <para>help during the build process</para> | | 70 | <para>help during the build process</para> |
71 | </listitem> | | 71 | </listitem> |
72 | | | 72 | |
73 | <listitem> | | 73 | <listitem> |
74 | <para>help during the installation of a package</para> | | 74 | <para>help during the installation of a package</para> |
75 | </listitem> | | 75 | </listitem> |
76 | </itemizedlist> | | 76 | </itemizedlist> |
77 | | | 77 | |
78 | <para>The <varname>INTERACTIVE_STAGE</varname> definition is | | 78 | <para>The <varname>INTERACTIVE_STAGE</varname> definition is |
79 | provided to notify the pkgsrc mechanism of an interactive stage | | 79 | provided to notify the pkgsrc mechanism of an interactive stage |
80 | which will be needed, and this should be set in the package's | | 80 | which will be needed, and this should be set in the package's |
81 | <filename>Makefile</filename>, e.g.:</para> | | 81 | <filename>Makefile</filename>, e.g.:</para> |
82 | | | 82 | |
83 | <programlisting> | | 83 | <programlisting> |
84 | INTERACTIVE_STAGE= build | | 84 | INTERACTIVE_STAGE= build |
85 | </programlisting> | | 85 | </programlisting> |
86 | | | 86 | |
87 | <para>Multiple interactive stages can be specified:</para> | | 87 | <para>Multiple interactive stages can be specified:</para> |
88 | | | 88 | |
89 | <programlisting> | | 89 | <programlisting> |
90 | INTERACTIVE_STAGE= configure install | | 90 | INTERACTIVE_STAGE= configure install |
91 | </programlisting> | | 91 | </programlisting> |
92 | | | 92 | |
93 | <para>The user can then decide to skip this package by setting the | | 93 | <para>The user can then decide to skip this package by setting the |
94 | <varname>BATCH</varname> variable.</para> | | 94 | <varname>BATCH</varname> variable.</para> |
95 | </sect2> | | 95 | </sect2> |
96 | | | 96 | |
97 | <sect2 id="handling-licenses"> | | 97 | <sect2 id="handling-licenses"> |
98 | <title>Handling licenses</title> | | 98 | <title>Handling licenses</title> |
99 | | | 99 | |
100 | <para>Authors of software can choose the licence under which | | 100 | <para>Authors of software can choose the licence under which |
101 | software can be copied. This is due to copyright law, and reasons | | 101 | software can be copied. This is due to copyright law, and reasons |
102 | for license choices are outside the scope of pkgsrc. The pkgsrc | | 102 | for license choices are outside the scope of pkgsrc. The pkgsrc |
103 | system recognizes that there are a number of licenses which some | | 103 | system recognizes that there are a number of licenses which some |
104 | users may find objectionable or difficult or impossible to comply | | 104 | users may find objectionable or difficult or impossible to comply |
105 | with. The Free Software Foundation has declared some licenses | | 105 | with. The Free Software Foundation has declared some licenses |
106 | "Free", and the Open Source Initiative has a definition of "Open | | 106 | "Free", and the Open Source Initiative has a definition of "Open |
107 | Source". The pkgsrc system, as a policy choice, does not label | | 107 | Source". The pkgsrc system, as a policy choice, does not label |
108 | packages which have licenses that are Free or Open Source. | | 108 | packages which have licenses that are Free or Open Source. |
109 | However, packages without a license meeting either of those tests | | 109 | However, packages without a license meeting either of those tests |
110 | are labeled with a license tag denoting the license. Note that a | | 110 | are labeled with a license tag denoting the license. Note that a |
111 | package with no license to copy trivially does not meet either the | | 111 | package with no license to copy trivially does not meet either the |
112 | Free or Open Source test.</para> | | 112 | Free or Open Source test.</para> |
113 | | | 113 | |
114 | <para>For packages which are not Free or Open Source, pkgsrc will | | 114 | <para>For packages which are not Free or Open Source, pkgsrc will |
115 | not build the package unless the user has indicated to pkgsrc that | | 115 | not build the package unless the user has indicated to pkgsrc that |
116 | packages with that particular license may be built. Note that | | 116 | packages with that particular license may be built. Note that |
117 | this documentation avoids the term "accepted the license". The | | 117 | this documentation avoids the term "accepted the license". The |
118 | pkgsrc system is merely providing a mechanism to avoid | | 118 | pkgsrc system is merely providing a mechanism to avoid |
119 | accidentally building a package with a non-free license; | | 119 | accidentally building a package with a non-free license; |
120 | judgement and responsibility remain with the user. (Installation | | 120 | judgement and responsibility remain with the user. (Installation |
121 | of binary packages are not currently subject to this mechanism; | | 121 | of binary packages are not currently subject to this mechanism; |
122 | this is a bug.)</para> | | 122 | this is a bug.)</para> |
123 | | | 123 | |
124 | <para>One might want to only install packages with a BSD license, | | 124 | <para>One might want to only install packages with a BSD license, |
125 | or the GPL, and not the other. The pkgsrc license tag mechanism | | 125 | or the GPL, and not the other. The pkgsrc license tag mechanism |
126 | does not provide a way to do this. It might be possible to put in | | 126 | does not provide a way to do this. It might be possible to put in |
127 | tags for free licenses, and have a default | | 127 | tags for free licenses, and have a default |
128 | <varname>ACCEPTABLE_LICENSES</varname> variable value, but this is | | 128 | <varname>ACCEPTABLE_LICENSES</varname> variable value, but this is |
129 | widely viewed as having a very poor ratio of benefit to | | 129 | widely viewed as having a very poor ratio of benefit to |
130 | work.</para> | | 130 | work.</para> |
131 | | | 131 | |
132 | <para>The license tag mechanism is intended to address | | 132 | <para>The license tag mechanism is intended to address |
133 | copyright-related issues surrounding building, installing and | | 133 | copyright-related issues surrounding building, installing and |
134 | using a package, and not to address redistribution issues (see | | 134 | using a package, and not to address redistribution issues (see |
135 | <varname>RESTRICTED</varname> and | | 135 | <varname>RESTRICTED</varname> and |
136 | <varname>NO_SRC_ON_FTP</varname>, etc.). However, the above | | 136 | <varname>NO_SRC_ON_FTP</varname>, etc.). However, the above |
137 | definition of licenses for which tags are not needed implies | | 137 | definition of licenses for which tags are not needed implies |
138 | that packages with redistribution restrictions should have | | 138 | that packages with redistribution restrictions should have |
139 | tags, because Free or Open Source programs do not have | | 139 | tags, because Free or Open Source programs do not have |
140 | redistribution restrictions.</para> | | 140 | redistribution restrictions.</para> |
141 | | | 141 | |
142 | <para>Denoting that a package may be copied according to a | | 142 | <para>Denoting that a package may be copied according to a |
143 | particular license is done by placing the license in | | 143 | particular license is done by placing the license in |
144 | <filename>pkgsrc/licenses</filename> and setting the | | 144 | <filename>pkgsrc/licenses</filename> and setting the |
145 | <varname>LICENSE</varname> variable to a string identifying the | | 145 | <varname>LICENSE</varname> variable to a string identifying the |
146 | license, e.g. in <filename | | 146 | license, e.g. in <filename |
147 | role="pkg">graphics/xv</filename>:</para> | | 147 | role="pkg">graphics/xv</filename>:</para> |
148 | | | 148 | |
149 | <programlisting> | | 149 | <programlisting> |
150 | LICENSE= xv-license | | 150 | LICENSE= xv-license |
151 | </programlisting> | | 151 | </programlisting> |
152 | | | 152 | |
153 | <para>When trying to build, the user will get a notice that the | | 153 | <para>When trying to build, the user will get a notice that the |
154 | package is covered by a license which has not been placed in the | | 154 | package is covered by a license which has not been placed in the |
155 | <varname>ACCEPTABLE_LICENSES</varname> variable:</para> | | 155 | <varname>ACCEPTABLE_LICENSES</varname> variable:</para> |
156 | | | 156 | |
157 | <programlisting> | | 157 | <programlisting> |
158 | &cprompt; <userinput>make</userinput> | | 158 | &cprompt; <userinput>make</userinput> |
159 | ===> xv-3.10anb9 has an unacceptable license: xv-license. | | 159 | ===> xv-3.10anb9 has an unacceptable license: xv-license. |
160 | ===> To view the license, enter "/usr/bin/make show-license". | | 160 | ===> To view the license, enter "/usr/bin/make show-license". |
161 | ===> To indicate acceptance, add this line to your /etc/mk.conf: | | 161 | ===> To indicate acceptance, add this line to your /etc/mk.conf: |
162 | ===> ACCEPTABLE_LICENSES+=xv-license | | 162 | ===> ACCEPTABLE_LICENSES+=xv-license |
163 | *** Error code 1 | | 163 | *** Error code 1 |
164 | </programlisting> | | 164 | </programlisting> |
165 | | | 165 | |
166 | <para>The license can be viewed with <command>make | | 166 | <para>The license can be viewed with <command>make |
167 | show-license</command>, and if the user so chooses, the line | | 167 | show-license</command>, and if the user so chooses, the line |
168 | printed above can be added to &mk.conf; to | | 168 | printed above can be added to &mk.conf; to |
169 | convey to pkgsrc that it should not in the future fail because of | | 169 | convey to pkgsrc that it should not in the future fail because of |
170 | that license:</para> | | 170 | that license:</para> |
171 | | | 171 | |
172 | <programlisting> | | 172 | <programlisting> |
173 | ACCEPTABLE_LICENSES+=xv-license | | 173 | ACCEPTABLE_LICENSES+=xv-license |
174 | </programlisting> | | 174 | </programlisting> |
175 | | | 175 | |
176 | <para>When adding a package with a new license, the license text | | 176 | <para>When adding a package with a new license, the license text |
177 | should be added to <filename>pkgsrc/licenses</filename> for | | 177 | should be added to <filename>pkgsrc/licenses</filename> for |
178 | displaying. A list of known licenses can be seen in this | | 178 | displaying. A list of known licenses can be seen in this |
179 | directory.</para> | | 179 | directory.</para> |
180 | | | 180 | |
181 | <para>When the license changes (in a way other than formatting), | | 181 | <para>When the license changes (in a way other than formatting), |
182 | please make sure that the new license has a different name (e.g., | | 182 | please make sure that the new license has a different name (e.g., |
183 | append the version number if it exists, or the date). Just | | 183 | append the version number if it exists, or the date). Just |
184 | because a user told pkgsrc to build programs under a previous | | 184 | because a user told pkgsrc to build programs under a previous |
185 | version of a license does not mean that pkgsrc should build | | 185 | version of a license does not mean that pkgsrc should build |
186 | programs under the new licenses. The higher-level point is that | | 186 | programs under the new licenses. The higher-level point is that |
187 | pkgsrc does not evaluate licenses for reasonableness; the only | | 187 | pkgsrc does not evaluate licenses for reasonableness; the only |
188 | test is a mechanistic test of whether a particular text has been | | 188 | test is a mechanistic test of whether a particular text has been |
189 | approved by either of two bodies.</para> | | 189 | approved by either of two bodies.</para> |
190 | | | 190 | |
191 | <para>The use of <varname>LICENSE=shareware</varname>, | | 191 | <para>The use of <varname>LICENSE=shareware</varname>, |
192 | <varname>LICENSE=no-commercial-use</varname>, and similar language | | 192 | <varname>LICENSE=no-commercial-use</varname>, and similar language |
193 | is deprecated because it does not crisply refer to a particular | | 193 | is deprecated because it does not crisply refer to a particular |
194 | license text. Another problem with such usage is that it does not | | 194 | license text. Another problem with such usage is that it does not |
195 | enable a user to tell pkgsrc to proceed for a single package | | 195 | enable a user to tell pkgsrc to proceed for a single package |
196 | without also telling pkgsrc to proceed for all packages with that | | 196 | without also telling pkgsrc to proceed for all packages with that |
197 | tag.</para> </sect2> | | 197 | tag.</para> </sect2> |
198 | | | 198 | |
199 | <sect2 id="restricted-packages"> | | 199 | <sect2 id="restricted-packages"> |
200 | <title>Restricted packages</title> | | 200 | <title>Restricted packages</title> |
201 | | | 201 | |
202 | <para>Some licenses restrict how software may be re-distributed. | | 202 | <para>Some licenses restrict how software may be re-distributed. |
203 | Because a license tag is required unless the package is Free or | | 203 | Because a license tag is required unless the package is Free or |
204 | Open Source, all packages with restrictions should have license | | 204 | Open Source, all packages with restrictions should have license |
205 | tags. By declaring the restrictions, package tools can | | 205 | tags. By declaring the restrictions, package tools can |
206 | automatically refrain from e.g. placing binary packages on FTP | | 206 | automatically refrain from e.g. placing binary packages on FTP |
207 | sites.</para> | | 207 | sites.</para> |
208 | | | 208 | |
209 | <para>There are four restrictions that may be encoded, which are | | 209 | <para>There are four restrictions that may be encoded, which are |
210 | the cross product of sources (distfiles) and binaries not being | | 210 | the cross product of sources (distfiles) and binaries not being |
211 | placed on FTP sites and CD-ROMs. Because this is rarely the exact | | 211 | placed on FTP sites and CD-ROMs. Because this is rarely the exact |
212 | language in any license, and because non-Free licenses tend to be | | 212 | language in any license, and because non-Free licenses tend to be |
213 | different from each other, pkgsrc adopts a definition of FTP and | | 213 | different from each other, pkgsrc adopts a definition of FTP and |
214 | CD-ROM. Pkgsrc uses "FTP" to mean that the source or binary file | | 214 | CD-ROM. Pkgsrc uses "FTP" to mean that the source or binary file |
215 | should not be made available over the Internet at no charge. | | 215 | should not be made available over the Internet at no charge. |
216 | Pkgsrc uses "CD-ROM" to mean that the source or binary may not be | | 216 | Pkgsrc uses "CD-ROM" to mean that the source or binary may not be |
217 | made available on some kind of media, together with other source | | 217 | made available on some kind of media, together with other source |
218 | and binary packages, and which is sold for a distribution charge. | | 218 | and binary packages, and which is sold for a distribution charge. |
219 | </para> | | 219 | </para> |
220 | | | 220 | |
221 | <para>In order to encode these restrictions, the package system | | 221 | <para>In order to encode these restrictions, the package system |
222 | defines five make variables that can be set to note these | | 222 | defines five make variables that can be set to note these |
223 | restrictions:</para> | | 223 | restrictions:</para> |
224 | | | 224 | |
225 | <itemizedlist> | | 225 | <itemizedlist> |
226 | <listitem> | | 226 | <listitem> |
227 | <para><varname>RESTRICTED</varname></para> | | 227 | <para><varname>RESTRICTED</varname></para> |
228 | | | 228 | |
229 | <para>This variable should be set whenever a restriction | | 229 | <para>This variable should be set whenever a restriction |
230 | exists (regardless of its kind). Set this variable to a | | 230 | exists (regardless of its kind). Set this variable to a |
231 | string containing the reason for the restriction. It should | | 231 | string containing the reason for the restriction. It should |
232 | be understood that those wanting to understand the restriction | | 232 | be understood that those wanting to understand the restriction |
233 | will have to read the license, and perhaps seek advice of | | 233 | will have to read the license, and perhaps seek advice of |
234 | counsel.</para> | | 234 | counsel.</para> |
235 | </listitem> | | 235 | </listitem> |
236 | | | 236 | |
237 | <listitem> | | 237 | <listitem> |
238 | <para><varname>NO_BIN_ON_CDROM</varname></para> | | 238 | <para><varname>NO_BIN_ON_CDROM</varname></para> |
239 | | | 239 | |
240 | <para>Binaries may not be placed on CD-ROM containing other | | 240 | <para>Binaries may not be placed on CD-ROM containing other |
241 | binary packages, for which a distribution charge may be made. | | 241 | binary packages, for which a distribution charge may be made. |
242 | In this case, set this variable to | | 242 | In this case, set this variable to |
243 | <varname>${RESTRICTED}</varname>.</para> | | 243 | <varname>${RESTRICTED}</varname>.</para> |
244 | </listitem> | | 244 | </listitem> |
245 | | | 245 | |
246 | <listitem> | | 246 | <listitem> |
247 | <para><varname>NO_BIN_ON_FTP</varname></para> | | 247 | <para><varname>NO_BIN_ON_FTP</varname></para> |
248 | | | 248 | |
249 | <para>Binaries may not made available on the Internet without | | 249 | <para>Binaries may not made available on the Internet without |
250 | charge. In this case, set this variable to | | 250 | charge. In this case, set this variable to |
251 | <varname>${RESTRICTED}</varname>. If this variable is set, | | 251 | <varname>${RESTRICTED}</varname>. If this variable is set, |
252 | binary packages will not be included on ftp.NetBSD.org.</para> | | 252 | binary packages will not be included on ftp.NetBSD.org.</para> |
253 | </listitem> | | 253 | </listitem> |
254 | | | 254 | |
255 | <listitem> | | 255 | <listitem> |
256 | <para><varname>NO_SRC_ON_CDROM</varname></para> | | 256 | <para><varname>NO_SRC_ON_CDROM</varname></para> |
257 | | | 257 | |
258 | <para>Distfiles may not be placed on CD-ROM, together with | | 258 | <para>Distfiles may not be placed on CD-ROM, together with |
259 | other distfiles, for which a fee may be charged. In this | | 259 | other distfiles, for which a fee may be charged. In this |
260 | case, set this variable to <varname>${RESTRICTED}</varname>. | | 260 | case, set this variable to <varname>${RESTRICTED}</varname>. |
261 | </para> | | 261 | </para> |
262 | </listitem> | | 262 | </listitem> |
263 | | | 263 | |
264 | <listitem> | | 264 | <listitem> |
265 | <para><varname>NO_SRC_ON_FTP</varname></para> | | 265 | <para><varname>NO_SRC_ON_FTP</varname></para> |
266 | | | 266 | |
267 | <para>Distfiles may not made available via FTP at no charge. | | 267 | <para>Distfiles may not made available via FTP at no charge. |
268 | In this case, set this variable to | | 268 | In this case, set this variable to |
269 | <varname>${RESTRICTED}</varname>. If this variable is set, | | 269 | <varname>${RESTRICTED}</varname>. If this variable is set, |
270 | the distfile(s) will not be mirrored on ftp.NetBSD.org.</para> | | 270 | the distfile(s) will not be mirrored on ftp.NetBSD.org.</para> |
271 | </listitem> | | 271 | </listitem> |
272 | </itemizedlist> | | 272 | </itemizedlist> |
273 | | | 273 | |
274 | <para>Please note that the use of <varname>NO_PACKAGE</varname>, | | 274 | <para>Please note that the use of <varname>NO_PACKAGE</varname>, |
275 | <varname>IGNORE</varname>, <varname>NO_CDROM</varname>, or other | | 275 | <varname>IGNORE</varname>, <varname>NO_CDROM</varname>, or other |
276 | generic make variables to denote restrictions is deprecated, | | 276 | generic make variables to denote restrictions is deprecated, |
277 | because they unconditionally prevent users from generating | | 277 | because they unconditionally prevent users from generating |
278 | binary packages!</para> | | 278 | binary packages!</para> |
279 | </sect2> | | 279 | </sect2> |
280 | | | 280 | |
281 | | | 281 | |
282 | <sect2 id="dependencies"> | | 282 | <sect2 id="dependencies"> |
283 | <title>Handling dependencies</title> | | 283 | <title>Handling dependencies</title> |
284 | | | 284 | |
285 | <para>Your package may depend on some other package being present | | 285 | <para>Your package may depend on some other package being present |
286 | - and there are various ways of expressing this dependency. | | 286 | - and there are various ways of expressing this dependency. |
287 | pkgsrc supports the <varname>BUILD_DEPENDS</varname> and | | 287 | pkgsrc supports the <varname>BUILD_DEPENDS</varname> and |
288 | <varname>DEPENDS</varname> definitions, the | | 288 | <varname>DEPENDS</varname> definitions, the |
289 | <varname>USE_TOOLS</varname> definition, as well as dependencies | | 289 | <varname>USE_TOOLS</varname> definition, as well as dependencies |
290 | via <filename>buildlink3.mk</filename>, which is the preferred way | | 290 | via <filename>buildlink3.mk</filename>, which is the preferred way |
291 | to handle dependencies, and which uses the variables named above. | | 291 | to handle dependencies, and which uses the variables named above. |
292 | See <xref linkend="buildlink"/> for more information.</para> | | 292 | See <xref linkend="buildlink"/> for more information.</para> |
293 | | | 293 | |
294 | <para>The basic difference between the two variables is as | | 294 | <para>The basic difference between the two variables is as |
295 | follows: The <varname>DEPENDS</varname> definition registers | | 295 | follows: The <varname>DEPENDS</varname> definition registers |
296 | that pre-requisite in the binary package so it will be pulled in | | 296 | that pre-requisite in the binary package so it will be pulled in |
297 | when the binary package is later installed, whilst the | | 297 | when the binary package is later installed, whilst the |
298 | <varname>BUILD_DEPENDS</varname> definition does not, marking a | | 298 | <varname>BUILD_DEPENDS</varname> definition does not, marking a |
299 | dependency that is only needed for building the package.</para> | | 299 | dependency that is only needed for building the package.</para> |
300 | | | 300 | |
301 | <para>This means that if you only need a package present whilst | | 301 | <para>This means that if you only need a package present whilst |
302 | you are building, it should be noted as a | | 302 | you are building, it should be noted as a |
303 | <varname>BUILD_DEPENDS</varname>.</para> | | 303 | <varname>BUILD_DEPENDS</varname>.</para> |
304 | | | 304 | |
305 | <para>The format for a <varname>BUILD_DEPENDS</varname> and a | | 305 | <para>The format for a <varname>BUILD_DEPENDS</varname> and a |
306 | <varname>DEPENDS</varname> definition is:</para> | | 306 | <varname>DEPENDS</varname> definition is:</para> |
307 | | | 307 | |
308 | <programlisting> | | 308 | <programlisting> |
309 | <pre-req-package-name>:../../<category>/<pre-req-package> | | 309 | <pre-req-package-name>:../../<category>/<pre-req-package> |
310 | </programlisting> | | 310 | </programlisting> |
311 | | | 311 | |
312 | <para>Please note that the <quote>pre-req-package-name</quote> | | 312 | <para>Please note that the <quote>pre-req-package-name</quote> |
313 | may include any of the wildcard version numbers recognized by | | 313 | may include any of the wildcard version numbers recognized by |
314 | &man.pkg.info.1;.</para> | | 314 | &man.pkg.info.1;.</para> |
315 | | | 315 | |
316 | <orderedlist> | | 316 | <orderedlist> |
317 | <listitem> | | 317 | <listitem> |
318 | <para>If your package needs another package's binaries or | | 318 | <para>If your package needs another package's binaries or |
319 | libraries to build or run, and if that package has a | | 319 | libraries to build or run, and if that package has a |
320 | <filename>buildlink3.mk</filename> file available, use it:</para> | | 320 | <filename>buildlink3.mk</filename> file available, use it:</para> |
321 | | | 321 | |
322 | <programlisting> | | 322 | <programlisting> |
323 | .include "../../graphics/jpeg/buildlink3.mk" | | 323 | .include "../../graphics/jpeg/buildlink3.mk" |
324 | </programlisting> | | 324 | </programlisting> |
325 | </listitem> | | 325 | </listitem> |
326 | | | 326 | |
327 | <listitem> | | 327 | <listitem> |
328 | <para>If your package needs to use another package to build | | 328 | <para>If your package needs to use another package to build |
329 | itself and there is no <filename>buildlink3.mk</filename> | | 329 | itself and there is no <filename>buildlink3.mk</filename> |
330 | file available, use the <varname>BUILD_DEPENDS</varname> | | 330 | file available, use the <varname>BUILD_DEPENDS</varname> |
331 | definition:</para> | | 331 | definition:</para> |
332 | | | 332 | |
333 | <programlisting> | | 333 | <programlisting> |
334 | BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf | | 334 | BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf |
335 | </programlisting> | | 335 | </programlisting> |
336 | </listitem> | | 336 | </listitem> |
337 | | | 337 | |
338 | <listitem> | | 338 | <listitem> |
339 | | | 339 | |
340 | <para>If your package needs a library with which to link and | | 340 | <para>If your package needs a library with which to link and |
341 | again there is no <filename>buildlink3.mk</filename> file | | 341 | again there is no <filename>buildlink3.mk</filename> file |
342 | available, this is specified using the | | 342 | available, this is specified using the |
343 | <varname>DEPENDS</varname> definition. For example:</para> | | 343 | <varname>DEPENDS</varname> definition. For example:</para> |
344 | | | 344 | |
345 | <programlisting> | | 345 | <programlisting> |
346 | DEPENDS+= xpm-3.4j:../../graphics/xpm | | 346 | DEPENDS+= xpm-3.4j:../../graphics/xpm |
347 | </programlisting> | | 347 | </programlisting> |
348 | | | 348 | |
349 | <para>You can also use wildcards in package dependencies:</para> | | 349 | <para>You can also use wildcards in package dependencies:</para> |
350 | | | 350 | |
351 | <programlisting> | | 351 | <programlisting> |
352 | DEPENDS+= xpm-[0-9]*:../../graphics/xpm | | 352 | DEPENDS+= xpm-[0-9]*:../../graphics/xpm |
353 | </programlisting> | | 353 | </programlisting> |
354 | | | 354 | |
355 | <para>Note that such wildcard dependencies are retained when | | 355 | <para>Note that such wildcard dependencies are retained when |
356 | creating binary packages. The dependency is checked when | | 356 | creating binary packages. The dependency is checked when |
357 | installing the binary package and any package which matches | | 357 | installing the binary package and any package which matches |
358 | the pattern will be used. Wildcard dependencies should be | | 358 | the pattern will be used. Wildcard dependencies should be |
359 | used with care.</para> | | 359 | used with care.</para> |
360 | | | 360 | |
361 | <para>The <quote>-[0-9]*</quote> should be used instead of | | 361 | <para>The <quote>-[0-9]*</quote> should be used instead of |
362 | <quote>-*</quote> to avoid potentially ambiguous matches | | 362 | <quote>-*</quote> to avoid potentially ambiguous matches |
363 | such as <quote>tk-postgresql</quote> matching a | | 363 | such as <quote>tk-postgresql</quote> matching a |
364 | <quote>tk-*</quote> <varname>DEPENDS</varname>.</para> | | 364 | <quote>tk-*</quote> <varname>DEPENDS</varname>.</para> |
365 | | | 365 | |
366 | <para>Wildcards can also be used to specify that a package | | 366 | <para>Wildcards can also be used to specify that a package |
367 | will only build against a certain minimum version of a | | 367 | will only build against a certain minimum version of a |
368 | pre-requisite:</para> | | 368 | pre-requisite:</para> |
369 | | | 369 | |
370 | <programlisting> | | 370 | <programlisting> |
371 | DEPENDS+= tiff>=3.5.4:../../graphics/tiff | | 371 | DEPENDS+= tiff>=3.5.4:../../graphics/tiff |
372 | </programlisting> | | 372 | </programlisting> |
373 | | | 373 | |
374 | <para>This means that the package will build against version | | 374 | <para>This means that the package will build against version |
375 | 3.5.4 of the tiff library or newer. Such a dependency may | | 375 | 3.5.4 of the tiff library or newer. Such a dependency may |
376 | be warranted if, for example, the API of the library has | | 376 | be warranted if, for example, the API of the library has |
377 | changed with version 3.5.4 and a package would not compile | | 377 | changed with version 3.5.4 and a package would not compile |
378 | against an earlier version of tiff.</para> | | 378 | against an earlier version of tiff.</para> |
379 | | | 379 | |
380 | <para>Please note that such dependencies should only be | | 380 | <para>Please note that such dependencies should only be |
381 | updated if a package requires a newer pre-requisite, but | | 381 | updated if a package requires a newer pre-requisite, but |
382 | not to denote recommendations such as | | 382 | not to denote recommendations such as |
383 | ABI changes that do not prevent a package from building | | 383 | ABI changes that do not prevent a package from building |
384 | correctly. Such recommendations can be expressed using | | 384 | correctly. Such recommendations can be expressed using |
385 | <varname>ABI_DEPENDS</varname>:</para> | | 385 | <varname>ABI_DEPENDS</varname>:</para> |
386 | | | 386 | |
387 | <programlisting> | | 387 | <programlisting> |
388 | ABI_DEPENDS+= tiff>=3.6.1:../../graphics/tiff | | 388 | ABI_DEPENDS+= tiff>=3.6.1:../../graphics/tiff |
389 | </programlisting> | | 389 | </programlisting> |
390 | | | 390 | |
391 | <para>In addition to the above <varname>DEPENDS</varname> | | 391 | <para>In addition to the above <varname>DEPENDS</varname> |
392 | line, this denotes that while a package will build against | | 392 | line, this denotes that while a package will build against |
393 | tiff>=3.5.4, at least version 3.6.1 is recommended. | | 393 | tiff>=3.5.4, at least version 3.6.1 is recommended. |
394 | <varname>ABI_DEPENDS</varname> entries will be turned into | | 394 | <varname>ABI_DEPENDS</varname> entries will be turned into |
395 | dependencies unless explicitly ignored (in which case a | | 395 | dependencies unless explicitly ignored (in which case a |
396 | warning will be printed).</para> | | 396 | warning will be printed).</para> |
397 | | | 397 | |
398 | <para>To ignore these ABI dependency recommendations and just | | 398 | <para>To ignore these ABI dependency recommendations and just |
399 | use the required <varname>DEPENDS</varname>, set | | 399 | use the required <varname>DEPENDS</varname>, set |
400 | <varname>USE_ABI_DEPENDS=NO</varname>. This may make | | 400 | <varname>USE_ABI_DEPENDS=NO</varname>. This may make |
401 | it easier and faster to update packages built using pkgsrc, | | 401 | it easier and faster to update packages built using pkgsrc, |
402 | since older compatible dependencies can continue to be | | 402 | since older compatible dependencies can continue to be |
403 | used. This is useful for people who watch their rebuilds | | 403 | used. This is useful for people who watch their rebuilds |
404 | very carefully; it is not very good as a general-purpose | | 404 | very carefully; it is not very good as a general-purpose |
405 | hammer. If you use it, you need to be mindful of possible | | 405 | hammer. If you use it, you need to be mindful of possible |
406 | ABI changes, including those from the underlying OS.</para> | | 406 | ABI changes, including those from the underlying OS.</para> |
407 | | | 407 | |
408 | <para>Packages that are built with recommendations ignored | | 408 | <para>Packages that are built with recommendations ignored |
409 | may not be uploaded to ftp.NetBSD.org by developers and | | 409 | may not be uploaded to ftp.NetBSD.org by developers and |
410 | should not be used across different systems that may have | | 410 | should not be used across different systems that may have |
411 | different versions of binary packages installed.</para> | | 411 | different versions of binary packages installed.</para> |
412 | | | 412 | |
413 | <para>For security fixes, please update the package | | 413 | <para>For security fixes, please update the package |
414 | vulnerabilities file. See <xref | | 414 | vulnerabilities file. See <xref |
415 | linkend="security-handling"/> for more | | 415 | linkend="security-handling"/> for more |
416 | information.</para> | | 416 | information.</para> |
417 | </listitem> | | 417 | </listitem> |
418 | | | 418 | |
419 | <listitem> | | 419 | <listitem> |
420 | <para>If your package needs some executable to be able to run | | 420 | <para>If your package needs some executable to be able to run |
421 | correctly and if there's no | | 421 | correctly and if there's no |
422 | <filename>buildlink3.mk</filename> file, this is specified | | 422 | <filename>buildlink3.mk</filename> file, this is specified |
423 | using the <varname>DEPENDS</varname> variable. The | | 423 | using the <varname>DEPENDS</varname> variable. The |
424 | <filename role="pkg">print/lyx</filename> package needs to | | 424 | <filename role="pkg">print/lyx</filename> package needs to |
425 | be able to execute the latex binary from the teTeX package | | 425 | be able to execute the latex binary from the teTeX package |
426 | when it runs, and that is specified:</para> | | 426 | when it runs, and that is specified:</para> |
427 | | | 427 | |
428 | <programlisting> | | 428 | <programlisting> |
429 | DEPENDS+= teTeX-[0-9]*:../../print/teTeX | | 429 | DEPENDS+= teTeX-[0-9]*:../../print/teTeX |
430 | </programlisting> | | 430 | </programlisting> |
431 | | | 431 | |
432 | <para>The comment about wildcard dependencies from previous | | 432 | <para>The comment about wildcard dependencies from previous |
433 | paragraph applies here, too.</para> | | 433 | paragraph applies here, too.</para> |
434 | </listitem> | | 434 | </listitem> |
435 | </orderedlist> | | 435 | </orderedlist> |
436 | | | 436 | |
437 | <para>If your package needs files from another package to build, | | 437 | <para>If your package needs files from another package to build, |
438 | add the relevant distribution files to | | 438 | add the relevant distribution files to |
439 | <varname>DISTFILES</varname>, so they will be extracted | | 439 | <varname>DISTFILES</varname>, so they will be extracted |
440 | automatically. See the <filename | | 440 | automatically. See the <filename |
441 | role="pkg">print/ghostscript</filename> package for an example. | | 441 | role="pkg">print/ghostscript</filename> package for an example. |
442 | (It relies on the jpeg sources being present in source form | | 442 | (It relies on the jpeg sources being present in source form |
443 | during the build.)</para> | | 443 | during the build.)</para> |
444 | </sect2> | | 444 | </sect2> |
445 | | | 445 | |
446 | | | 446 | |
447 | <sect2 id="conflicts"> | | 447 | <sect2 id="conflicts"> |
448 | <title>Handling conflicts with other packages</title> | | 448 | <title>Handling conflicts with other packages</title> |
449 | | | 449 | |
450 | <para>Your package may conflict with other packages a user might | | 450 | <para>Your package may conflict with other packages a user might |
451 | already have installed on his system, e.g. if your package | | 451 | already have installed on his system, e.g. if your package |
452 | installs the same set of files as another package in the pkgsrc | | 452 | installs the same set of files as another package in the pkgsrc |
453 | tree.</para> | | 453 | tree.</para> |
454 | | | 454 | |
455 | <para>In this case you can set <varname>CONFLICTS</varname> to a | | 455 | <para>In this case you can set <varname>CONFLICTS</varname> to a |
456 | space-separated list of packages (including version string) your | | 456 | space-separated list of packages (including version string) your |
457 | package conflicts with.</para> | | 457 | package conflicts with.</para> |
458 | | | 458 | |
459 | <para>For example, <filename role="pkg">x11/Xaw3d</filename> | | 459 | <para>For example, <filename role="pkg">x11/Xaw3d</filename> |
460 | and <filename role="pkg">x11/Xaw-Xpm</filename> | | 460 | and <filename role="pkg">x11/Xaw-Xpm</filename> |
461 | install the same shared library, thus you set in | | 461 | install the same shared library, thus you set in |
462 | <filename>pkgsrc/x11/Xaw3d/Makefile</filename>:</para> | | 462 | <filename>pkgsrc/x11/Xaw3d/Makefile</filename>:</para> |
463 | | | 463 | |
464 | <programlisting> | | 464 | <programlisting> |
465 | CONFLICTS= Xaw-Xpm-[0-9]* | | 465 | CONFLICTS= Xaw-Xpm-[0-9]* |
466 | </programlisting> | | 466 | </programlisting> |
467 | | | 467 | |
468 | <para>and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>:</para> | | 468 | <para>and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>:</para> |
469 | | | 469 | |
470 | <programlisting> | | 470 | <programlisting> |
471 | CONFLICTS= Xaw3d-[0-9]* | | 471 | CONFLICTS= Xaw3d-[0-9]* |
472 | </programlisting> | | 472 | </programlisting> |
473 | | | 473 | |
474 | <para>Packages will automatically conflict with other packages | | 474 | <para>Packages will automatically conflict with other packages |
475 | with the name prefix and a different version | | 475 | with the name prefix and a different version |
476 | string. <quote>Xaw3d-1.5</quote> e.g. will automatically | | 476 | string. <quote>Xaw3d-1.5</quote> e.g. will automatically |
477 | conflict with the older version <quote>Xaw3d-1.3</quote>.</para> | | 477 | conflict with the older version <quote>Xaw3d-1.3</quote>.</para> |
478 | </sect2> | | 478 | </sect2> |
479 | | | 479 | |
480 | | | 480 | |
481 | <sect2 id="not-building-packages"> | | 481 | <sect2 id="not-building-packages"> |
482 | <title>Packages that cannot or should not be built</title> | | 482 | <title>Packages that cannot or should not be built</title> |
483 | | | 483 | |
484 | <para>There are several reasons why a package might be | | 484 | <para>There are several reasons why a package might be |
485 | instructed to not build under certain circumstances. If the | | 485 | instructed to not build under certain circumstances. If the |
486 | package builds and runs on most platforms, the exceptions | | 486 | package builds and runs on most platforms, the exceptions |
487 | should be noted with <varname>NOT_FOR_PLATFORM</varname>. If | | 487 | should be noted with <varname>NOT_FOR_PLATFORM</varname>. If |
488 | the package builds and runs on a small handful of platforms, | | 488 | the package builds and runs on a small handful of platforms, |
489 | set <varname>ONLY_FOR_PLATFORM</varname> instead. | | 489 | set <varname>ONLY_FOR_PLATFORM</varname> instead. |
490 | Both <varname>ONLY_FOR_PLATFORM</varname> and | | 490 | Both <varname>ONLY_FOR_PLATFORM</varname> and |
491 | <varname>NOT_FOR_PLATFORM</varname> are OS triples | | 491 | <varname>NOT_FOR_PLATFORM</varname> are OS triples |
492 | (OS-version-platform) that can use glob-style | | 492 | (OS-version-platform) that can use glob-style |
493 | wildcards.</para> | | 493 | wildcards.</para> |
494 | <para>Some packages are tightly bound to a specific version of an | | 494 | <para>Some packages are tightly bound to a specific version of an |
495 | operating system, e.g. LKMs or <filename | | 495 | operating system, e.g. LKMs or <filename |
496 | role="pkg">sysutils/lsof</filename>. Such binary packages are not | | 496 | role="pkg">sysutils/lsof</filename>. Such binary packages are not |
497 | backwards compatible with other versions of the OS, and should be | | 497 | backwards compatible with other versions of the OS, and should be |
498 | uploaded to a version specific directory on the FTP server. Mark | | 498 | uploaded to a version specific directory on the FTP server. Mark |
499 | these packages by setting <varname>OSVERSION_SPECIFIC</varname> to | | 499 | these packages by setting <varname>OSVERSION_SPECIFIC</varname> to |
500 | <quote>yes</quote>. This variable is not currently used by any of | | 500 | <quote>yes</quote>. This variable is not currently used by any of |
501 | the package system internals, but may be used in the | | 501 | the package system internals, but may be used in the |
502 | future.</para> | | 502 | future.</para> |
503 | <para>If the package should be skipped (for example, because it | | 503 | <para>If the package should be skipped (for example, because it |
504 | provides functionality already provided by the system), set | | 504 | provides functionality already provided by the system), set |
505 | <varname>PKG_SKIP_REASON</varname> to a descriptive message. If | | 505 | <varname>PKG_SKIP_REASON</varname> to a descriptive message. If |
506 | the package should fail because some preconditions are not met, | | 506 | the package should fail because some preconditions are not met, |
507 | set <varname>PKG_FAIL_REASON</varname> to a descriptive | | 507 | set <varname>PKG_FAIL_REASON</varname> to a descriptive |
508 | message.</para> | | 508 | message.</para> |
509 | </sect2> | | 509 | </sect2> |
510 | | | 510 | |
511 | | | 511 | |
512 | <sect2 id="undeletable-packages"> | | 512 | <sect2 id="undeletable-packages"> |
513 | <title>Packages which should not be deleted, once installed</title> | | 513 | <title>Packages which should not be deleted, once installed</title> |
514 | | | 514 | |
515 | <para>To ensure that a package may not be deleted, once it has been | | 515 | <para>To ensure that a package may not be deleted, once it has been |
516 | installed, the <varname>PKG_PRESERVE</varname> definition should | | 516 | installed, the <varname>PKG_PRESERVE</varname> definition should |
517 | be set in the package Makefile. This will be carried into any | | 517 | be set in the package Makefile. This will be carried into any |
518 | binary package that is made from this pkgsrc entry. A | | 518 | binary package that is made from this pkgsrc entry. A |
519 | <quote>preserved</quote> package will | | 519 | <quote>preserved</quote> package will |
520 | not be deleted using &man.pkg.delete.1; unless the | | 520 | not be deleted using &man.pkg.delete.1; unless the |
521 | <quote>-f</quote> option is used.</para> | | 521 | <quote>-f</quote> option is used.</para> |
522 | </sect2> | | 522 | </sect2> |
523 | | | 523 | |
524 | | | 524 | |
525 | <sect2 id="security-handling"> | | 525 | <sect2 id="security-handling"> |
526 | <title>Handling packages with security problems</title> | | 526 | <title>Handling packages with security problems</title> |
527 | | | 527 | |
528 | <para>When a vulnerability is found, this should be noted in | | 528 | <para>When a vulnerability is found, this should be noted in |
529 | <filename>localsrc/security/advisories/pkg-vulnerabilities</filename>, | | 529 | <filename>localsrc/security/advisories/pkg-vulnerabilities</filename>, |
530 | and after committing that file, use <command>make upload</command> | | 530 | and after committing that file, use <command>make upload</command> |
531 | in the same directory to update the file on ftp.NetBSD.org.</para> | | 531 | in the same directory to update the file on ftp.NetBSD.org.</para> |
532 | | | 532 | |
533 | <para>After fixing the vulnerability by a patch, its | | 533 | <para>After fixing the vulnerability by a patch, its |
534 | <varname>PKGREVISION</varname> should be increased (this | | 534 | <varname>PKGREVISION</varname> should be increased (this |
535 | is of course not necessary if the problem is fixed by using | | 535 | is of course not necessary if the problem is fixed by using |
536 | a newer release of the software).</para> | | 536 | a newer release of the software).</para> |
537 | | | 537 | |
538 | <para>Also, if the fix should be applied to the stable pkgsrc | | 538 | <para>Also, if the fix should be applied to the stable pkgsrc |
539 | branch, be sure to submit a pullup request!</para> | | 539 | branch, be sure to submit a pullup request!</para> |
540 | | | 540 | |
541 | <para>Binary packages already on ftp.NetBSD.org will be handled | | 541 | <para>Binary packages already on ftp.NetBSD.org will be handled |
542 | semi-automatically by a weekly cron job.</para> | | 542 | semi-automatically by a weekly cron job.</para> |
543 | </sect2> | | 543 | </sect2> |
544 | | | 544 | |
545 | | | 545 | |
546 | <sect2 id="bumping-pkgrevision"> | | 546 | <sect2 id="bumping-pkgrevision"> |
547 | <title>How to handle incrementing versions when fixing an existing package</title> | | 547 | <title>How to handle incrementing versions when fixing an existing package</title> |
548 | | | 548 | |
549 | <para>When making fixes to an existing package it can be useful | | 549 | <para>When making fixes to an existing package it can be useful |
550 | to change the version number in <varname>PKGNAME</varname>. To | | 550 | to change the version number in <varname>PKGNAME</varname>. To |
551 | avoid conflicting with future versions by the original author, a | | 551 | avoid conflicting with future versions by the original author, a |
552 | <quote>nb1</quote>, <quote>nb2</quote>, ... suffix can be used | | 552 | <quote>nb1</quote>, <quote>nb2</quote>, ... suffix can be used |
553 | on package versions by setting <varname>PKGREVISION=1</varname> | | 553 | on package versions by setting <varname>PKGREVISION=1</varname> |
554 | (2, ...). The <quote>nb</quote> is treated like a | | 554 | (2, ...). The <quote>nb</quote> is treated like a |
555 | <quote>.</quote> by the package tools. e.g.</para> | | 555 | <quote>.</quote> by the package tools. e.g.</para> |
556 | | | 556 | |
557 | <programlisting> | | 557 | <programlisting> |
558 | DISTNAME= foo-17.42 | | 558 | DISTNAME= foo-17.42 |
559 | PKGREVISION= 9 | | 559 | PKGREVISION= 9 |
560 | </programlisting> | | 560 | </programlisting> |
561 | | | 561 | |
562 | <para>will result in a <varname>PKGNAME</varname> of | | 562 | <para>will result in a <varname>PKGNAME</varname> of |
563 | <quote>foo-17.42nb9</quote>. If you want to use the original | | 563 | <quote>foo-17.42nb9</quote>. If you want to use the original |
564 | value of <varname>PKGNAME</varname> without the <quote>nbX</quote> | | 564 | value of <varname>PKGNAME</varname> without the <quote>nbX</quote> |
565 | suffix, e.g. for setting <varname>DIST_SUBDIR</varname>, use | | 565 | suffix, e.g. for setting <varname>DIST_SUBDIR</varname>, use |
566 | <varname>PKGNAME_NOREV</varname>.</para> | | 566 | <varname>PKGNAME_NOREV</varname>.</para> |
567 | | | 567 | |
568 | <para>When a new release of the package is released, the | | 568 | <para>When a new release of the package is released, the |
569 | <varname>PKGREVISION</varname> should be removed, e.g. on a new | | 569 | <varname>PKGREVISION</varname> should be removed, e.g. on a new |
570 | minor release of the above package, things should be like:</para> | | 570 | minor release of the above package, things should be like:</para> |
571 | | | 571 | |
572 | <programlisting> | | 572 | <programlisting> |
573 | DISTNAME= foo-17.43 | | 573 | DISTNAME= foo-17.43 |
574 | </programlisting> | | 574 | </programlisting> |
575 | | | 575 | |
576 | <para><varname>PKGREVISION</varname> should be incremented for any | | 576 | <para><varname>PKGREVISION</varname> should be incremented for any |
577 | non-trivial change in the resulting binary package. Without a | | 577 | non-trivial change in the resulting binary package. Without a |
578 | <varname>PKGREVISION</varname> bump, someone with the previous | | 578 | <varname>PKGREVISION</varname> bump, someone with the previous |
579 | version installed has no way of knowing that their package is out | | 579 | version installed has no way of knowing that their package is out |
580 | of date. Thus, changes without increasing | | 580 | of date. Thus, changes without increasing |
581 | <varname>PKGREVISION</varname> are essentially labeled "this is so | | 581 | <varname>PKGREVISION</varname> are essentially labeled "this is so |
582 | trivial that no reasonable person would want to upgrade", and this | | 582 | trivial that no reasonable person would want to upgrade", and this |
583 | is the rough test for when increasing | | 583 | is the rough test for when increasing |
584 | <varname>PKGREVISION</varname> is appropriate. Examples of | | 584 | <varname>PKGREVISION</varname> is appropriate. Examples of |
585 | changes that do not merit increasing | | 585 | changes that do not merit increasing |
586 | <varname>PKGREVISION</varname> are:</para> | | 586 | <varname>PKGREVISION</varname> are:</para> |
587 | | | 587 | |
588 | <itemizedlist><listitem> | | 588 | <itemizedlist><listitem> |
589 | <para>Changing <varname>HOMEPAGE</varname>, | | 589 | <para>Changing <varname>HOMEPAGE</varname>, |
590 | <varname>MAINTAINER</varname>, <varname>OWNER</varname>, | | 590 | <varname>MAINTAINER</varname>, <varname>OWNER</varname>, |
591 | or comments in Makefile.</para></listitem><listitem><para> | | 591 | or comments in Makefile.</para></listitem><listitem><para> |
592 | Changing build variables if the resulting binary package is the same.</para></listitem><listitem><para> | | 592 | Changing build variables if the resulting binary package is the same.</para></listitem><listitem><para> |
593 | Changing <filename>DESCR</filename>.</para></listitem><listitem><para> | | 593 | Changing <filename>DESCR</filename>.</para></listitem><listitem><para> |
594 | Adding <varname>PKG_OPTIONS</varname> if the default options don't change.</para></listitem> | | 594 | Adding <varname>PKG_OPTIONS</varname> if the default options don't change.</para></listitem> |
595 | </itemizedlist> | | 595 | </itemizedlist> |
596 | | | 596 | |
597 | <para>Examples of changes that do merit an increase to | | 597 | <para>Examples of changes that do merit an increase to |
598 | <varname>PKGREVISION</varname> include:</para> | | 598 | <varname>PKGREVISION</varname> include:</para> |
599 | <itemizedlist><listitem><para> | | 599 | <itemizedlist><listitem><para> |
600 | Security fixes</para></listitem><listitem><para> | | 600 | Security fixes</para></listitem><listitem><para> |
601 | Changes or additions to a patch file</para></listitem><listitem><para> | | 601 | Changes or additions to a patch file</para></listitem><listitem><para> |
602 | Changes to the <filename>PLIST</filename></para></listitem> | | 602 | Changes to the <filename>PLIST</filename></para></listitem> |
603 | <listitem><para>A dependency is changed or renamed.</para></listitem> | | 603 | <listitem><para>A dependency is changed or renamed.</para></listitem> |
604 | </itemizedlist> | | 604 | </itemizedlist> |
605 | | | 605 | |
606 | <para>PKGREVISION must also be incremented when dependencies have ABI | | 606 | <para>PKGREVISION must also be incremented when dependencies have ABI |
607 | changes.</para> | | 607 | changes.</para> |
608 | </sect2> | | 608 | </sect2> |
609 | | | 609 | |
610 | <sect2 id="fixes.subst"> | | 610 | <sect2 id="fixes.subst"> |
611 | <title>Substituting variable text in the package files (the SUBST framework)</title> | | 611 | <title>Substituting variable text in the package files (the SUBST framework)</title> |
612 | | | 612 | |
613 | <para>When you want to replace the same text in multiple files | | 613 | <para>When you want to replace the same text in multiple files |
614 | or when the replacement text varies, patches alone cannot help. | | 614 | or when the replacement text varies, patches alone cannot help. |
615 | This is where the SUBST framework comes in. It provides an | | 615 | This is where the SUBST framework comes in. It provides an |
616 | easy-to-use interface for replacing text in files. | | 616 | easy-to-use interface for replacing text in files. |
617 | Example:</para> | | 617 | Example:</para> |
618 | | | 618 | |
619 | <programlisting> | | 619 | <programlisting> |
620 | SUBST_CLASSES+= fix-paths | | 620 | SUBST_CLASSES+= fix-paths |
621 | SUBST_STAGE.fix-paths= pre-configure | | 621 | SUBST_STAGE.fix-paths= pre-configure |
622 | SUBST_MESSAGE.fix-paths= Fixing absolute paths. | | 622 | SUBST_MESSAGE.fix-paths= Fixing absolute paths. |
623 | SUBST_FILES.fix-paths= src/*.c | | 623 | SUBST_FILES.fix-paths= src/*.c |
624 | SUBST_FILES.fix-paths+= scripts/*.sh | | 624 | SUBST_FILES.fix-paths+= scripts/*.sh |
625 | SUBST_SED.fix-paths= -e 's,"/usr/local,"${PREFIX},g' | | 625 | SUBST_SED.fix-paths= -e 's,"/usr/local,"${PREFIX},g' |
626 | SUBST_SED.fix-paths+= -e 's,"/var/log,"${VARBASE}/log,g' | | 626 | SUBST_SED.fix-paths+= -e 's,"/var/log,"${VARBASE}/log,g' |
627 | </programlisting> | | 627 | </programlisting> |
628 | | | 628 | |
629 | <para><varname>SUBST_CLASSES</varname> is a list of identifiers | | 629 | <para><varname>SUBST_CLASSES</varname> is a list of identifiers |
630 | that are used to identify the different SUBST blocks that are | | 630 | that are used to identify the different SUBST blocks that are |
631 | defined. The SUBST framework is heavily used by pkgsrc, so it is | | 631 | defined. The SUBST framework is heavily used by pkgsrc, so it is |
632 | important to always use the <literal>+=</literal> operator with | | 632 | important to always use the <literal>+=</literal> operator with |
633 | this variable. Otherwise some substitutions may be | | 633 | this variable. Otherwise some substitutions may be |
634 | skipped.</para> | | 634 | skipped.</para> |
635 | | | 635 | |
636 | <para>The remaining variables of each SUBST block are | | 636 | <para>The remaining variables of each SUBST block are |
637 | parameterized with the identifier from the first line | | 637 | parameterized with the identifier from the first line |
638 | (<literal>fix-paths</literal> in this case.) They can be seen as | | 638 | (<literal>fix-paths</literal> in this case.) They can be seen as |
639 | parameters to a function call.</para> | | 639 | parameters to a function call.</para> |
640 | | | 640 | |
641 | <para><varname>SUBST_STAGE.*</varname> specifies the stage at | | 641 | <para><varname>SUBST_STAGE.*</varname> specifies the stage at |
642 | which the replacement will take place. All combinations of | | 642 | which the replacement will take place. All combinations of |
643 | <literal>pre-</literal>, <literal>do-</literal> and | | 643 | <literal>pre-</literal>, <literal>do-</literal> and |
644 | <literal>post-</literal> together with a phase name are | | 644 | <literal>post-</literal> together with a phase name are |
645 | possible, though only few are actually used. Most commonly used | | 645 | possible, though only few are actually used. Most commonly used |
646 | are <literal>post-patch</literal> and | | 646 | are <literal>post-patch</literal> and |
647 | <literal>pre-configure</literal>. Of these two, | | 647 | <literal>pre-configure</literal>. Of these two, |
648 | <literal>pre-configure</literal> should be preferred because | | 648 | <literal>pre-configure</literal> should be preferred because |
649 | then it is possible to run <command>bmake patch</command> and | | 649 | then it is possible to run <command>bmake patch</command> and |
650 | have the state after applying the patches but before making any | | 650 | have the state after applying the patches but before making any |
651 | other changes. This is especially useful when you are debugging | | 651 | other changes. This is especially useful when you are debugging |
652 | a package in order to create new patches for it. Similarly, | | 652 | a package in order to create new patches for it. Similarly, |
653 | <literal>post-build</literal> is preferred over | | 653 | <literal>post-build</literal> is preferred over |
654 | <literal>pre-install</literal>, because the install phase should | | 654 | <literal>pre-install</literal>, because the install phase should |
655 | generally be kept as simple as possible. When you use | | 655 | generally be kept as simple as possible. When you use |
656 | <literal>post-build</literal>, you have the same files in the | | 656 | <literal>post-build</literal>, you have the same files in the |
657 | working directory that will be installed later, so you can check | | 657 | working directory that will be installed later, so you can check |
658 | if the substitution has succeeded.</para> | | 658 | if the substitution has succeeded.</para> |
659 | | | 659 | |
660 | <para><varname>SUBST_MESSAGE.*</varname> is an optional text | | 660 | <para><varname>SUBST_MESSAGE.*</varname> is an optional text |
661 | that is printed just before the substitution is done.</para> | | 661 | that is printed just before the substitution is done.</para> |
662 | | | 662 | |
663 | <para><varname>SUBST_FILES.*</varname> is the list of shell | | 663 | <para><varname>SUBST_FILES.*</varname> is the list of shell |
664 | globbing patterns that specifies the files in which the | | 664 | globbing patterns that specifies the files in which the |
665 | substitution will take place. The patterns are interpreted | | 665 | substitution will take place. The patterns are interpreted |
666 | relatively to the <varname>WRKSRC</varname> directory.</para> | | 666 | relatively to the <varname>WRKSRC</varname> directory.</para> |
667 | | | 667 | |
668 | <para><varname>SUBST_SED.*</varname> is a list of arguments to | | 668 | <para><varname>SUBST_SED.*</varname> is a list of arguments to |
669 | &man.sed.1; that specify the actual substitution. Every sed | | 669 | &man.sed.1; that specify the actual substitution. Every sed |
670 | command should be prefixed with <literal>-e</literal>, so that | | 670 | command should be prefixed with <literal>-e</literal>, so that |
671 | all SUBST blocks look uniform.</para> | | 671 | all SUBST blocks look uniform.</para> |
672 | | | 672 | |
673 | <para>There are some more variables, but they are so seldomly | | 673 | <para>There are some more variables, but they are so seldomly |
674 | used that they are only documented in the | | 674 | used that they are only documented in the |
675 | <filename>mk/subst.mk</filename> file.</para> | | 675 | <filename>mk/subst.mk</filename> file.</para> |
676 | | | 676 | |
677 | </sect2> | | 677 | </sect2> |
678 | </sect1> | | 678 | </sect1> |
679 | <sect1 id="fixes.fetch"> | | 679 | <sect1 id="fixes.fetch"> |
680 | <title>Fixing problems in the <emphasis>fetch</emphasis> phase</title> | | 680 | <title>Fixing problems in the <emphasis>fetch</emphasis> phase</title> |
681 | | | 681 | |
682 | <sect2 id="no-plain-download"> | | 682 | <sect2 id="no-plain-download"> |
683 | <title>Packages whose distfiles aren't available for plain downloading</title> | | 683 | <title>Packages whose distfiles aren't available for plain downloading</title> |
684 | | | 684 | |
685 | <para>If you need to download from a dynamic URL you can set | | 685 | <para>If you need to download from a dynamic URL you can set |
686 | <varname>DYNAMIC_MASTER_SITES</varname> and a <command>make | | 686 | <varname>DYNAMIC_MASTER_SITES</varname> and a <command>make |
687 | fetch</command> will call <filename>files/getsite.sh</filename> | | 687 | fetch</command> will call <filename>files/getsite.sh</filename> |
688 | with the name of each file to download as an argument, expecting | | 688 | with the name of each file to download as an argument, expecting |
689 | it to output the URL of the directory from which to download | | 689 | it to output the URL of the directory from which to download |
690 | it. <filename role="pkg">graphics/ns-cult3d</filename> is an | | 690 | it. <filename role="pkg">graphics/ns-cult3d</filename> is an |
691 | example of this usage.</para> | | 691 | example of this usage.</para> |
692 | | | 692 | |
693 | <para>If the download can't be automated, because the user must | | 693 | <para>If the download can't be automated, because the user must |
694 | submit personal information to apply for a password, or must pay | | 694 | submit personal information to apply for a password, or must pay |
695 | for the source, or whatever, you can set | | 695 | for the source, or whatever, you can set |
696 | <varname>FETCH_MESSAGE</varname> to a list of lines that are | | 696 | <varname>FETCH_MESSAGE</varname> to a list of lines that are |
697 | displayed to the user before aborting the build. Example:</para> | | 697 | displayed to the user before aborting the build. Example:</para> |
698 | | | 698 | |
699 | <programlisting> | | 699 | <programlisting> |
700 | FETCH_MESSAGE= "Please download the files" | | 700 | FETCH_MESSAGE= "Please download the files" |
701 | FETCH_MESSAGE+= " "${DISTFILES:Q} | | 701 | FETCH_MESSAGE+= " "${DISTFILES:Q} |
702 | FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"." | | 702 | FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"." |
703 | </programlisting> | | 703 | </programlisting> |
704 | | | 704 | |
705 | </sect2> | | 705 | </sect2> |
706 | | | 706 | |
707 | | | 707 | |
708 | <sect2 id="modified-distfiles-same-name"> | | 708 | <sect2 id="modified-distfiles-same-name"> |
709 | <title>How to handle modified distfiles with the 'old' name</title> | | 709 | <title>How to handle modified distfiles with the 'old' name</title> |
710 | | | 710 | |
711 | <para>Sometimes authors of a software package make some | | 711 | <para>Sometimes authors of a software package make some |
712 | modifications after the software was released, and they put up a | | 712 | modifications after the software was released, and they put up a |
713 | new distfile without changing the package's version number. If a | | 713 | new distfile without changing the package's version number. If a |
714 | package is already in pkgsrc at that time, the checksum will | | 714 | package is already in pkgsrc at that time, the checksum will |
715 | no longer match. The contents of the new distfile should be | | 715 | no longer match. The contents of the new distfile should be |
716 | compared against the old one before changing anything, to make | | 716 | compared against the old one before changing anything, to make |
717 | sure the distfile was really updated on purpose, and that | | 717 | sure the distfile was really updated on purpose, and that |
718 | no trojan horse or so crept in. | | 718 | no trojan horse or so crept in. |
719 | Please mention that the distfiles were compared and what was found | | 719 | Please mention that the distfiles were compared and what was found |
720 | in your commit message. | | 720 | in your commit message. |
721 | Then, the correct way to work around this is to | | 721 | Then, the correct way to work around this is to |
722 | set <varname>DIST_SUBDIR</varname> to a unique directory name, | | 722 | set <varname>DIST_SUBDIR</varname> to a unique directory name, |
723 | usually based on <varname>PKGNAME_NOREV</varname>. All | | 723 | usually based on <varname>PKGNAME_NOREV</varname>. All |
724 | <varname>DISTFILES</varname> and | | 724 | <varname>DISTFILES</varname> and |
725 | <varname>PATCHFILES</varname> for this package will be put in that | | 725 | <varname>PATCHFILES</varname> for this package will be put in that |
726 | subdirectory of the local distfiles directory. | | 726 | subdirectory of the local distfiles directory. |
727 | (See <xref linkend="bumping-pkgrevision"/> for more details.) | | 727 | (See <xref linkend="bumping-pkgrevision"/> for more details.) |
728 | In case this | | 728 | In case this |
729 | happens more often, <varname>PKGNAME</varname> can be used (thus | | 729 | happens more often, <varname>PKGNAME</varname> can be used (thus |
730 | including the <filename>nbX</filename> suffix) or a date stamp | | 730 | including the <filename>nbX</filename> suffix) or a date stamp |
731 | can be appended, like <varname>${PKGNAME_NOREV}-YYYYMMDD</varname>. | | 731 | can be appended, like <varname>${PKGNAME_NOREV}-YYYYMMDD</varname>. |
732 | Do not forget regenerating the <filename>distinfo</filename> file | | 732 | Do not forget regenerating the <filename>distinfo</filename> file |
733 | after that, since it contains the <varname>DIST_SUBDIR</varname> | | 733 | after that, since it contains the <varname>DIST_SUBDIR</varname> |
734 | path in the filenames. | | 734 | path in the filenames. |
735 | Also increase the PKGREVISION if the installed package is different. | | 735 | Also increase the PKGREVISION if the installed package is different. |
736 | Furthermore, a mail to the package's authors seems appropriate | | 736 | Furthermore, a mail to the package's authors seems appropriate |
737 | telling them that changing distfiles after releases without | | 737 | telling them that changing distfiles after releases without |
738 | changing the file names is not good practice.</para> | | 738 | changing the file names is not good practice.</para> |
739 | </sect2> | | 739 | </sect2> |
740 | </sect1> | | 740 | </sect1> |
741 | | | 741 | |
742 | | | 742 | |
743 | <sect1 id="fixes.configure"> | | 743 | <sect1 id="fixes.configure"> |
744 | <title>Fixing problems in the <emphasis>configure</emphasis> phase</title> | | 744 | <title>Fixing problems in the <emphasis>configure</emphasis> phase</title> |
745 | | | 745 | |
746 | <sect2 id="fixes.libtool"> | | 746 | <sect2 id="fixes.libtool"> |
747 | <title>Shared libraries - libtool</title> | | 747 | <title>Shared libraries - libtool</title> |
748 | | | 748 | |
749 | <para>pkgsrc supports many different machines, with different | | 749 | <para>pkgsrc supports many different machines, with different |
750 | object formats like a.out and ELF, and varying abilities to do | | 750 | object formats like a.out and ELF, and varying abilities to do |
751 | shared library and dynamic loading at all. To accompany this, | | 751 | shared library and dynamic loading at all. To accompany this, |
752 | varying commands and options have to be passed to the | | 752 | varying commands and options have to be passed to the |
753 | compiler, linker, etc. to get the Right Thing, which can be | | 753 | compiler, linker, etc. to get the Right Thing, which can be |
754 | pretty annoying especially if you don't have all the machines | | 754 | pretty annoying especially if you don't have all the machines |
755 | at your hand to test things. The | | 755 | at your hand to test things. The |
756 | <filename role="pkg">devel/libtool</filename> pkg | | 756 | <filename role="pkg">devel/libtool</filename> pkg |
757 | can help here, as it just <quote>knows</quote> how to build | | 757 | can help here, as it just <quote>knows</quote> how to build |
758 | both static and dynamic libraries from a set of source files, | | 758 | both static and dynamic libraries from a set of source files, |
759 | thus being platform-independent.</para> | | 759 | thus being platform-independent.</para> |
760 | | | 760 | |
761 | <para>Here's how to use libtool in a package in seven simple | | 761 | <para>Here's how to use libtool in a package in seven simple |
762 | steps:</para> | | 762 | steps:</para> |
763 | | | 763 | |
764 | <orderedlist> | | 764 | <orderedlist> |
765 | <listitem> | | 765 | <listitem> |
766 | <para>Add <varname>USE_LIBTOOL=yes</varname> to the package | | 766 | <para>Add <varname>USE_LIBTOOL=yes</varname> to the package |
767 | Makefile.</para> | | 767 | Makefile.</para> |
768 | </listitem> | | 768 | </listitem> |
769 | | | 769 | |
770 | <listitem> | | 770 | <listitem> |
771 | <para>For library objects, use <quote>${LIBTOOL} --mode=compile | | 771 | <para>For library objects, use <quote>${LIBTOOL} --mode=compile |
772 | ${CC}</quote> in place of <quote>${CC}</quote>. You could even | | 772 | ${CC}</quote> in place of <quote>${CC}</quote>. You could even |
773 | add it to the definition of <varname>CC</varname>, if only | | 773 | add it to the definition of <varname>CC</varname>, if only |
774 | libraries are being built in a given Makefile. This one command | | 774 | libraries are being built in a given Makefile. This one command |
775 | will build both PIC and non-PIC library objects, so you need not | | 775 | will build both PIC and non-PIC library objects, so you need not |
776 | have separate shared and non-shared library rules.</para> | | 776 | have separate shared and non-shared library rules.</para> |
777 | </listitem> | | 777 | </listitem> |
778 | | | 778 | |
779 | <listitem> | | 779 | <listitem> |
780 | <para>For the linking of the library, remove any | | 780 | <para>For the linking of the library, remove any |
781 | <quote>ar</quote>, <quote>ranlib</quote>, and <quote>ld | | 781 | <quote>ar</quote>, <quote>ranlib</quote>, and <quote>ld |
782 | -Bshareable</quote> commands, and instead use:</para> | | 782 | -Bshareable</quote> commands, and instead use:</para> |
783 | | | 783 | |
784 | <programlisting> | | 784 | <programlisting> |
785 | ${LIBTOOL} --mode=link \ | | 785 | ${LIBTOOL} --mode=link \ |
786 | ${CC} -o ${.TARGET:.a=.la} \ | | 786 | ${CC} -o ${.TARGET:.a=.la} \ |
787 | ${OBJS:.o=.lo} \ | | 787 | ${OBJS:.o=.lo} \ |
788 | -rpath ${PREFIX}/lib \ | | 788 | -rpath ${PREFIX}/lib \ |
789 | -version-info major:minor | | 789 | -version-info major:minor |
790 | </programlisting> | | 790 | </programlisting> |
791 | | | 791 | |
792 | <para>Note that the library is changed to have a | | 792 | <para>Note that the library is changed to have a |
793 | <filename>.la</filename> extension, and the objects are | | 793 | <filename>.la</filename> extension, and the objects are |
794 | changed to have a <filename>.lo</filename> | | 794 | changed to have a <filename>.lo</filename> |
795 | extension. Change <varname>OBJS</varname> as | | 795 | extension. Change <varname>OBJS</varname> as |
796 | necessary. This automatically creates all of the | | 796 | necessary. This automatically creates all of the |
797 | <filename>.a</filename>, | | 797 | <filename>.a</filename>, |
798 | <filename>.so.major.minor</filename>, and ELF symlinks (if | | 798 | <filename>.so.major.minor</filename>, and ELF symlinks (if |
799 | necessary) in the build directory. Be sure to include | | 799 | necessary) in the build directory. Be sure to include |
800 | <quote>-version-info</quote>, especially when major and | | 800 | <quote>-version-info</quote>, especially when major and |
801 | minor are zero, as libtool will otherwise strip off the | | 801 | minor are zero, as libtool will otherwise strip off the |
802 | shared library version.</para> | | 802 | shared library version.</para> |
803 | | | 803 | |
804 | <para>From the libtool manual:</para> | | 804 | <para>From the libtool manual:</para> |
805 | | | 805 | |
806 | <programlisting> | | 806 | <programlisting> |
807 | So, libtool library versions are described by three integers: | | 807 | So, libtool library versions are described by three integers: |
808 | | | 808 | |
809 | CURRENT | | 809 | CURRENT |
810 | The most recent interface number that this library implements. | | 810 | The most recent interface number that this library implements. |
811 | | | 811 | |
812 | REVISION | | 812 | REVISION |
813 | The implementation number of the CURRENT interface. | | 813 | The implementation number of the CURRENT interface. |
814 | | | 814 | |
815 | AGE | | 815 | AGE |
816 | The difference between the newest and oldest interfaces that | | 816 | The difference between the newest and oldest interfaces that |
817 | this library implements. In other words, the library implements | | 817 | this library implements. In other words, the library implements |
818 | all the interface numbers in the range from number `CURRENT - | | 818 | all the interface numbers in the range from number `CURRENT - |
819 | AGE' to `CURRENT'. | | 819 | AGE' to `CURRENT'. |
820 | | | 820 | |
821 | If two libraries have identical CURRENT and AGE numbers, then the | | 821 | If two libraries have identical CURRENT and AGE numbers, then the |
822 | dynamic linker chooses the library with the greater REVISION number. | | 822 | dynamic linker chooses the library with the greater REVISION number. |
823 | </programlisting> | | 823 | </programlisting> |
824 | | | 824 | |
825 | <para>The <quote>-release</quote> option will produce | | 825 | <para>The <quote>-release</quote> option will produce |
826 | different results for a.out and ELF (excluding symlinks) | | 826 | different results for a.out and ELF (excluding symlinks) |
827 | in only one case. An ELF library of the form | | 827 | in only one case. An ELF library of the form |
828 | <quote>libfoo-release.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> | | 828 | <quote>libfoo-release.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> |
829 | will have a symlink of | | 829 | will have a symlink of |
830 | <quote>libfoo.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> | | 830 | <quote>libfoo.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> |
831 | on an a.out platform. This is handled | | 831 | on an a.out platform. This is handled |
832 | automatically.</para> | | 832 | automatically.</para> |
833 | | | 833 | |
834 | <para>The <quote>-rpath argument</quote> is the install | | 834 | <para>The <quote>-rpath argument</quote> is the install |
835 | directory of the library being built.</para> | | 835 | directory of the library being built.</para> |
836 | | | 836 | |
837 | <para>In the <filename>PLIST</filename>, include only the | | 837 | <para>In the <filename>PLIST</filename>, include only the |
838 | <filename>.la</filename> file, the other files will be | | 838 | <filename>.la</filename> file, the other files will be |
839 | added automatically.</para> | | 839 | added automatically.</para> |
840 | </listitem> | | 840 | </listitem> |
841 | | | 841 | |
842 | <listitem> | | 842 | <listitem> |
843 | <para>When linking shared object (<filename>.so</filename>) | | 843 | <para>When linking shared object (<filename>.so</filename>) |
844 | files, i.e. files that are loaded via &man.dlopen.3;, NOT | | 844 | files, i.e. files that are loaded via &man.dlopen.3;, NOT |
845 | shared libraries, use <quote>-module | | 845 | shared libraries, use <quote>-module |
846 | -avoid-version</quote> to prevent them getting version | | 846 | -avoid-version</quote> to prevent them getting version |
847 | tacked on.</para> | | 847 | tacked on.</para> |
848 | | | 848 | |
849 | <para>The <filename>PLIST</filename> file gets the | | 849 | <para>The <filename>PLIST</filename> file gets the |
850 | <filename>foo.so</filename> entry.</para> | | 850 | <filename>foo.so</filename> entry.</para> |
851 | </listitem> | | 851 | </listitem> |
852 | | | 852 | |
853 | <listitem> | | 853 | <listitem> |
854 | <para>When linking programs that depend on these libraries | | 854 | <para>When linking programs that depend on these libraries |
855 | <emphasis>before</emphasis> they are installed, preface | | 855 | <emphasis>before</emphasis> they are installed, preface |
856 | the &man.cc.1; or &man.ld.1; line with <quote>${LIBTOOL} | | 856 | the &man.cc.1; or &man.ld.1; line with <quote>${LIBTOOL} |
857 | --mode=link</quote>, and it will find the correct | | 857 | --mode=link</quote>, and it will find the correct |
858 | libraries (static or shared), but please be aware that | | 858 | libraries (static or shared), but please be aware that |
859 | libtool will not allow you to specify a relative path in | | 859 | libtool will not allow you to specify a relative path in |
860 | -L (such as <quote>-L../somelib</quote>), because it | | 860 | -L (such as <quote>-L../somelib</quote>), because it |
861 | expects you to change that argument to be the | | 861 | expects you to change that argument to be the |
862 | <filename>.la</filename> file. e.g.</para> | | 862 | <filename>.la</filename> file. e.g.</para> |
863 | | | 863 | |
864 | <programlisting> | | 864 | <programlisting> |
865 | ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib | | 865 | ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib |
866 | </programlisting> | | 866 | </programlisting> |
867 | | | 867 | |
868 | <para>should be changed to:</para> | | 868 | <para>should be changed to:</para> |
869 | | | 869 | |
870 | <programlisting> | | 870 | <programlisting> |
871 | ${LIBTOOL} --mode=link ${CC} -o <replaceable>someprog</replaceable> <replaceable>../somelib/somelib.la</replaceable> | | 871 | ${LIBTOOL} --mode=link ${CC} -o <replaceable>someprog</replaceable> <replaceable>../somelib/somelib.la</replaceable> |
872 | </programlisting> | | 872 | </programlisting> |
873 | | | 873 | |
874 | <para>and it will do the right thing with the libraries.</para> | | 874 | <para>and it will do the right thing with the libraries.</para> |
875 | </listitem> | | 875 | </listitem> |
876 | | | 876 | |
877 | <listitem> | | 877 | <listitem> |
878 | <para>When installing libraries, preface the &man.install.1; | | 878 | <para>When installing libraries, preface the &man.install.1; |
879 | or &man.cp.1; command with <quote>${LIBTOOL} | | 879 | or &man.cp.1; command with <quote>${LIBTOOL} |
880 | --mode=install</quote>, and change the library name to | | 880 | --mode=install</quote>, and change the library name to |
881 | <filename>.la</filename>. e.g.</para> | | 881 | <filename>.la</filename>. e.g.</para> |
882 | | | 882 | |
883 | <programlisting> | | 883 | <programlisting> |
884 | ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib | | 884 | ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib |
885 | </programlisting> | | 885 | </programlisting> |
886 | | | 886 | |
887 | <para>This will install the static <filename>.a</filename>, | | 887 | <para>This will install the static <filename>.a</filename>, |
888 | shared library, any needed symlinks, and run | | 888 | shared library, any needed symlinks, and run |
889 | &man.ldconfig.8;.</para> | | 889 | &man.ldconfig.8;.</para> |
890 | </listitem> | | 890 | </listitem> |
891 | | | 891 | |
892 | <listitem> | | 892 | <listitem> |
893 | <para>In your <filename>PLIST</filename>, include only | | 893 | <para>In your <filename>PLIST</filename>, include only |
894 | the <filename>.la</filename> | | 894 | the <filename>.la</filename> |
895 | file (this is a change from previous behaviour).</para> | | 895 | file (this is a change from previous behaviour).</para> |
896 | </listitem> | | 896 | </listitem> |
897 | </orderedlist> | | 897 | </orderedlist> |
898 | </sect2> | | 898 | </sect2> |
899 | | | 899 | |
900 | | | 900 | |
901 | <sect2 id="using-libtool"> | | 901 | <sect2 id="using-libtool"> |
902 | <title>Using libtool on GNU packages that already support libtool</title> | | 902 | <title>Using libtool on GNU packages that already support libtool</title> |
903 | | | 903 | |
904 | <para>Add <varname>USE_LIBTOOL=yes</varname> to the | | 904 | <para>Add <varname>USE_LIBTOOL=yes</varname> to the |
905 | package Makefile. This will override the package's own libtool | | 905 | package Makefile. This will override the package's own libtool |
906 | in most cases. For older libtool using packages, libtool is | | 906 | in most cases. For older libtool using packages, libtool is |
907 | made by ltconfig script during the do-configure step; you can | | 907 | made by ltconfig script during the do-configure step; you can |
908 | check the libtool script location by doing <command>make | | 908 | check the libtool script location by doing <command>make |
909 | configure; find work*/ -name libtool</command>.</para> | | 909 | configure; find work*/ -name libtool</command>.</para> |
910 | | | 910 | |
911 | <para><varname>LIBTOOL_OVERRIDE</varname> specifies which libtool | | 911 | <para><varname>LIBTOOL_OVERRIDE</varname> specifies which libtool |
912 | scripts, relative to <varname>WRKSRC</varname>, to override. By | | 912 | scripts, relative to <varname>WRKSRC</varname>, to override. By |
913 | default, it is set to <quote>libtool */libtool | | 913 | default, it is set to <quote>libtool */libtool |
914 | */*/libtool</quote>. If this does not match the location of the | | 914 | */*/libtool</quote>. If this does not match the location of the |
915 | package's libtool script(s), set it as appropriate.</para> | | 915 | package's libtool script(s), set it as appropriate.</para> |
916 | | | 916 | |
917 | <para>If you do not need <filename>*.a</filename> static | | 917 | <para>If you do not need <filename>*.a</filename> static |
918 | libraries built and installed, then use | | 918 | libraries built and installed, then use |
919 | <varname>SHLIBTOOL_OVERRIDE</varname> instead.</para> | | 919 | <varname>SHLIBTOOL_OVERRIDE</varname> instead.</para> |
920 | | | 920 | |
921 | <para>If your package makes use of the platform-independent library | | 921 | <para>If your package makes use of the platform-independent library |
922 | for loading dynamic shared objects, that comes with libtool | | 922 | for loading dynamic shared objects, that comes with libtool |
923 | (libltdl), you should include devel/libltdl/buildlink3.mk.</para> | | 923 | (libltdl), you should include devel/libltdl/buildlink3.mk.</para> |
924 | | | 924 | |
925 | <para>Some packages use libtool incorrectly so that the package | | 925 | <para>Some packages use libtool incorrectly so that the package |
926 | may not work or build in some circumstances. Some of the more | | 926 | may not work or build in some circumstances. Some of the more |
927 | common errors are:</para> | | 927 | common errors are:</para> |
928 | | | 928 | |
929 | <itemizedlist> | | 929 | <itemizedlist> |
930 | <listitem> | | 930 | <listitem> |
931 | <para>The inclusion of a shared object (-module) as a dependent library in an | | 931 | <para>The inclusion of a shared object (-module) as a dependent library in an |
932 | executable or library. This in itself isn't a problem if one of two things | | 932 | executable or library. This in itself isn't a problem if one of two things |
933 | has been done:</para> | | 933 | has been done:</para> |
934 | | | 934 | |
935 | <orderedlist> | | 935 | <orderedlist> |
936 | <listitem> | | 936 | <listitem> |
937 | <para>The shared object is named correctly, i.e. | | 937 | <para>The shared object is named correctly, i.e. |
938 | <filename>libfoo.la</filename>, not | | 938 | <filename>libfoo.la</filename>, not |
939 | <filename>foo.la</filename></para> | | 939 | <filename>foo.la</filename></para> |
940 | </listitem> | | 940 | </listitem> |
941 | | | 941 | |
942 | <listitem> | | 942 | <listitem> |
943 | <para>The -dlopen option is used when linking an executable.</para> | | 943 | <para>The -dlopen option is used when linking an executable.</para> |
944 | </listitem> | | 944 | </listitem> |
945 | </orderedlist> | | 945 | </orderedlist> |
946 | </listitem> | | 946 | </listitem> |
947 | | | 947 | |
948 | <listitem> | | 948 | <listitem> |
949 | <para>The use of libltdl without the correct calls to initialisation routines. | | 949 | <para>The use of libltdl without the correct calls to initialisation routines. |
950 | The function lt_dlinit() should be called and the macro | | 950 | The function lt_dlinit() should be called and the macro |
951 | <varname>LTDL_SET_PRELOADED_SYMBOLS</varname> included in | | 951 | <varname>LTDL_SET_PRELOADED_SYMBOLS</varname> included in |
952 | executables.</para> | | 952 | executables.</para> |
953 | </listitem> | | 953 | </listitem> |
954 | </itemizedlist> | | 954 | </itemizedlist> |
955 | </sect2> | | 955 | </sect2> |
956 | | | 956 | |
957 | | | 957 | |
958 | <sect2 id="autoconf-automake"> | | 958 | <sect2 id="autoconf-automake"> |
959 | <title>GNU Autoconf/Automake</title> | | 959 | <title>GNU Autoconf/Automake</title> |
960 | | | 960 | |
961 | <para>If a package needs GNU autoconf or automake to be executed | | 961 | <para>If a package needs GNU autoconf or automake to be executed |
962 | to regenerate the configure script and Makefile.in makefile | | 962 | to regenerate the configure script and Makefile.in makefile |
963 | templates, then they should be executed in a pre-configure | | 963 | templates, then they should be executed in a pre-configure |
964 | target.</para> | | 964 | target.</para> |
965 | | | 965 | |
966 | <para>For packages that need only autoconf:</para> | | 966 | <para>For packages that need only autoconf:</para> |
967 | | | 967 | |
968 | <programlisting> | | 968 | <programlisting> |
969 | AUTOCONF_REQD= 2.50 # if default version is not good enough | | 969 | AUTOCONF_REQD= 2.50 # if default version is not good enough |
970 | USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13 | | 970 | USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13 |
971 | ... | | 971 | ... |
972 | | | 972 | |
973 | pre-configure: | | 973 | pre-configure: |
974 | cd ${WRKSRC} && autoconf | | 974 | cd ${WRKSRC} && autoconf |
975 | | | 975 | |
976 | ... | | 976 | ... |
977 | </programlisting> | | 977 | </programlisting> |
978 | | | 978 | |
979 | <para>and for packages that need automake and autoconf:</para> | | 979 | <para>and for packages that need automake and autoconf:</para> |
980 | | | 980 | |
981 | <programlisting> | | 981 | <programlisting> |
982 | AUTOMAKE_REQD= 1.7.1 # if default version is not good enough | | 982 | AUTOMAKE_REQD= 1.7.1 # if default version is not good enough |
983 | USE_TOOLS+= automake # use "automake14" for automake-1.4 | | 983 | USE_TOOLS+= automake # use "automake14" for automake-1.4 |
984 | ... | | 984 | ... |
985 | | | 985 | |
986 | pre-configure: | | 986 | pre-configure: |
987 | set -e; cd ${WRKSRC}; \ | | 987 | set -e; cd ${WRKSRC}; \ |
988 | aclocal; autoheader; automake -a --foreign -i; autoconf | | 988 | aclocal; autoheader; automake -a --foreign -i; autoconf |
989 | | | 989 | |
990 | ... | | 990 | ... |
991 | </programlisting> | | 991 | </programlisting> |
992 | | | 992 | |
993 | <para>Packages which use GNU Automake will almost certainly | | 993 | <para>Packages which use GNU Automake will almost certainly |
994 | require GNU Make.</para> | | 994 | require GNU Make.</para> |
995 | | | 995 | |
996 | <para>There are times when the configure process makes | | 996 | <para>There are times when the configure process makes |
997 | additional changes to the generated files, which then causes | | 997 | additional changes to the generated files, which then causes |
998 | the build process to try to re-execute the automake sequence. | | 998 | the build process to try to re-execute the automake sequence. |
999 | This is prevented by touching various files in the configure | | 999 | This is prevented by touching various files in the configure |
1000 | stage. If this causes problems with your package you can set | | 1000 | stage. If this causes problems with your package you can set |
1001 | <varname>AUTOMAKE_OVERRIDE=NO</varname> in the package | | 1001 | <varname>AUTOMAKE_OVERRIDE=NO</varname> in the package |
1002 | Makefile.</para> | | 1002 | Makefile.</para> |
1003 | </sect2> | | 1003 | </sect2> |
1004 | </sect1> | | 1004 | </sect1> |
1005 | | | 1005 | |
1006 | <sect1 id="programming-languages"> | | 1006 | <sect1 id="programming-languages"> |
1007 | <title>Programming languages</title> | | 1007 | <title>Programming languages</title> |
1008 | | | 1008 | |
1009 | <sect2 id="basic-programming-languages"> | | 1009 | <sect2 id="basic-programming-languages"> |
1010 | <title>C, C++, and Fortran</title> | | 1010 | <title>C, C++, and Fortran</title> |
1011 | | | 1011 | |
1012 | <para>Compilers for the C, C++, and Fortran languages comes with | | 1012 | <para>Compilers for the C, C++, and Fortran languages comes with |
1013 | the NetBSD base system. By default, pkgsrc assumes that a package | | 1013 | the NetBSD base system. By default, pkgsrc assumes that a package |
1014 | is written in C and will hide all other compilers (via the wrapper | | 1014 | is written in C and will hide all other compilers (via the wrapper |
1015 | framework, see <xref linkend="buildlink" />).</para> | | 1015 | framework, see <xref linkend="buildlink" />).</para> |
1016 | | | 1016 | |
1017 | <para>To declare which language's compiler a package needs, set | | 1017 | <para>To declare which language's compiler a package needs, set |
1018 | the <varname>USE_LANGUAGES</varname> variable. Allowed values | | 1018 | the <varname>USE_LANGUAGES</varname> variable. Allowed values |
1019 | currently are <quote>c</quote>, <quote>c++</quote>, and | | 1019 | currently are <quote>c</quote>, <quote>c++</quote>, and |
1020 | <quote>fortran</quote> (and any combination). The default is | | 1020 | <quote>fortran</quote> (and any combination). The default is |
1021 | <quote>c</quote>. Packages using GNU configure scripts, even if | | 1021 | <quote>c</quote>. Packages using GNU configure scripts, even if |
1022 | written in C++, usually need a C compiler for the configure | | 1022 | written in C++, usually need a C compiler for the configure |
1023 | phase.</para> | | 1023 | phase.</para> |
1024 | </sect2> | | 1024 | </sect2> |
1025 | | | 1025 | |
1026 | <sect2 id="java-programming-language"> | | 1026 | <sect2 id="java-programming-language"> |
1027 | <title>Java</title> | | 1027 | <title>Java</title> |
1028 | | | 1028 | |
1029 | <para>If a program is written in Java, use the Java framework in | | 1029 | <para>If a program is written in Java, use the Java framework in |
1030 | pkgsrc. The package must include | | 1030 | pkgsrc. The package must include |
1031 | <filename>../../mk/java-vm.mk</filename>. This Makefile fragment | | 1031 | <filename>../../mk/java-vm.mk</filename>. This Makefile fragment |
1032 | provides the following variables:</para> | | 1032 | provides the following variables:</para> |
1033 | | | 1033 | |
1034 | <itemizedlist> | | 1034 | <itemizedlist> |
1035 | <listitem><para><varname>USE_JAVA</varname> defines if a build | | 1035 | <listitem><para><varname>USE_JAVA</varname> defines if a build |
1036 | dependency on the JDK is added. If | | 1036 | dependency on the JDK is added. If |
1037 | <varname>USE_JAVA</varname> is set to <quote>run</quote>, then | | 1037 | <varname>USE_JAVA</varname> is set to <quote>run</quote>, then |
1038 | there is only a runtime dependency on the JDK. The default is | | 1038 | there is only a runtime dependency on the JDK. The default is |
1039 | <quote>yes</quote>, which also adds a build dependency on the | | 1039 | <quote>yes</quote>, which also adds a build dependency on the |
1040 | JDK.</para></listitem> | | 1040 | JDK.</para></listitem> |
1041 | | | 1041 | |
1042 | <listitem><para>Set <varname>USE_JAVA2</varname> to declare that | | 1042 | <listitem><para>Set <varname>USE_JAVA2</varname> to declare that |
1043 | a package needs a Java2 implementation. The supported values | | 1043 | a package needs a Java2 implementation. The supported values |
1044 | are <quote>yes</quote>, <quote>1.4</quote>, and | | 1044 | are <quote>yes</quote>, <quote>1.4</quote>, and |
1045 | <quote>1.5</quote>. <quote>yes</quote> accepts any Java2 | | 1045 | <quote>1.5</quote>. <quote>yes</quote> accepts any Java2 |
1046 | implementation, <quote>1.4</quote> insists on versions 1.4 or | | 1046 | implementation, <quote>1.4</quote> insists on versions 1.4 or |
1047 | above, and <quote>1.5</quote> only accepts versions 1.5 or | | 1047 | above, and <quote>1.5</quote> only accepts versions 1.5 or |
1048 | above. This variable is not set by default.</para></listitem> | | 1048 | above. This variable is not set by default.</para></listitem> |
1049 | <!-- XXX: describe PKG_JVM_DEFAULT and PKG_JVMS_ACCEPTED, but | | 1049 | <!-- XXX: describe PKG_JVM_DEFAULT and PKG_JVMS_ACCEPTED, but |
1050 | not here --> | | 1050 | not here --> |
1051 | </itemizedlist> | | 1051 | </itemizedlist> |
1052 | </sect2> | | 1052 | </sect2> |
1053 | | | 1053 | |
1054 | <sect2 id="perl-scripts"> | | 1054 | <sect2 id="perl-scripts"> |
1055 | <title>Packages containing perl scripts</title> | | 1055 | <title>Packages containing perl scripts</title> |
1056 | | | 1056 | |
1057 | <para>If your package contains interpreted perl scripts, add | | 1057 | <para>If your package contains interpreted perl scripts, add |
1058 | <quote>perl</quote> to the <varname>USE_TOOLS</varname> variable | | 1058 | <quote>perl</quote> to the <varname>USE_TOOLS</varname> variable |
1059 | and set <varname>REPLACE_PERL</varname> to ensure that the proper | | 1059 | and set <varname>REPLACE_PERL</varname> to ensure that the proper |
1060 | interpreter path is set. <varname>REPLACE_PERL</varname> should | | 1060 | interpreter path is set. <varname>REPLACE_PERL</varname> should |
1061 | contain a list of scripts, relative to <varname>WRKSRC</varname>, | | 1061 | contain a list of scripts, relative to <varname>WRKSRC</varname>, |
1062 | that you want adjusted. Every occurrence of | | 1062 | that you want adjusted. Every occurrence of |
1063 | <filename>*/bin/perl</filename> will be replaced with the full | | 1063 | <filename>*/bin/perl</filename> will be replaced with the full |
1064 | path to the perl executable.</para> | | 1064 | path to the perl executable.</para> |
1065 | | | 1065 | |
1066 | <para>If a particular version of perl is needed, set the | | 1066 | <para>If a particular version of perl is needed, set the |
1067 | <varname>PERL5_REQD</varname> variable to the version number. The | | 1067 | <varname>PERL5_REQD</varname> variable to the version number. The |
1068 | default is <quote>5.0</quote>.</para> | | 1068 | default is <quote>5.0</quote>.</para> |
1069 | | | 1069 | |
1070 | <para>See <xref linkend="perl-modules" /> for information | | 1070 | <para>See <xref linkend="perl-modules" /> for information |
1071 | about handling perl modules.</para> | | 1071 | about handling perl modules.</para> |
1072 | </sect2> | | 1072 | </sect2> |
1073 | | | 1073 | |
1074 | <sect2 id="other-programming-languages"> | | 1074 | <sect2 id="other-programming-languages"> |
1075 | <title>Other programming languages</title> | | 1075 | <title>Other programming languages</title> |
1076 | | | 1076 | |
1077 | <para>Currently, there is no special handling for other languages | | 1077 | <para>Currently, there is no special handling for other languages |
1078 | in pkgsrc. If a compiler package provides a | | 1078 | in pkgsrc. If a compiler package provides a |
1079 | <filename>buildlink3.mk</filename> file, include that, otherwise | | 1079 | <filename>buildlink3.mk</filename> file, include that, otherwise |
1080 | just add a (build) dependency on the appropriate compiler | | 1080 | just add a (build) dependency on the appropriate compiler |
1081 | package.</para> | | 1081 | package.</para> |
1082 | </sect2> | | 1082 | </sect2> |
1083 | </sect1> | | 1083 | </sect1> |
1084 | | | 1084 | |
1085 | <sect1 id="fixes.build"> | | 1085 | <sect1 id="fixes.build"> |
1086 | <title>Fixing problems in the <emphasis>build</emphasis> phase</title> | | 1086 | <title>Fixing problems in the <emphasis>build</emphasis> phase</title> |
1087 | | | 1087 | |
1088 | <para>The most common failures when building a package are that | | 1088 | <para>The most common failures when building a package are that |
1089 | some platforms do not provide certain header files, functions or | | 1089 | some platforms do not provide certain header files, functions or |
1090 | libraries, or they provide the functions in a library that the | | 1090 | libraries, or they provide the functions in a library that the |
1091 | original package author didn't know. To work around this, you | | 1091 | original package author didn't know. To work around this, you |
1092 | can rewrite the source code in most cases so that it does not | | 1092 | can rewrite the source code in most cases so that it does not |
1093 | use the missing functions or provides a replacement function.</para> | | 1093 | use the missing functions or provides a replacement function.</para> |
1094 | | | 1094 | |
1095 | <sect2 id="fixes.build.cpp"> | | 1095 | <sect2 id="fixes.build.cpp"> |
1096 | <title>Compiling C and C++ code conditionally</title> | | 1096 | <title>Compiling C and C++ code conditionally</title> |
1097 | | | 1097 | |
1098 | <para>If a package already comes with a GNU configure script, the | | 1098 | <para>If a package already comes with a GNU configure script, the |
1099 | preferred way to fix the build failure is to change the | | 1099 | preferred way to fix the build failure is to change the |
1100 | configure script, not the code. In the other cases, you can | | 1100 | configure script, not the code. In the other cases, you can |
1101 | utilize the C preprocessor, which defines certain macros | | 1101 | utilize the C preprocessor, which defines certain macros |
1102 | depending on the operating system and hardware architecture it | | 1102 | depending on the operating system and hardware architecture it |
1103 | compiles for. These macros can be queried using for example | | 1103 | compiles for. These macros can be queried using for example |
1104 | <varname>#if defined(__i386)</varname>. Almost every operating | | 1104 | <varname>#if defined(__i386)</varname>. Almost every operating |
1105 | system, hardware architecture and compiler has its own macro. | | 1105 | system, hardware architecture and compiler has its own macro. |
1106 | For example, if the macros <varname>__GNUC__</varname>, | | 1106 | For example, if the macros <varname>__GNUC__</varname>, |
1107 | <varname>__i386__</varname> and <varname>__NetBSD__</varname> | | 1107 | <varname>__i386__</varname> and <varname>__NetBSD__</varname> |
1108 | are all defined, you know that you are using NetBSD on an i386 | | 1108 | are all defined, you know that you are using NetBSD on an i386 |
1109 | compatible CPU, and your compiler is GCC.</para> | | 1109 | compatible CPU, and your compiler is GCC.</para> |
1110 | | | 1110 | |
1111 | <para>The list of the following macros for hardware and | | 1111 | <para>The list of the following macros for hardware and |
1112 | operating system depends on the compiler that is used. For | | 1112 | operating system depends on the compiler that is used. For |
1113 | example, if you want to conditionally compile code on Solaris, | | 1113 | example, if you want to conditionally compile code on Solaris, |
1114 | don't use <varname>__sun__</varname>, as the SunPro compiler | | 1114 | don't use <varname>__sun__</varname>, as the SunPro compiler |
1115 | does not define it. Use <varname>__sun</varname> instead.</para> | | 1115 | does not define it. Use <varname>__sun</varname> instead.</para> |
1116 | | | 1116 | |
1117 | <sect3 id="fixes.build.cpp.os"> | | 1117 | <sect3 id="fixes.build.cpp.os"> |
1118 | <title>C preprocessor macros to identify the operating system</title> | | 1118 | <title>C preprocessor macros to identify the operating system</title> |
1119 | | | 1119 | |
1120 | <para>To distinguish between 4.4 BSD-derived systems and the | | 1120 | <para>To distinguish between 4.4 BSD-derived systems and the |
1121 | rest of the world, you should use the following code.</para> | | 1121 | rest of the world, you should use the following code.</para> |
1122 | | | 1122 | |
1123 | <programlisting> | | 1123 | <programlisting> |
1124 | #include <sys/param.h> | | 1124 | #include <sys/param.h> |
1125 | #if (defined(BSD) && BSD >= 199306) | | 1125 | #if (defined(BSD) && BSD >= 199306) |
1126 | /* BSD-specific code goes here */ | | 1126 | /* BSD-specific code goes here */ |
1127 | #else | | 1127 | #else |
1128 | /* non-BSD-specific code goes here */ | | 1128 | /* non-BSD-specific code goes here */ |
1129 | #endif | | 1129 | #endif |
1130 | </programlisting> | | 1130 | </programlisting> |
1131 | | | 1131 | |
1132 | <para>If this distinction is not fine enough, you can also test | | 1132 | <para>If this distinction is not fine enough, you can also test |
1133 | for the following macros.</para> | | 1133 | for the following macros.</para> |
1134 | | | 1134 | |
1135 | <programlisting> | | 1135 | <programlisting> |
1136 | FreeBSD __FreeBSD__ | | 1136 | FreeBSD __FreeBSD__ |
1137 | DragonFly __DragonFly__ | | 1137 | DragonFly __DragonFly__ |
1138 | Interix __INTERIX | | 1138 | Interix __INTERIX |
1139 | IRIX __sgi (TODO: get a definite source for this) | | 1139 | IRIX __sgi (TODO: get a definite source for this) |
1140 | Linux linux, __linux, __linux__ | | 1140 | Linux linux, __linux, __linux__ |
1141 | NetBSD __NetBSD__ | | 1141 | NetBSD __NetBSD__ |
1142 | OpenBSD __OpenBSD__ | | 1142 | OpenBSD __OpenBSD__ |
1143 | Solaris sun, __sun | | 1143 | Solaris sun, __sun |
1144 | </programlisting> | | 1144 | </programlisting> |
1145 | | | 1145 | |
1146 | </sect3> | | 1146 | </sect3> |
1147 | <sect3 id="fixes.build.cpp.arch"> | | 1147 | <sect3 id="fixes.build.cpp.arch"> |
1148 | <title>C preprocessor macros to identify the hardware architecture</title> | | 1148 | <title>C preprocessor macros to identify the hardware architecture</title> |
1149 | | | 1149 | |
1150 | <programlisting> | | 1150 | <programlisting> |
1151 | i386 i386, __i386, __i386__ | | 1151 | i386 i386, __i386, __i386__ |
1152 | MIPS __mips | | 1152 | MIPS __mips |
1153 | SPARC sparc, __sparc | | 1153 | SPARC sparc, __sparc |
1154 | </programlisting> | | 1154 | </programlisting> |
1155 | | | 1155 | |
1156 | </sect3> | | 1156 | </sect3> |
1157 | <sect3 id="fixes.build.cpp.compiler"> | | 1157 | <sect3 id="fixes.build.cpp.compiler"> |
1158 | <title>C preprocessor macros to identify the compiler</title> | | 1158 | <title>C preprocessor macros to identify the compiler</title> |
1159 | | | 1159 | |
1160 | <programlisting> | | 1160 | <programlisting> |
1161 | GCC __GNUC__ (major version), __GNUC_MINOR__ | | 1161 | GCC __GNUC__ (major version), __GNUC_MINOR__ |
1162 | MIPSpro _COMPILER_VERSION (0x741 for MIPSpro 7.41) | | 1162 | MIPSpro _COMPILER_VERSION (0x741 for MIPSpro 7.41) |
1163 | SunPro __SUNPRO_C (0x570 for Sun C 5.7) | | 1163 | SunPro __SUNPRO_C (0x570 for Sun C 5.7) |
1164 | SunPro C++ __SUNPRO_CC (0x580 for Sun C++ 5.8) | | 1164 | SunPro C++ __SUNPRO_CC (0x580 for Sun C++ 5.8) |
1165 | </programlisting> | | 1165 | </programlisting> |
1166 | | | 1166 | |
1167 | </sect3> | | 1167 | </sect3> |
1168 | </sect2> | | 1168 | </sect2> |
1169 | <sect2 id="compiler-bugs"> | | 1169 | <sect2 id="compiler-bugs"> |
1170 | <title>How to handle compiler bugs</title> | | 1170 | <title>How to handle compiler bugs</title> |
1171 | | | 1171 | |
1172 | <para>Some source files trigger bugs in the compiler, based on | | 1172 | <para>Some source files trigger bugs in the compiler, based on |
1173 | combinations of compiler version and architecture and almost | | 1173 | combinations of compiler version and architecture and almost |
1174 | always relation to optimisation being enabled. Common symptoms | | 1174 | always relation to optimisation being enabled. Common symptoms |
1175 | are gcc internal errors or never finishing compiling a | | 1175 | are gcc internal errors or never finishing compiling a |
1176 | file.</para> | | 1176 | file.</para> |
1177 | | | 1177 | |
1178 | <para>Typically, a workaround involves testing the | | 1178 | <para>Typically, a workaround involves testing the |
1179 | <varname>MACHINE_ARCH</varname> and compiler version, disabling | | 1179 | <varname>MACHINE_ARCH</varname> and compiler version, disabling |
1180 | optimisation for that combination of file, | | 1180 | optimisation for that combination of file, |
1181 | <varname>MACHINE_ARCH</varname> and compiler, and documenting it | | 1181 | <varname>MACHINE_ARCH</varname> and compiler, and documenting it |
1182 | in <filename>pkgsrc/doc/HACKS</filename>. See that file for a | | 1182 | in <filename>pkgsrc/doc/HACKS</filename>. See that file for a |
1183 | number of examples.</para> | | 1183 | number of examples.</para> |
1184 | | | 1184 | |
1185 | </sect2> | | 1185 | </sect2> |
1186 | | | 1186 | |
1187 | <sect2 id="undefined-reference"> | | 1187 | <sect2 id="undefined-reference"> |
1188 | <title>Undefined reference to <quote>...</quote></title> | | 1188 | <title>Undefined reference to <quote>...</quote></title> |
1189 | | | 1189 | |
1190 | <para>This error message often means that a package did not | | 1190 | <para>This error message often means that a package did not |
1191 | link to a shared library it needs. The following functions are | | 1191 | link to a shared library it needs. The following functions are |
1192 | known to cause this error message over and over.</para> | | 1192 | known to cause this error message over and over.</para> |
1193 | | | 1193 | |
1194 | <informaltable id="undefined-reference-functions"> | | 1194 | <informaltable id="undefined-reference-functions"> |
1195 | <tgroup cols="3"> | | 1195 | <tgroup cols="3"> |
1196 | <thead><row><entry>Function</entry><entry>Library</entry><entry>Affected platforms</entry></row></thead> | | 1196 | <thead><row><entry>Function</entry><entry>Library</entry><entry>Affected platforms</entry></row></thead> |
1197 | <tbody> | | 1197 | <tbody> |
1198 | <row><entry>accept, bind, connect</entry><entry>-lsocket</entry><entry>Solaris</entry></row> | | 1198 | <row><entry>accept, bind, connect</entry><entry>-lsocket</entry><entry>Solaris</entry></row> |
1199 | <row><entry>crypt</entry><entry>-lcrypt</entry><entry>DragonFly, NetBSD</entry></row> | | 1199 | <row><entry>crypt</entry><entry>-lcrypt</entry><entry>DragonFly, NetBSD</entry></row> |
1200 | <row><entry>dlopen, dlsym</entry><entry>-ldl</entry><entry>Linux</entry></row> | | 1200 | <row><entry>dlopen, dlsym</entry><entry>-ldl</entry><entry>Linux</entry></row> |
1201 | <row><entry>gethost*</entry><entry>-lnsl</entry><entry>Solaris</entry></row> | | 1201 | <row><entry>gethost*</entry><entry>-lnsl</entry><entry>Solaris</entry></row> |
1202 | <row><entry>inet_aton</entry><entry>-lresolv</entry><entry>Solaris</entry></row> | | 1202 | <row><entry>inet_aton</entry><entry>-lresolv</entry><entry>Solaris</entry></row> |
1203 | <row><entry>nanosleep, sem_*, timer_*</entry><entry>-lrt</entry><entry>Solaris</entry></row> | | 1203 | <row><entry>nanosleep, sem_*, timer_*</entry><entry>-lrt</entry><entry>Solaris</entry></row> |
1204 | <row><entry>openpty</entry><entry>-lutil</entry><entry>Linux</entry></row> | | 1204 | <row><entry>openpty</entry><entry>-lutil</entry><entry>Linux</entry></row> |
1205 | </tbody> | | 1205 | </tbody> |
1206 | </tgroup> | | 1206 | </tgroup> |
1207 | </informaltable> | | 1207 | </informaltable> |
1208 | | | 1208 | |
1209 | <para>To fix these linker errors, it is often sufficient to say | | 1209 | <para>To fix these linker errors, it is often sufficient to say |
1210 | <literal>LIBS.<replaceable>OperatingSystem</replaceable>+= | | 1210 | <literal>LIBS.<replaceable>OperatingSystem</replaceable>+= |
1211 | -l<replaceable>foo</replaceable></literal> to the package | | 1211 | -l<replaceable>foo</replaceable></literal> to the package |
1212 | <filename>Makefile</filename> and then say <command>bmake clean; | | 1212 | <filename>Makefile</filename> and then say <command>bmake clean; |
1213 | bmake</command>.</para> | | 1213 | bmake</command>.</para> |
1214 | | | 1214 | |
1215 | <sect3 id="undefined-reference-sunpro"> | | 1215 | <sect3 id="undefined-reference-sunpro"> |
1216 | <title>Special issue: The SunPro compiler</title> | | 1216 | <title>Special issue: The SunPro compiler</title> |
1217 | | | 1217 | |
1218 | <para>When you are using the SunPro compiler, there is another | | 1218 | <para>When you are using the SunPro compiler, there is another |
1219 | possibility. That compiler cannot handle the following code:</para> | | 1219 | possibility. That compiler cannot handle the following code:</para> |
1220 | | | 1220 | |
1221 | <programlisting> | | 1221 | <programlisting> |
1222 | extern int extern_func(int); | | 1222 | extern int extern_func(int); |
1223 | | | 1223 | |
1224 | static inline int | | 1224 | static inline int |
1225 | inline_func(int x) | | 1225 | inline_func(int x) |
1226 | { | | 1226 | { |
1227 | return extern_func(x); | | 1227 | return extern_func(x); |
1228 | } | | 1228 | } |
1229 | | | 1229 | |
1230 | int main(void) | | 1230 | int main(void) |
1231 | { | | 1231 | { |
1232 | return 0; | | 1232 | return 0; |
1233 | } | | 1233 | } |
1234 | </programlisting> | | 1234 | </programlisting> |
1235 | | | 1235 | |
1236 | <para>It generates the code for <function>inline_func</function> even if | | 1236 | <para>It generates the code for <function>inline_func</function> even if |
1237 | that function is never used. This code then refers to | | 1237 | that function is never used. This code then refers to |
1238 | <function>extern_func</function>, which can usually not be resolved. To | | 1238 | <function>extern_func</function>, which can usually not be resolved. To |
1239 | solve this problem you can try to tell the package to disable inlining | | 1239 | solve this problem you can try to tell the package to disable inlining |
1240 | of functions.</para> | | 1240 | of functions.</para> |
1241 | | | 1241 | |
1242 | </sect3> | | 1242 | </sect3> |
1243 | | | 1243 | |
1244 | </sect2> | | 1244 | </sect2> |
1245 | | | 1245 | |
1246 | <sect2 id="out-of-memory"> | | 1246 | <sect2 id="out-of-memory"> |
1247 | <title>Running out of memory</title> | | 1247 | <title>Running out of memory</title> |
1248 | | | 1248 | |
1249 | <para>Sometimes packages fail to build because the compiler runs | | 1249 | <para>Sometimes packages fail to build because the compiler runs |
1250 | into an operating system specific soft limit. With the | | 1250 | into an operating system specific soft limit. With the |
1251 | <varname>UNLIMIT_RESOURCES</varname> variable pkgsrc can be told | | 1251 | <varname>UNLIMIT_RESOURCES</varname> variable pkgsrc can be told |
1252 | to unlimit the resources. Currently, the allowed values are | | 1252 | to unlimit the resources. Currently, the allowed values are |
1253 | <quote>datasize</quote> and <quote>stacksize</quote> (or both). | | 1253 | <quote>datasize</quote> and <quote>stacksize</quote> (or both). |
1254 | Setting this variable is similar to running the shell builtin | | 1254 | Setting this variable is similar to running the shell builtin |
1255 | <command>ulimit</command> command to raise the maximum data | | 1255 | <command>ulimit</command> command to raise the maximum data |
1256 | segment size or maximum stack size of a process, respectively, to | | 1256 | segment size or maximum stack size of a process, respectively, to |
1257 | their hard limits.</para> | | 1257 | their hard limits.</para> |
1258 | </sect2> | | 1258 | </sect2> |
1259 | </sect1> | | 1259 | </sect1> |
1260 | | | 1260 | |
1261 | <sect1 id="fixes.install"> | | 1261 | <sect1 id="fixes.install"> |
1262 | <title>Fixing problems in the <emphasis>install</emphasis> phase</title> | | 1262 | <title>Fixing problems in the <emphasis>install</emphasis> phase</title> |
1263 | | | 1263 | |
1264 | <sect2 id="install-scripts"> | | 1264 | <sect2 id="install-scripts"> |
1265 | <title>Creating needed directories</title> | | 1265 | <title>Creating needed directories</title> |
1266 | | | 1266 | |
1267 | <para>The BSD-compatible <command>install</command> supplied | | 1267 | <para>The BSD-compatible <command>install</command> supplied |
1268 | with some operating systems cannot create more than one | | 1268 | with some operating systems cannot create more than one |
1269 | directory at a time. As such, you should call | | 1269 | directory at a time. As such, you should call |
1270 | <literal>${INSTALL_*_DIR}</literal> like this:</para> | | 1270 | <literal>${INSTALL_*_DIR}</literal> like this:</para> |
1271 | | | 1271 | |
1272 | <programlisting> | | 1272 | <programlisting> |
1273 | ${INSTALL_DATA_DIR} ${PREFIX}/dir1 | | 1273 | ${INSTALL_DATA_DIR} ${PREFIX}/dir1 |
1274 | ${INSTALL_DATA_DIR} ${PREFIX}/dir2 | | 1274 | ${INSTALL_DATA_DIR} ${PREFIX}/dir2 |
1275 | </programlisting> | | 1275 | </programlisting> |
1276 | | | 1276 | |
1277 | <para>You can also just append <quote><literal>dir1 | | 1277 | <para>You can also just append <quote><literal>dir1 |
1278 | dir2</literal></quote> to the | | 1278 | dir2</literal></quote> to the |
1279 | <varname>INSTALLATION_DIRS</varname> variable, which will | | 1279 | <varname>INSTALLATION_DIRS</varname> variable, which will |
1280 | automatically do the right thing.</para> | | 1280 | automatically do the right thing.</para> |
1281 | | | 1281 | |
1282 | </sect2> | | 1282 | </sect2> |
1283 | <sect2 id="where-to-install-documentation"> | | 1283 | <sect2 id="where-to-install-documentation"> |
1284 | <title>Where to install documentation</title> | | 1284 | <title>Where to install documentation</title> |
1285 | | | 1285 | |
1286 | <para>In general, documentation should be installed into | | 1286 | <para>In general, documentation should be installed into |
1287 | <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or | | 1287 | <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or |
1288 | <filename>${PREFIX}/share/doc/${PKGNAME}</filename> (the latter | | 1288 | <filename>${PREFIX}/share/doc/${PKGNAME}</filename> (the latter |
1289 | includes the version number of the package).</para> | | 1289 | includes the version number of the package).</para> |
1290 | | | 1290 | |
1291 | <para>Many modern packages using GNU autoconf allow to set the | | 1291 | <para>Many modern packages using GNU autoconf allow to set the |
1292 | directory where HTML documentation is installed with the | | 1292 | directory where HTML documentation is installed with the |
1293 | <quote>--with-html-dir</quote> option. Sometimes using this flag | | 1293 | <quote>--with-html-dir</quote> option. Sometimes using this flag |
1294 | is needed because otherwise the documentation ends up in | | 1294 | is needed because otherwise the documentation ends up in |
1295 | <filename>${PREFIX}/share/doc/html</filename> or other | | 1295 | <filename>${PREFIX}/share/doc/html</filename> or other |
1296 | places.</para> | | 1296 | places.</para> |
1297 | | | 1297 | |
1298 | <para>An exception to the above is that library API documentation | | 1298 | <para>An exception to the above is that library API documentation |
1299 | generated with the <filename | | 1299 | generated with the <filename |
1300 | role="pkg">textproc/gtk-doc</filename> tools, for use by special | | 1300 | role="pkg">textproc/gtk-doc</filename> tools, for use by special |
1301 | browsers (devhelp) should be left at their default location, which | | 1301 | browsers (devhelp) should be left at their default location, which |
1302 | is <filename>${PREFIX}/share/gtk-doc</filename>. Such | | 1302 | is <filename>${PREFIX}/share/gtk-doc</filename>. Such |
1303 | documentation can be recognized from files ending in | | 1303 | documentation can be recognized from files ending in |
1304 | <filename>.devhelp</filename> or <filename>.devhelp2</filename>. | | 1304 | <filename>.devhelp</filename> or <filename>.devhelp2</filename>. |
1305 | (It is also acceptable to install such files in | | 1305 | (It is also acceptable to install such files in |
1306 | <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or | | 1306 | <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or |
1307 | <filename>${PREFIX}/share/doc/${PKGNAME}</filename>; the | | 1307 | <filename>${PREFIX}/share/doc/${PKGNAME}</filename>; the |
1308 | <filename>.devhelp*</filename> file must be directly in that | | 1308 | <filename>.devhelp*</filename> file must be directly in that |
1309 | directory then, no additional subdirectory level is allowed in | | 1309 | directory then, no additional subdirectory level is allowed in |
1310 | this case. This is usually achieved by using | | 1310 | this case. This is usually achieved by using |
1311 | <quote>--with-html-dir=${PREFIX}/share/doc</quote>. | | 1311 | <quote>--with-html-dir=${PREFIX}/share/doc</quote>. |
1312 | <filename>${PREFIX}/share/gtk-doc</filename> is preferred | | 1312 | <filename>${PREFIX}/share/gtk-doc</filename> is preferred |
1313 | though.)</para> | | 1313 | though.)</para> |
1314 | | | 1314 | |
1315 | </sect2> | | 1315 | </sect2> |
1316 | | | 1316 | |
1317 | <sect2 id="installing-score-files"> | | 1317 | <sect2 id="installing-score-files"> |
1318 | <title>Installing highscore files</title> | | 1318 | <title>Installing highscore files</title> |
1319 | | | 1319 | |
1320 | <para>Certain packages, most of them in the games category, install | | 1320 | <para>Certain packages, most of them in the games category, install |
1321 | a score file that allows all users on the system to record their | | 1321 | a score file that allows all users on the system to record their |
1322 | highscores. In order for this to work, the binaries need to be | | 1322 | highscores. In order for this to work, the binaries need to be |
1323 | installed setgid and the score files owned by the appropriate | | 1323 | installed setgid and the score files owned by the appropriate |
1324 | group and/or owner (traditionally the "games" user/group). The | | 1324 | group and/or owner (traditionally the "games" user/group). The |
1325 | following variables, documented in more detail in | | 1325 | following variables, documented in more detail in |
1326 | <filename>mk/defaults/mk.conf</filename>, control this | | 1326 | <filename>mk/defaults/mk.conf</filename>, control this |
1327 | behaviour: <varname>SETGIDGAME</varname>, | | 1327 | behaviour: <varname>SETGIDGAME</varname>, |
1328 | <varname>GAMEDATAMODE</varname>, <varname>GAMEGRP</varname>, | | 1328 | <varname>GAMEDATAMODE</varname>, <varname>GAMEGRP</varname>, |
1329 | <varname>GAMEMODE</varname>, <varname>GAMEOWN</varname>.</para> | | 1329 | <varname>GAMEMODE</varname>, <varname>GAMEOWN</varname>.</para> |
1330 | | | 1330 | |
1331 | <para>Note that per default, setgid installation of games is | | 1331 | <para>Note that per default, setgid installation of games is |
1332 | disabled; setting <varname>SETGIDGAME=YES</varname> will set all | | 1332 | disabled; setting <varname>SETGIDGAME=YES</varname> will set all |
1333 | the other variables accordingly.</para> | | 1333 | the other variables accordingly.</para> |
1334 | | | 1334 | |
1335 | <para>A package should therefore never hard code file ownership or | | 1335 | <para>A package should therefore never hard code file ownership or |
1336 | access permissions but rely on <varname>INSTALL_GAME</varname> and | | 1336 | access permissions but rely on <varname>INSTALL_GAME</varname> and |
1337 | <varname>INSTALL_GAME_DATA</varname> to set these | | 1337 | <varname>INSTALL_GAME_DATA</varname> to set these |
1338 | correctly.</para> | | 1338 | correctly.</para> |
1339 | </sect2> | | 1339 | </sect2> |
1340 | | | 1340 | |
1341 | <sect2 id="destdir-support"> | | 1341 | <sect2 id="destdir-support"> |
1342 | <title>Adding DESTDIR support to packages</title> | | 1342 | <title>Adding DESTDIR support to packages</title> |
1343 | | | 1343 | |
1344 | <para><varname>DESTDIR</varname> support means that a package | | 1344 | <para><varname>DESTDIR</varname> support means that a package |
1345 | installs into a staging directory, not the final location of the | | 1345 | installs into a staging directory, not the final location of the |
1346 | files. Then a binary package is created which can be used for | | 1346 | files. Then a binary package is created which can be used for |
1347 | installation as usual. There are two ways: Either the package must | | 1347 | installation as usual. There are two ways: Either the package must |
1348 | install as root (<quote>destdir</quote>) or the package can | | 1348 | install as root (<quote>destdir</quote>) or the package can |
1349 | install as non-root user (<quote>user-destdir</quote>).</para> | | 1349 | install as non-root user (<quote>user-destdir</quote>).</para> |
1350 | | | 1350 | |
1351 | <itemizedlist> | | 1351 | <itemizedlist> |
1352 | <listitem><para><varname>PKG_DESTDIR_SUPPORT</varname> has to be | | 1352 | <listitem><para><varname>PKG_DESTDIR_SUPPORT</varname> has to be |
1353 | set to <quote>destdir</quote> or <quote>user-destdir</quote>. If | | 1353 | set to <quote>destdir</quote> or <quote>user-destdir</quote>. If |
1354 | bsd.prefs.mk is included in the Makefile, | | 1354 | bsd.prefs.mk is included in the Makefile, |
1355 | <varname>PKG_DESTDIR_SUPPORT</varname> needs to be set before | | 1355 | <varname>PKG_DESTDIR_SUPPORT</varname> needs to be set before |
1356 | the inclusion.</para></listitem> | | 1356 | the inclusion.</para></listitem> |
1357 | | | 1357 | |
1358 | <listitem><para>All installation operations have to be prefixed with | | 1358 | <listitem><para>All installation operations have to be prefixed with |
1359 | <filename>${DESTDIR}</filename>.</para></listitem> | | 1359 | <filename>${DESTDIR}</filename>.</para></listitem> |
1360 | | | 1360 | |
1361 | <listitem><para>automake gets this DESTDIR mostly right | | 1361 | <listitem><para>automake gets this DESTDIR mostly right |
1362 | automatically. Many manual rules and pre/post-install often are | | 1362 | automatically. Many manual rules and pre/post-install often are |
1363 | incorrect; fix them.</para></listitem> | | 1363 | incorrect; fix them.</para></listitem> |
1364 | | | 1364 | |
1365 | <listitem><para>If files are installed with special owner/group | | 1365 | <listitem><para>If files are installed with special owner/group |
1366 | use <varname>SPECIAL_PERMS</varname>.</para></listitem> | | 1366 | use <varname>SPECIAL_PERMS</varname>.</para></listitem> |
1367 | | | 1367 | |
1368 | <listitem><para>In general, packages should support | | 1368 | <listitem><para>In general, packages should support |
1369 | <varname>UNPRIVILEGED</varname> to be able to use | | 1369 | <varname>UNPRIVILEGED</varname> to be able to use |
1370 | DESTDIR.</para></listitem> | | 1370 | DESTDIR.</para></listitem> |
1371 | | | 1371 | |
1372 | </itemizedlist> | | 1372 | </itemizedlist> |
1373 | </sect2> | | 1373 | </sect2> |
1374 | | | 1374 | |
1375 | | | 1375 | |
1376 | <sect2 id="hardcoded-paths"> | | 1376 | <sect2 id="hardcoded-paths"> |
1377 | <title>Packages with hardcoded paths to other interpreters</title> | | 1377 | <title>Packages with hardcoded paths to other interpreters</title> |
1378 | | | 1378 | |
1379 | <para>Your package may also contain scripts with hardcoded paths to | | 1379 | <para>Your package may also contain scripts with hardcoded paths to |
1380 | other interpreters besides (or as well as) perl. To correct the | | 1380 | other interpreters besides (or as well as) perl. To correct the |
1381 | full pathname to the script interpreter, you need to set the | | 1381 | full pathname to the script interpreter, you need to set the |
1382 | following definitions in your <filename>Makefile</filename> (we | | 1382 | following definitions in your <filename>Makefile</filename> (we |
1383 | shall use <command>tclsh</command> in this example):</para> | | 1383 | shall use <command>tclsh</command> in this example):</para> |
1384 | | | 1384 | |
1385 | <programlisting> | | 1385 | <programlisting> |
1386 | REPLACE_INTERPRETER+= tcl | | 1386 | REPLACE_INTERPRETER+= tcl |
1387 | REPLACE.tcl.old= .*/bin/tclsh | | 1387 | REPLACE.tcl.old= .*/bin/tclsh |
1388 | REPLACE.tcl.new= ${PREFIX}/bin/tclsh | | 1388 | REPLACE.tcl.new= ${PREFIX}/bin/tclsh |
1389 | REPLACE_FILES.tcl= # list of tcl scripts which need to be fixed, | | 1389 | REPLACE_FILES.tcl= # list of tcl scripts which need to be fixed, |
1390 | # relative to ${WRKSRC}, just as in REPLACE_PERL | | 1390 | # relative to ${WRKSRC}, just as in REPLACE_PERL |
1391 | </programlisting> | | 1391 | </programlisting> |
1392 | | | 1392 | |
1393 | <note><para>Before March 2006, these variables were called | | 1393 | <note><para>Before March 2006, these variables were called |
1394 | <varname>_REPLACE.*</varname> and | | 1394 | <varname>_REPLACE.*</varname> and |
1395 | <varname>_REPLACE_FILES.*</varname>.</para></note> | | 1395 | <varname>_REPLACE_FILES.*</varname>.</para></note> |
1396 | | | 1396 | |
1397 | </sect2> | | 1397 | </sect2> |
1398 | | | 1398 | |
1399 | | | 1399 | |
1400 | <sect2 id="perl-modules"> | | 1400 | <sect2 id="perl-modules"> |
1401 | <title>Packages installing perl modules</title> | | 1401 | <title>Packages installing perl modules</title> |
1402 | | | 1402 | |
1403 | <para>Makefiles of packages providing perl5 modules should include | | 1403 | <para>Makefiles of packages providing perl5 modules should include |
1404 | the Makefile fragment | | 1404 | the Makefile fragment |
1405 | <filename>../../lang/perl5/module.mk</filename>. It provides a | | 1405 | <filename>../../lang/perl5/module.mk</filename>. It provides a |
1406 | <command>do-configure</command> target for the standard perl | | 1406 | <command>do-configure</command> target for the standard perl |
1407 | configuration for such modules as well as various hooks to tune | | 1407 | configuration for such modules as well as various hooks to tune |
1408 | this configuration. See comments in this file for | | 1408 | this configuration. See comments in this file for |
1409 | details.</para> | | 1409 | details.</para> |
1410 | | | 1410 | |
1411 | <para>Perl5 modules will install into different places depending | | 1411 | <para>Perl5 modules will install into different places depending |
1412 | on the version of perl used during the build process. To | | 1412 | on the version of perl used during the build process. To |
1413 | address this, pkgsrc will append lines to the | | 1413 | address this, pkgsrc will append lines to the |
1414 | <filename>PLIST</filename> corresponding to the files listed in | | 1414 | <filename>PLIST</filename> corresponding to the files listed in |
1415 | the installed <filename>.packlist</filename> file generated by | | 1415 | the installed <filename>.packlist</filename> file generated by |
1416 | most perl5 modules. This is invoked by defining | | 1416 | most perl5 modules. This is invoked by defining |
1417 | <varname>PERL5_PACKLIST</varname> to a space-separated list of | | 1417 | <varname>PERL5_PACKLIST</varname> to a space-separated list of |
1418 | paths to packlist files, e.g.:</para> | | 1418 | paths to packlist files, e.g.:</para> |
1419 | | | 1419 | |
1420 | <programlisting> | | 1420 | <programlisting> |
1421 | PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist | | 1421 | PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist |
1422 | </programlisting> | | 1422 | </programlisting> |
1423 | | | 1423 | |
1424 | <para>The variables <varname>PERL5_SITELIB</varname>, | | 1424 | <para>The variables <varname>PERL5_SITELIB</varname>, |
1425 | <varname>PERL5_SITEARCH</varname>, and | | 1425 | <varname>PERL5_SITEARCH</varname>, and |
1426 | <varname>PERL5_ARCHLIB</varname> represent the three locations | | 1426 | <varname>PERL5_ARCHLIB</varname> represent the three locations |
1427 | in which perl5 modules may be installed, and may be used by | | 1427 | in which perl5 modules may be installed, and may be used by |
1428 | perl5 packages that don't have a packlist. These three | | 1428 | perl5 packages that don't have a packlist. These three |
1429 | variables are also substituted for in the | | 1429 | variables are also substituted for in the |
1430 | <filename>PLIST</filename>.</para> | | 1430 | <filename>PLIST</filename>.</para> |
1431 | </sect2> | | 1431 | </sect2> |
1432 | | | 1432 | |
1433 | | | 1433 | |
1434 | <sect2 id="faq.info-files"> | | 1434 | <sect2 id="faq.info-files"> |
1435 | <title>Packages installing info files</title> | | 1435 | <title>Packages installing info files</title> |
1436 | | | 1436 | |
1437 | <para>Some packages install info files or use the | | 1437 | <para>Some packages install info files or use the |
1438 | <quote>makeinfo</quote> or <quote>install-info</quote> | | 1438 | <quote>makeinfo</quote> or <quote>install-info</quote> |
1439 | commands. <varname>INFO_FILES</varname> should be defined in | | 1439 | commands. <varname>INFO_FILES</varname> should be defined in |
1440 | the package Makefile so that <filename>INSTALL</filename> and | | 1440 | the package Makefile so that <filename>INSTALL</filename> and |
1441 | <filename>DEINSTALL</filename> scripts will be generated to | | 1441 | <filename>DEINSTALL</filename> scripts will be generated to |
1442 | handle registration of the info files in the Info directory | | 1442 | handle registration of the info files in the Info directory |
1443 | file. The <quote>install-info</quote> command used for the info | | 1443 | file. The <quote>install-info</quote> command used for the info |
1444 | files registration is either provided by the system, or by a | | 1444 | files registration is either provided by the system, or by a |
1445 | special purpose package automatically added as dependency if | | 1445 | special purpose package automatically added as dependency if |
1446 | needed.</para> | | 1446 | needed.</para> |
1447 | | | 1447 | |
1448 | <para><varname>PKGINFODIR</varname> is the directory under | | 1448 | <para><varname>PKGINFODIR</varname> is the directory under |
1449 | <filename>${PREFIX}</filename> where info files are primarily | | 1449 | <filename>${PREFIX}</filename> where info files are primarily |
1450 | located. <varname>PKGINFODIR</varname> defaults to | | 1450 | located. <varname>PKGINFODIR</varname> defaults to |
1451 | <quote>info</quote> and can be overridden by the user.</para> | | 1451 | <quote>info</quote> and can be overridden by the user.</para> |
1452 | | | 1452 | |
1453 | <para>The info files for the package should be listed in the | | 1453 | <para>The info files for the package should be listed in the |
1454 | package <filename>PLIST</filename>; however any split info files | | 1454 | package <filename>PLIST</filename>; however any split info files |
1455 | need not be listed.</para> | | 1455 | need not be listed.</para> |
1456 | | | 1456 | |
1457 | <para>A package which needs the <quote>makeinfo</quote> command | | 1457 | <para>A package which needs the <quote>makeinfo</quote> command |
1458 | at build time must add <quote>makeinfo</quote> to | | 1458 | at build time must add <quote>makeinfo</quote> to |
1459 | <varname>USE_TOOLS</varname> in its Makefile. If a minimum | | 1459 | <varname>USE_TOOLS</varname> in its Makefile. If a minimum |
1460 | version of the <quote>makeinfo</quote> command is needed it | | 1460 | version of the <quote>makeinfo</quote> command is needed it |
1461 | should be noted with the <varname>TEXINFO_REQD</varname> | | 1461 | should be noted with the <varname>TEXINFO_REQD</varname> |
1462 | variable in the package <filename>Makefile</filename>. By | | 1462 | variable in the package <filename>Makefile</filename>. By |
1463 | default, a minimum version of 3.12 is required. If the system | | 1463 | default, a minimum version of 3.12 is required. If the system |
1464 | does not provide a <command>makeinfo</command> command or if it | | 1464 | does not provide a <command>makeinfo</command> command or if it |
1465 | does not match the required minimum, a build dependency on the | | 1465 | does not match the required minimum, a build dependency on the |
1466 | <filename role="pkg">devel/gtexinfo</filename> package will | | 1466 | <filename role="pkg">devel/gtexinfo</filename> package will |
1467 | be added automatically.</para> | | 1467 | be added automatically.</para> |
1468 | | | 1468 | |
1469 | <para>The build and installation process of the software provided | | 1469 | <para>The build and installation process of the software provided |
1470 | by the package should not use the | | 1470 | by the package should not use the |
1471 | <command>install-info</command> command as the registration of | | 1471 | <command>install-info</command> command as the registration of |
1472 | info files is the task of the package | | 1472 | info files is the task of the package |
1473 | <filename>INSTALL</filename> script, and it must use the | | 1473 | <filename>INSTALL</filename> script, and it must use the |
1474 | appropriate <command>makeinfo</command> command.</para> | | 1474 | appropriate <command>makeinfo</command> command.</para> |
1475 | | | 1475 | |
1476 | <para>To achieve this goal, the pkgsrc infrastructure creates | | 1476 | <para>To achieve this goal, the pkgsrc infrastructure creates |
1477 | overriding scripts for the <command>install-info</command> and | | 1477 | overriding scripts for the <command>install-info</command> and |
1478 | <command>makeinfo</command> commands in a directory listed early | | 1478 | <command>makeinfo</command> commands in a directory listed early |
1479 | in <varname>PATH</varname>.</para> | | 1479 | in <varname>PATH</varname>.</para> |
1480 | | | 1480 | |
1481 | <para>The script overriding <command>install-info</command> has | | 1481 | <para>The script overriding <command>install-info</command> has |
1482 | no effect except the logging of a message. The script overriding | | 1482 | no effect except the logging of a message. The script overriding |
1483 | <command>makeinfo</command> logs a message and according to the | | 1483 | <command>makeinfo</command> logs a message and according to the |
1484 | value of <varname>TEXINFO_REQD</varname> either runs the appropriate | | 1484 | value of <varname>TEXINFO_REQD</varname> either runs the appropriate |
1485 | <command>makeinfo</command> command or exit on error.</para> | | 1485 | <command>makeinfo</command> command or exit on error.</para> |
1486 | </sect2> | | 1486 | </sect2> |
1487 | | | 1487 | |
1488 | <sect2 id="manpages"> | | 1488 | <sect2 id="manpages"> |
1489 | <title>Packages installing man pages</title> | | 1489 | <title>Packages installing man pages</title> |
1490 | | | 1490 | |
1491 | <para>All packages that install manual pages should install them | | 1491 | <para>All packages that install manual pages should install them |
1492 | into the same directory, so that there is one common place to look | | 1492 | into the same directory, so that there is one common place to look |
1493 | for them. In pkgsrc, this place is | | 1493 | for them. In pkgsrc, this place is |
1494 | <literal>${PREFIX}/${PKGMANDIR}</literal>, and this expression | | 1494 | <literal>${PREFIX}/${PKGMANDIR}</literal>, and this expression |
1495 | should be used in packages. The default for | | 1495 | should be used in packages. The default for |
1496 | <varname>PKGMANDIR</varname> is | | 1496 | <varname>PKGMANDIR</varname> is |
1497 | <quote><filename>man</filename></quote>. Another often-used value | | 1497 | <quote><filename>man</filename></quote>. Another often-used value |
1498 | is <quote><filename>share/man</filename></quote>.</para> | | 1498 | is <quote><filename>share/man</filename></quote>.</para> |
1499 | | | 1499 | |
1500 | <note><para>The support for a custom <varname>PKGMANDIR</varname> | | 1500 | <note><para>The support for a custom <varname>PKGMANDIR</varname> |
1501 | is far from complete.</para></note> | | 1501 | is far from complete.</para></note> |
1502 | | | 1502 | |
1503 | <para>The <filename>PLIST</filename> files can just use | | 1503 | <para>The <filename>PLIST</filename> files can just use |
1504 | <filename>man/</filename> as the top level directory for the man | | 1504 | <filename>man/</filename> as the top level directory for the man |
1505 | page file entries, and the pkgsrc framework will convert as | | 1505 | page file entries, and the pkgsrc framework will convert as |
1506 | needed. In all other places, the correct | | 1506 | needed. In all other places, the correct |
1507 | <varname>PKGMANDIR</varname> must be used.</para> | | 1507 | <varname>PKGMANDIR</varname> must be used.</para> |
1508 | | | 1508 | |
1509 | <para>Packages that are | | 1509 | <para>Packages that are |
1510 | configured with <varname>GNU_CONFIGURE</varname> set as | | 1510 | configured with <varname>GNU_CONFIGURE</varname> set as |
1511 | <quote>yes</quote>, by default will use the | | 1511 | <quote>yes</quote>, by default will use the |
1512 | <filename>./configure</filename> | | 1512 | <filename>./configure</filename> |
1513 | --mandir switch to set where the man pages should be installed. | | 1513 | --mandir switch to set where the man pages should be installed. |
1514 | The path is <varname>GNU_CONFIGURE_MANDIR</varname> which defaults | | 1514 | The path is <varname>GNU_CONFIGURE_MANDIR</varname> which defaults |
1515 | to <varname>${PREFIX}/${PKGMANDIR}</varname>.</para> | | 1515 | to <varname>${PREFIX}/${PKGMANDIR}</varname>.</para> |
1516 | | | 1516 | |
1517 | <para>Packages that use <varname>GNU_CONFIGURE</varname> but do not | | 1517 | <para>Packages that use <varname>GNU_CONFIGURE</varname> but do not |
1518 | use --mandir, can set <varname>CONFIGURE_HAS_MANDIR</varname> | | 1518 | use --mandir, can set <varname>CONFIGURE_HAS_MANDIR</varname> |
1519 | to <quote>no</quote>. | | 1519 | to <quote>no</quote>. |
1520 | Or if the <filename>./configure</filename> script uses | | 1520 | Or if the <filename>./configure</filename> script uses |
1521 | a non-standard use of --mandir, you can set | | 1521 | a non-standard use of --mandir, you can set |
1522 | <varname>GNU_CONFIGURE_MANDIR</varname> as needed.</para> | | 1522 | <varname>GNU_CONFIGURE_MANDIR</varname> as needed.</para> |
1523 | | | 1523 | |
1524 | <para>See <xref linkend="manpage-compression"/> for | | 1524 | <para>See <xref linkend="manpage-compression"/> for |
1525 | information on installation of compressed manual pages.</para> | | 1525 | information on installation of compressed manual pages.</para> |
1526 | | | 1526 | |
1527 | </sect2> | | 1527 | </sect2> |
1528 | | | 1528 | |
1529 | <sect2 id="gconf-data-files"> | | 1529 | <sect2 id="gconf-data-files"> |
1530 | <title>Packages installing GConf data files</title> | | 1530 | <title>Packages installing GConf data files</title> |
1531 | | | 1531 | |
1532 | <para>If a package installs <filename>.schemas</filename> or | | 1532 | <para>If a package installs <filename>.schemas</filename> or |
1533 | <filename>.entries</filename> files, used by GConf, | | 1533 | <filename>.entries</filename> files, used by GConf, |
1534 | you need to take some extra steps to make sure they get registered | | 1534 | you need to take some extra steps to make sure they get registered |
1535 | in the database:</para> | | 1535 | in the database:</para> |
1536 | | | 1536 | |
1537 | <orderedlist> | | 1537 | <orderedlist> |
1538 | <listitem> | | 1538 | <listitem> |
1539 | <para>Include <filename>../../devel/GConf/schemas.mk</filename> | | 1539 | <para>Include <filename>../../devel/GConf/schemas.mk</filename> |
1540 | instead of its <filename>buildlink3.mk</filename> file. This | | 1540 | instead of its <filename>buildlink3.mk</filename> file. This |
1541 | takes care of rebuilding the GConf database at installation and | | 1541 | takes care of rebuilding the GConf database at installation and |
1542 | deinstallation time, and tells the package where to install | | 1542 | deinstallation time, and tells the package where to install |
1543 | GConf data files using some standard configure arguments. It | | 1543 | GConf data files using some standard configure arguments. It |
1544 | also disallows any access to the database directly from the | | 1544 | also disallows any access to the database directly from the |
1545 | package.</para> | | 1545 | package.</para> |
1546 | </listitem> | | 1546 | </listitem> |
1547 | | | 1547 | |
1548 | <listitem> | | 1548 | <listitem> |
1549 | <para>Ensure that the package installs its | | 1549 | <para>Ensure that the package installs its |
1550 | <filename>.schemas</filename> files under | | 1550 | <filename>.schemas</filename> files under |
1551 | <filename>${PREFIX}/share/gconf/schemas</filename>. If they get | | 1551 | <filename>${PREFIX}/share/gconf/schemas</filename>. If they get |
1552 | installed under <filename>${PREFIX}/etc</filename>, you will | | 1552 | installed under <filename>${PREFIX}/etc</filename>, you will |
1553 | need to manually patch the package.</para> | | 1553 | need to manually patch the package.</para> |
1554 | </listitem> | | 1554 | </listitem> |
1555 | | | 1555 | |
1556 | <listitem> | | 1556 | <listitem> |
1557 | <para>Check the PLIST and remove any entries under the etc/gconf | | 1557 | <para>Check the PLIST and remove any entries under the etc/gconf |
1558 | directory, as they will be handled automatically. See | | 1558 | directory, as they will be handled automatically. See |
1559 | <xref linkend="faq.conf"/> for more information.</para> | | 1559 | <xref linkend="faq.conf"/> for more information.</para> |
1560 | </listitem> | | 1560 | </listitem> |
1561 | | | 1561 | |
1562 | <listitem> | | 1562 | <listitem> |
1563 | <para>Define the <varname>GCONF_SCHEMAS</varname> variable in | | 1563 | <para>Define the <varname>GCONF_SCHEMAS</varname> variable in |
1564 | your <filename>Makefile</filename> with a list of all | | 1564 | your <filename>Makefile</filename> with a list of all |
1565 | <filename>.schemas</filename> files installed by the package, if | | 1565 | <filename>.schemas</filename> files installed by the package, if |
1566 | any. Names must not contain any directories in them.</para> | | 1566 | any. Names must not contain any directories in them.</para> |
1567 | </listitem> | | 1567 | </listitem> |
1568 | | | 1568 | |
1569 | <listitem> | | 1569 | <listitem> |
1570 | <para>Define the <varname>GCONF_ENTRIES</varname> variable in | | 1570 | <para>Define the <varname>GCONF_ENTRIES</varname> variable in |
1571 | your <filename>Makefile</filename> with a | | 1571 | your <filename>Makefile</filename> with a |
1572 | list of all <filename>.entries</filename> files installed by the | | 1572 | list of all <filename>.entries</filename> files installed by the |
1573 | package, if any. Names must not contain any directories in | | 1573 | package, if any. Names must not contain any directories in |
1574 | them.</para> | | 1574 | them.</para> |
1575 | </listitem> | | 1575 | </listitem> |
1576 | </orderedlist> | | 1576 | </orderedlist> |
1577 | </sect2> | | 1577 | </sect2> |
1578 | | | 1578 | |
1579 | | | 1579 | |
1580 | <sect2 id="scrollkeeper-data-files"> | | 1580 | <sect2 id="scrollkeeper-data-files"> |
1581 | <title>Packages installing scrollkeeper data files</title> | | 1581 | <title>Packages installing scrollkeeper/rarian data files</title> |
1582 | | | 1582 | |
1583 | <para>If a package installs <filename>.omf</filename> files, used by | | 1583 | <para>If a package installs <filename>.omf</filename> files, used by |
1584 | scrollkeeper, you need to take some extra steps to make sure they | | 1584 | scrollkeeper/rarian, you need to take some extra steps to make sure they |
1585 | get registered in the database:</para> | | 1585 | get registered in the database:</para> |
1586 | | | 1586 | |
1587 | <orderedlist> | | 1587 | <orderedlist> |
1588 | <listitem> | | 1588 | <listitem> |
1589 | <para>Include | | 1589 | <para>Include |
1590 | <filename>../../textproc/rarian/omf.mk</filename> | | 1590 | <filename>../../mk/omf-scrollkeeper.mk</filename> |
1591 | instead of its <filename>buildlink3.mk</filename> file. This | | 1591 | instead of rarian's <filename>buildlink3.mk</filename> file. This |
1592 | takes care of rebuilding the scrollkeeper database at | | 1592 | takes care of rebuilding the scrollkeeper database at |
1593 | installation and deinstallation time, and disallows any access | | 1593 | installation and deinstallation time, and disallows any access |
1594 | to it directly from the package.</para> | | 1594 | to it directly from the package.</para> |
1595 | </listitem> | | 1595 | </listitem> |
1596 | | | 1596 | |
1597 | <listitem> | | 1597 | <listitem> |
1598 | <para>Check the PLIST and remove any entries under the | | 1598 | <para>Check the PLIST and remove any entries under the |
1599 | <filename>libdata/scrollkeeper</filename> directory, as they | | 1599 | <filename>libdata/scrollkeeper</filename> directory, as they |
1600 | will be handled automatically.</para> | | 1600 | will be handled automatically.</para> |
1601 | </listitem> | | 1601 | </listitem> |
1602 | | | 1602 | |
1603 | <listitem> | | 1603 | <listitem> |
1604 | <para>Remove the <filename>share/omf</filename> directory from | | 1604 | <para>Remove the <filename>share/omf</filename> directory from |
1605 | the PLIST. It will be handled by scrollkeeper.</para> | | 1605 | the PLIST. It will be handled by rarian. (<command>make |
| | | 1606 | print-PLIST</command> does this automatically.)</para> |
1606 | </listitem> | | 1607 | </listitem> |
1607 | </orderedlist> | | 1608 | </orderedlist> |
1608 | </sect2> | | 1609 | </sect2> |
1609 | | | 1610 | |
1610 | | | 1611 | |
1611 | <sect2 id="x11-fonts"> | | 1612 | <sect2 id="x11-fonts"> |
1612 | <title>Packages installing X11 fonts</title> | | 1613 | <title>Packages installing X11 fonts</title> |
1613 | | | 1614 | |
1614 | <para>If a package installs font files, you will need to rebuild | | 1615 | <para>If a package installs font files, you will need to rebuild |
1615 | the fonts database in the directory where they get installed at | | 1616 | the fonts database in the directory where they get installed at |
1616 | installation and deinstallation time. This can be automatically | | 1617 | installation and deinstallation time. This can be automatically |
1617 | done by using the pkginstall framework.</para> | | 1618 | done by using the pkginstall framework.</para> |
1618 | | | 1619 | |
1619 | <para>You can list the directories where fonts are installed in the | | 1620 | <para>You can list the directories where fonts are installed in the |
1620 | <varname>FONTS_DIRS.<replaceable>type</replaceable></varname> | | 1621 | <varname>FONTS_DIRS.<replaceable>type</replaceable></varname> |
1621 | variables, where <replaceable>type</replaceable> can be one of | | 1622 | variables, where <replaceable>type</replaceable> can be one of |
1622 | <quote>ttf</quote>, <quote>type1</quote> or <quote>x11</quote>. | | 1623 | <quote>ttf</quote>, <quote>type1</quote> or <quote>x11</quote>. |
1623 | Also make sure that the database file | | 1624 | Also make sure that the database file |
1624 | <filename>fonts.dir</filename> is not listed in the PLIST.</para> | | 1625 | <filename>fonts.dir</filename> is not listed in the PLIST.</para> |
1625 | | | 1626 | |
1626 | <para>Note that you should not create new directories for fonts; | | 1627 | <para>Note that you should not create new directories for fonts; |
1627 | instead use the standard ones to avoid that the user needs to | | 1628 | instead use the standard ones to avoid that the user needs to |
1628 | manually configure his X server to find them.</para> | | 1629 | manually configure his X server to find them.</para> |
1629 | </sect2> | | 1630 | </sect2> |
1630 | | | 1631 | |
1631 | | | 1632 | |
1632 | <sect2 id="gtk2-modules"> | | 1633 | <sect2 id="gtk2-modules"> |
1633 | <title>Packages installing GTK2 modules</title> | | 1634 | <title>Packages installing GTK2 modules</title> |
1634 | | | 1635 | |
1635 | <para>If a package installs GTK2 immodules or loaders, you need to | | 1636 | <para>If a package installs GTK2 immodules or loaders, you need to |
1636 | take some extra steps to get them registered in the GTK2 database | | 1637 | take some extra steps to get them registered in the GTK2 database |
1637 | properly:</para> | | 1638 | properly:</para> |
1638 | | | 1639 | |
1639 | <orderedlist> | | 1640 | <orderedlist> |
1640 | <listitem><para>Include | | 1641 | <listitem><para>Include |
1641 | <filename>../../x11/gtk2/modules.mk</filename> instead of its | | 1642 | <filename>../../x11/gtk2/modules.mk</filename> instead of its |
1642 | <filename>buildlink3.mk</filename> file. This takes care of | | 1643 | <filename>buildlink3.mk</filename> file. This takes care of |
1643 | rebuilding the database at installation and deinstallation time.</para> | | 1644 | rebuilding the database at installation and deinstallation time.</para> |
1644 | </listitem> | | 1645 | </listitem> |
1645 | | | 1646 | |
1646 | <listitem><para>Set <varname>GTK2_IMMODULES=YES</varname> if | | 1647 | <listitem><para>Set <varname>GTK2_IMMODULES=YES</varname> if |
1647 | your package installs GTK2 immodules.</para> | | 1648 | your package installs GTK2 immodules.</para> |
1648 | </listitem> | | 1649 | </listitem> |
1649 | | | 1650 | |
1650 | <listitem><para>Set <varname>GTK2_LOADERS=YES</varname> if your package installs | | 1651 | <listitem><para>Set <varname>GTK2_LOADERS=YES</varname> if your package installs |
1651 | GTK2 loaders.</para> | | 1652 | GTK2 loaders.</para> |
1652 | </listitem> | | 1653 | </listitem> |
1653 | | | 1654 | |
1654 | <listitem><para>Patch the package to not touch any of the GTK2 | | 1655 | <listitem><para>Patch the package to not touch any of the GTK2 |
1655 | databases directly. These are:</para> | | 1656 | databases directly. These are:</para> |
1656 | | | 1657 | |
1657 | <itemizedlist> | | 1658 | <itemizedlist> |
1658 | <listitem><para><filename>libdata/gtk-2.0/gdk-pixbuf.loaders</filename></para></listitem> | | 1659 | <listitem><para><filename>libdata/gtk-2.0/gdk-pixbuf.loaders</filename></para></listitem> |
1659 | <listitem><para><filename>libdata/gtk-2.0/gtk.immodules</filename></para></listitem> | | 1660 | <listitem><para><filename>libdata/gtk-2.0/gtk.immodules</filename></para></listitem> |
1660 | </itemizedlist> | | 1661 | </itemizedlist> |
1661 | | | 1662 | |
1662 | </listitem> | | 1663 | </listitem> |
1663 | | | 1664 | |
1664 | <listitem><para>Check the <filename>PLIST</filename> and remove | | 1665 | <listitem><para>Check the <filename>PLIST</filename> and remove |
1665 | any entries under the <filename>libdata/gtk-2.0</filename> | | 1666 | any entries under the <filename>libdata/gtk-2.0</filename> |
1666 | directory, as they will be handled automatically.</para> | | 1667 | directory, as they will be handled automatically.</para> |
1667 | </listitem> | | 1668 | </listitem> |
1668 | </orderedlist> | | 1669 | </orderedlist> |
1669 | </sect2> | | 1670 | </sect2> |
1670 | | | 1671 | |
1671 | | | 1672 | |
1672 | <sect2 id="sgml-xml-data"> | | 1673 | <sect2 id="sgml-xml-data"> |
1673 | <title>Packages installing SGML or XML data</title> | | 1674 | <title>Packages installing SGML or XML data</title> |
1674 | | | 1675 | |
1675 | <para>If a package installs SGML or XML data files that need to be | | 1676 | <para>If a package installs SGML or XML data files that need to be |
1676 | registered in system-wide catalogs (like DTDs, sub-catalogs, | | 1677 | registered in system-wide catalogs (like DTDs, sub-catalogs, |
1677 | etc.), you need to take some extra steps:</para> | | 1678 | etc.), you need to take some extra steps:</para> |
1678 | | | 1679 | |
1679 | <orderedlist> | | 1680 | <orderedlist> |
1680 | <listitem> | | 1681 | <listitem> |
1681 | <para>Include | | 1682 | <para>Include |
1682 | <filename>../../textproc/xmlcatmgr/catalogs.mk</filename> in | | 1683 | <filename>../../textproc/xmlcatmgr/catalogs.mk</filename> in |
1683 | your <filename>Makefile</filename>, which takes care of | | 1684 | your <filename>Makefile</filename>, which takes care of |
1684 | registering those files in system-wide catalogs at | | 1685 | registering those files in system-wide catalogs at |
1685 | installation and deinstallation time.</para> | | 1686 | installation and deinstallation time.</para> |
1686 | </listitem> | | 1687 | </listitem> |
1687 | | | 1688 | |
1688 | <listitem> | | 1689 | <listitem> |
1689 | <para>Set <varname>SGML_CATALOGS</varname> to the full path of | | 1690 | <para>Set <varname>SGML_CATALOGS</varname> to the full path of |
1690 | any SGML catalogs installed by the package.</para> | | 1691 | any SGML catalogs installed by the package.</para> |
1691 | </listitem> | | 1692 | </listitem> |
1692 | | | 1693 | |
1693 | <listitem> | | 1694 | <listitem> |
1694 | <para>Set <varname>XML_CATALOGS</varname> to the full path of | | 1695 | <para>Set <varname>XML_CATALOGS</varname> to the full path of |
1695 | any XML catalogs installed by the package.</para> | | 1696 | any XML catalogs installed by the package.</para> |
1696 | </listitem> | | 1697 | </listitem> |
1697 | | | 1698 | |
1698 | <listitem> | | 1699 | <listitem> |
1699 | <para>Set <varname>SGML_ENTRIES</varname> to individual entries | | 1700 | <para>Set <varname>SGML_ENTRIES</varname> to individual entries |
1700 | to be added to the SGML catalog. These come in groups of | | 1701 | to be added to the SGML catalog. These come in groups of |
1701 | three strings; see xmlcatmgr(1) for more information | | 1702 | three strings; see xmlcatmgr(1) for more information |
1702 | (specifically, arguments recognized by the 'add' action). | | 1703 | (specifically, arguments recognized by the 'add' action). |
1703 | Note that you will normally not use this variable.</para> | | 1704 | Note that you will normally not use this variable.</para> |
1704 | </listitem> | | 1705 | </listitem> |
1705 | | | 1706 | |
1706 | <listitem> | | 1707 | <listitem> |
1707 | <para>Set <varname>XML_ENTRIES</varname> to individual entries | | 1708 | <para>Set <varname>XML_ENTRIES</varname> to individual entries |
1708 | to be added to the XML catalog. These come in groups of three | | 1709 | to be added to the XML catalog. These come in groups of three |
1709 | strings; see xmlcatmgr(1) for more information (specifically, | | 1710 | strings; see xmlcatmgr(1) for more information (specifically, |
1710 | arguments recognized by the 'add' action). Note that you will | | 1711 | arguments recognized by the 'add' action). Note that you will |
1711 | normally not use this variable.</para> | | 1712 | normally not use this variable.</para> |
1712 | </listitem> | | 1713 | </listitem> |
1713 | </orderedlist> | | 1714 | </orderedlist> |
1714 | </sect2> | | 1715 | </sect2> |
1715 | | | 1716 | |
1716 | | | 1717 | |
1717 | <sect2 id="mime-database"> | | 1718 | <sect2 id="mime-database"> |
1718 | <title>Packages installing extensions to the MIME database</title> | | 1719 | <title>Packages installing extensions to the MIME database</title> |
1719 | | | 1720 | |
1720 | <para>If a package provides extensions to the MIME database by | | 1721 | <para>If a package provides extensions to the MIME database by |
1721 | installing <filename>.xml</filename> files inside | | 1722 | installing <filename>.xml</filename> files inside |
1722 | <filename>${PREFIX}/share/mime/packages</filename>, you | | 1723 | <filename>${PREFIX}/share/mime/packages</filename>, you |
1723 | need to take some extra steps to ensure that the database is kept | | 1724 | need to take some extra steps to ensure that the database is kept |
1724 | consistent with respect to these new files:</para> | | 1725 | consistent with respect to these new files:</para> |
1725 | | | 1726 | |
1726 | <orderedlist> | | 1727 | <orderedlist> |
1727 | <listitem> | | 1728 | <listitem> |
1728 | <para>Include | | 1729 | <para>Include |
1729 | <filename>../../databases/shared-mime-info/mimedb.mk</filename> | | 1730 | <filename>../../databases/shared-mime-info/mimedb.mk</filename> |
1730 | (avoid using the <filename>buildlink3.mk</filename> file from | | 1731 | (avoid using the <filename>buildlink3.mk</filename> file from |
1731 | this same directory, which is reserved for inclusion from | | 1732 | this same directory, which is reserved for inclusion from |
1732 | other <filename>buildlink3.mk</filename> files). It takes | | 1733 | other <filename>buildlink3.mk</filename> files). It takes |
1733 | care of rebuilding the MIME database at installation and | | 1734 | care of rebuilding the MIME database at installation and |
1734 | deinstallation time, and disallows any access to it directly | | 1735 | deinstallation time, and disallows any access to it directly |
1735 | from the package.</para> | | 1736 | from the package.</para> |
1736 | </listitem> | | 1737 | </listitem> |
1737 | | | 1738 | |
1738 | <listitem> | | 1739 | <listitem> |
1739 | <para>Check the PLIST and remove any entries under the | | 1740 | <para>Check the PLIST and remove any entries under the |
1740 | <filename>share/mime</filename> directory, | | 1741 | <filename>share/mime</filename> directory, |
1741 | <emphasis>except</emphasis> for files saved under | | 1742 | <emphasis>except</emphasis> for files saved under |
1742 | <filename>share/mime/packages</filename>. The former are | | 1743 | <filename>share/mime/packages</filename>. The former are |
1743 | handled automatically by | | 1744 | handled automatically by |
1744 | the update-mime-database program, but the latter are | | 1745 | the update-mime-database program, but the latter are |
1745 | package-dependent and must be removed by the package that | | 1746 | package-dependent and must be removed by the package that |
1746 | installed them in the first place.</para> | | 1747 | installed them in the first place.</para> |
1747 | </listitem> | | 1748 | </listitem> |
1748 | | | 1749 | |
1749 | <listitem> | | 1750 | <listitem> |
1750 | <para>Remove any <filename>share/mime/*</filename> directories | | 1751 | <para>Remove any <filename>share/mime/*</filename> directories |
1751 | from the PLIST. They will be handled by the shared-mime-info | | 1752 | from the PLIST. They will be handled by the shared-mime-info |
1752 | package.</para> | | 1753 | package.</para> |
1753 | </listitem> | | 1754 | </listitem> |
1754 | </orderedlist> | | 1755 | </orderedlist> |
1755 | </sect2> | | 1756 | </sect2> |
1756 | | | 1757 | |
1757 | | | 1758 | |
1758 | <sect2 id="intltool"> | | 1759 | <sect2 id="intltool"> |
1759 | <title>Packages using intltool</title> | | 1760 | <title>Packages using intltool</title> |
1760 | | | 1761 | |
1761 | <para>If a package uses intltool during its build, add | | 1762 | <para>If a package uses intltool during its build, add |
1762 | <literal>intltool</literal> to the <varname>USE_TOOLS</varname>, | | 1763 | <literal>intltool</literal> to the <varname>USE_TOOLS</varname>, |
1763 | which forces it to use the intltool package provided by pkgsrc, | | 1764 | which forces it to use the intltool package provided by pkgsrc, |
1764 | instead of the one bundled with the distribution file.</para> | | 1765 | instead of the one bundled with the distribution file.</para> |
1765 | | | 1766 | |
1766 | <para>This tracks intltool's build-time dependencies and uses the | | 1767 | <para>This tracks intltool's build-time dependencies and uses the |
1767 | latest available version; this way, the package benefits of any | | 1768 | latest available version; this way, the package benefits of any |
1768 | bug fixes that may have appeared since it was released.</para> | | 1769 | bug fixes that may have appeared since it was released.</para> |
1769 | </sect2> | | 1770 | </sect2> |
1770 | | | 1771 | |
1771 | | | 1772 | |
1772 | <sect2 id="startup-scripts"> | | 1773 | <sect2 id="startup-scripts"> |
1773 | <title>Packages installing startup scripts</title> | | 1774 | <title>Packages installing startup scripts</title> |
1774 | <para>If a package contains a rc.d script, it won't be copied into | | 1775 | <para>If a package contains a rc.d script, it won't be copied into |
1775 | the startup directory by default, but you can enable it, by adding | | 1776 | the startup directory by default, but you can enable it, by adding |
1776 | the option <varname>PKG_RCD_SCRIPTS=YES</varname> in | | 1777 | the option <varname>PKG_RCD_SCRIPTS=YES</varname> in |
1777 | &mk.conf;. This option will copy the scripts | | 1778 | &mk.conf;. This option will copy the scripts |
1778 | into <filename>/etc/rc.d</filename> when a package is installed, and | | 1779 | into <filename>/etc/rc.d</filename> when a package is installed, and |
1779 | it will automatically remove the scripts when the package is | | 1780 | it will automatically remove the scripts when the package is |
1780 | deinstalled.</para> | | 1781 | deinstalled.</para> |
1781 | </sect2> | | 1782 | </sect2> |
1782 | | | 1783 | |
1783 | <sect2 id="tex-packages"> | | 1784 | <sect2 id="tex-packages"> |
1784 | <title>Packages installing TeX modules</title> | | 1785 | <title>Packages installing TeX modules</title> |
1785 | | | 1786 | |
1786 | <para>If a package installs TeX packages into the texmf tree, | | 1787 | <para>If a package installs TeX packages into the texmf tree, |
1787 | the <filename>ls-R</filename> database of the tree needs to be | | 1788 | the <filename>ls-R</filename> database of the tree needs to be |
1788 | updated.</para> | | 1789 | updated.</para> |
1789 | <note><para>Except the main TeX packages such as teTeX-texmf, | | 1790 | <note><para>Except the main TeX packages such as teTeX-texmf, |
1790 | packages should install files | | 1791 | packages should install files |
1791 | into <varname>PKG_LOCALTEXMFPREFIX</varname>, | | 1792 | into <varname>PKG_LOCALTEXMFPREFIX</varname>, |
1792 | not <varname>PKG_TEXMFPREFIX</varname>.</para></note> | | 1793 | not <varname>PKG_TEXMFPREFIX</varname>.</para></note> |
1793 | | | 1794 | |
1794 | <orderedlist> | | 1795 | <orderedlist> |
1795 | <listitem><para>Include | | 1796 | <listitem><para>Include |
1796 | <filename>../../print/teTeX/module.mk</filename> instead | | 1797 | <filename>../../print/teTeX/module.mk</filename> instead |
1797 | of <filename>../../mk/tex.buildlink3.mk</filename>. This | | 1798 | of <filename>../../mk/tex.buildlink3.mk</filename>. This |
1798 | takes care of rebuilding the <filename>ls-R</filename> | | 1799 | takes care of rebuilding the <filename>ls-R</filename> |
1799 | database at installation and deinstallation time.</para> | | 1800 | database at installation and deinstallation time.</para> |
1800 | </listitem> | | 1801 | </listitem> |
1801 | | | 1802 | |
1802 | <listitem><para>If your package installs files into a texmf | | 1803 | <listitem><para>If your package installs files into a texmf |
1803 | tree other than the one | | 1804 | tree other than the one |
1804 | at <varname>PKG_LOCALTEXMFPREFIX</varname>, | | 1805 | at <varname>PKG_LOCALTEXMFPREFIX</varname>, |
1805 | set <varname>TEXMFDIRS</varname> to the list of all texmf | | 1806 | set <varname>TEXMFDIRS</varname> to the list of all texmf |
1806 | trees that need database update.</para> | | 1807 | trees that need database update.</para> |
1807 | <para>If your package also installs font map files that need | | 1808 | <para>If your package also installs font map files that need |
1808 | to be registered using <command>updmap</command>, | | 1809 | to be registered using <command>updmap</command>, |
1809 | set <varname>TEX_FONTMAPS</varname> to the list of all | | 1810 | set <varname>TEX_FONTMAPS</varname> to the list of all |
1810 | such font map files. Then <command>updmap</command> will | | 1811 | such font map files. Then <command>updmap</command> will |
1811 | be run automatically at installation/deinstallation to | | 1812 | be run automatically at installation/deinstallation to |
1812 | enable/disable font map files for TeX output | | 1813 | enable/disable font map files for TeX output |
1813 | drivers.</para> | | 1814 | drivers.</para> |
1814 | </listitem> | | 1815 | </listitem> |
1815 | | | 1816 | |
1816 | <listitem><para>Make sure that none of <filename>ls-R</filename> | | 1817 | <listitem><para>Make sure that none of <filename>ls-R</filename> |
1817 | databases are included in <filename>PLIST</filename>, as | | 1818 | databases are included in <filename>PLIST</filename>, as |
1818 | they will be removed only by the teTeX-bin package.</para> | | 1819 | they will be removed only by the teTeX-bin package.</para> |
1819 | </listitem> | | 1820 | </listitem> |
1820 | </orderedlist> | | 1821 | </orderedlist> |
1821 | </sect2> | | 1822 | </sect2> |
1822 | | | 1823 | |
1823 | <sect2 id="emulation-packages"> | | 1824 | <sect2 id="emulation-packages"> |
1824 | <title>Packages supporting running binaries in | | 1825 | <title>Packages supporting running binaries in |
1825 | emulation</title> | | 1826 | emulation</title> |
1826 | | | 1827 | |
1827 | <para>There are some packages that provide libraries and | | 1828 | <para>There are some packages that provide libraries and |
1828 | executables for running binaries from a one operating system | | 1829 | executables for running binaries from a one operating system |
1829 | on a different one (if the latter supports it). One example | | 1830 | on a different one (if the latter supports it). One example |
1830 | is running Linux binaries on NetBSD.</para> | | 1831 | is running Linux binaries on NetBSD.</para> |
1831 | | | 1832 | |
1832 | <para>The <filename role="pkg">pkgtools/rpm2pkg</filename> | | 1833 | <para>The <filename role="pkg">pkgtools/rpm2pkg</filename> |
1833 | helps in extracting and packaging Linux rpm packages.</para> | | 1834 | helps in extracting and packaging Linux rpm packages.</para> |
1834 | | | 1835 | |
1835 | <para>The <varname>CHECK_SHLIBS</varname> can be set to no to | | 1836 | <para>The <varname>CHECK_SHLIBS</varname> can be set to no to |
1836 | avoid the <command>check-shlibs</command> target, which tests | | 1837 | avoid the <command>check-shlibs</command> target, which tests |
1837 | if all libraries for each installed executable can be found by | | 1838 | if all libraries for each installed executable can be found by |
1838 | the dynamic linker. Since the standard dynamic linker is run, | | 1839 | the dynamic linker. Since the standard dynamic linker is run, |
1839 | this fails for emulation packages, because the libraries used | | 1840 | this fails for emulation packages, because the libraries used |
1840 | by the emulation are not in the standard directories.</para> | | 1841 | by the emulation are not in the standard directories.</para> |
1841 | </sect2> | | 1842 | </sect2> |
1842 | | | 1843 | |
1843 | <sect2 id="hicolor-theme"> | | 1844 | <sect2 id="hicolor-theme"> |
1844 | <title>Packages installing hicolor theme icons</title> | | 1845 | <title>Packages installing hicolor theme icons</title> |
1845 | | | 1846 | |
1846 | <para>If a package installs images under the | | 1847 | <para>If a package installs images under the |
1847 | <filename>share/icons/hicolor</filename> and/or updates the | | 1848 | <filename>share/icons/hicolor</filename> and/or updates the |
1848 | <filename>share/icons/hicolor/icon-theme.cache</filename> | | 1849 | <filename>share/icons/hicolor/icon-theme.cache</filename> |
1849 | database, you need to take some extra steps to make sure that the | | 1850 | database, you need to take some extra steps to make sure that the |
1850 | shared theme directory is handled appropriately and that the cache | | 1851 | shared theme directory is handled appropriately and that the cache |
1851 | database is rebuilt:</para> | | 1852 | database is rebuilt:</para> |
1852 | | | 1853 | |
1853 | <orderedlist> | | 1854 | <orderedlist> |
1854 | <listitem> | | 1855 | <listitem> |
1855 | <para>Include | | 1856 | <para>Include |
1856 | <filename>../../graphics/hicolor-icon-theme/buildlink3.mk</filename>.</para> | | 1857 | <filename>../../graphics/hicolor-icon-theme/buildlink3.mk</filename>.</para> |
1857 | </listitem> | | 1858 | </listitem> |
1858 | | | 1859 | |
1859 | <listitem> | | 1860 | <listitem> |
1860 | <para>Check the <filename>PLIST</filename> and remove the | | 1861 | <para>Check the <filename>PLIST</filename> and remove the |
1861 | entry that refers to the theme cache.</para> | | 1862 | entry that refers to the theme cache.</para> |
1862 | </listitem> | | 1863 | </listitem> |
1863 | | | 1864 | |
1864 | <listitem> | | 1865 | <listitem> |
1865 | <para>Ensure that the PLIST does not remove the shared icon | | 1866 | <para>Ensure that the PLIST does not remove the shared icon |
1866 | directories from the <filename>share/icons/hicolor</filename> | | 1867 | directories from the <filename>share/icons/hicolor</filename> |
1867 | hierarchy because they will be handled automatically.</para> | | 1868 | hierarchy because they will be handled automatically.</para> |
1868 | </listitem> | | 1869 | </listitem> |
1869 | </orderedlist> | | 1870 | </orderedlist> |
1870 | | | 1871 | |
1871 | <para>The best way to verify that the PLIST is correct with | | 1872 | <para>The best way to verify that the PLIST is correct with |
1872 | respect to the last two points is to regenerate it using | | 1873 | respect to the last two points is to regenerate it using |
1873 | <command>make print-PLIST</command>.</para> | | 1874 | <command>make print-PLIST</command>.</para> |
1874 | </sect2> | | 1875 | </sect2> |
1875 | | | 1876 | |
1876 | | | 1877 | |
1877 | <sect2 id="desktop-files"> | | 1878 | <sect2 id="desktop-files"> |
1878 | <title>Packages installing desktop files</title> | | 1879 | <title>Packages installing desktop files</title> |
1879 | | | 1880 | |
1880 | <para>If a package installs <filename>.desktop</filename> files | | 1881 | <para>If a package installs <filename>.desktop</filename> files |
1881 | under <filename>share/applications</filename> and these include | | 1882 | under <filename>share/applications</filename> and these include |
1882 | MIME information, you need to take extra steps to ensure that they | | 1883 | MIME information, you need to take extra steps to ensure that they |
1883 | are registered into the MIME database:</para> | | 1884 | are registered into the MIME database:</para> |
1884 | | | 1885 | |
1885 | <orderedlist> | | 1886 | <orderedlist> |
1886 | <listitem> | | 1887 | <listitem> |
1887 | <para>Include | | 1888 | <para>Include |
1888 | <filename>../../sysutils/desktop-file-utils/desktopdb.mk</filename>.</para> | | 1889 | <filename>../../sysutils/desktop-file-utils/desktopdb.mk</filename>.</para> |
1889 | </listitem> | | 1890 | </listitem> |
1890 | | | 1891 | |
1891 | <listitem> | | 1892 | <listitem> |
1892 | <para>Check the PLIST and remove the entry that refers to the | | 1893 | <para>Check the PLIST and remove the entry that refers to the |
1893 | <filename>share/applications/mimeinfo.cache</filename> file. | | 1894 | <filename>share/applications/mimeinfo.cache</filename> file. |
1894 | It will be handled automatically.</para> | | 1895 | It will be handled automatically.</para> |
1895 | </listitem> | | 1896 | </listitem> |
1896 | </orderedlist> | | 1897 | </orderedlist> |
1897 | | | 1898 | |
1898 | <para>The best way to verify that the PLIST is correct with | | 1899 | <para>The best way to verify that the PLIST is correct with |
1899 | respect to the last point is to regenerate it using <command>make | | 1900 | respect to the last point is to regenerate it using <command>make |
1900 | print-PLIST</command>.</para> | | 1901 | print-PLIST</command>.</para> |
1901 | </sect2> | | 1902 | </sect2> |
1902 | </sect1> | | 1903 | </sect1> |
1903 | | | 1904 | |
1904 | <sect1 id="punting"> | | 1905 | <sect1 id="punting"> |
1905 | <title>Marking packages as having problems</title> | | 1906 | <title>Marking packages as having problems</title> |
1906 | | | 1907 | |
1907 | <para>In some cases one does not have the time to solve a problem | | 1908 | <para>In some cases one does not have the time to solve a problem |
1908 | immediately. There are currently two ways to declare that one knows | | 1909 | immediately. There are currently two ways to declare that one knows |
1909 | that a package has problems.</para> | | 1910 | that a package has problems.</para> |
1910 | <itemizedlist> | | 1911 | <itemizedlist> |
1911 | <listitem><para>The first way is to plainly mark it as broken. For | | 1912 | <listitem><para>The first way is to plainly mark it as broken. For |
1912 | this, one just sets the variable <varname>BROKEN</varname> to the | | 1913 | this, one just sets the variable <varname>BROKEN</varname> to the |
1913 | reason why the package is broken (similar to the | | 1914 | reason why the package is broken (similar to the |
1914 | <varname>RESTRICTED</varname> variable). A user trying to build | | 1915 | <varname>RESTRICTED</varname> variable). A user trying to build |
1915 | the package will immediately be shown this message, and the build | | 1916 | the package will immediately be shown this message, and the build |
1916 | will not be even tried.</para></listitem> | | 1917 | will not be even tried.</para></listitem> |
1917 | | | 1918 | |
1918 | <listitem><para>After each pkgsrc freeze period (a time when the | | 1919 | <listitem><para>After each pkgsrc freeze period (a time when the |
1919 | tree is stabilized and a new pkgsrc branch is cut), the packages | | 1920 | tree is stabilized and a new pkgsrc branch is cut), the packages |
1920 | that were not building in the official branch build on the latest | | 1921 | that were not building in the official branch build on the latest |
1921 | NetBSD release will be marked as broken on that branch. This is | | 1922 | NetBSD release will be marked as broken on that branch. This is |
1922 | done by setting the <varname>BROKEN_IN</varname> variable to the | | 1923 | done by setting the <varname>BROKEN_IN</varname> variable to the |
1923 | branch name (or appending the branch name to it). If a user tries | | 1924 | branch name (or appending the branch name to it). If a user tries |
1924 | to build such a package and the build fails, the user gets a | | 1925 | to build such a package and the build fails, the user gets a |
1925 | message that says that the package was broken on the respective | | 1926 | message that says that the package was broken on the respective |
1926 | branch(es).</para></listitem> | | 1927 | branch(es).</para></listitem> |
1927 | </itemizedlist> | | 1928 | </itemizedlist> |
1928 | <para>Both types of packages are removed from pkgsrc in irregular | | 1929 | <para>Both types of packages are removed from pkgsrc in irregular |
1929 | intervals.</para> | | 1930 | intervals.</para> |
1930 | </sect1> | | 1931 | </sect1> |
1931 | | | 1932 | |
1932 | </chapter> | | 1933 | </chapter> |