| @@ -1,2460 +1,2461 @@ | | | @@ -1,2460 +1,2461 @@ |
1 | <!-- $NetBSD: fixes.xml,v 1.187 2023/07/21 08:29:56 nia Exp $ --> | | 1 | <!-- $NetBSD: fixes.xml,v 1.188 2023/07/22 12:20:37 nia 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 | <para>One appealing feature of pkgsrc is that it runs on many | | 9 | <para>One appealing feature of pkgsrc is that it runs on many |
10 | different platforms. As a result, it is important to ensure, | | 10 | different platforms. As a result, it is important to ensure, |
11 | where possible, that packages in pkgsrc are portable. This | | 11 | where possible, that packages in pkgsrc are portable. This |
12 | chapter mentions some particular details you should pay | | 12 | chapter mentions some particular details you should pay |
13 | attention to while working on pkgsrc.</para> | | 13 | attention to while working on pkgsrc.</para> |
14 | | | 14 | |
15 | <sect2 id="pulling-vars-from-etc-mk.conf"> | | 15 | <sect2 id="pulling-vars-from-etc-mk.conf"> |
16 | <title>How to pull in user-settable variables from &mk.conf;</title> | | 16 | <title>How to pull in user-settable variables from &mk.conf;</title> |
17 | | | 17 | |
18 | <para>The pkgsrc user can configure pkgsrc by overriding several | | 18 | <para>The pkgsrc user can configure pkgsrc by overriding several |
19 | variables in the file pointed to by <varname>MAKECONF</varname>, | | 19 | variables in the file pointed to by <varname>MAKECONF</varname>, |
20 | which is &mk.conf; by default. When you | | 20 | which is &mk.conf; by default. When you |
21 | want to use those variables in the preprocessor directives of | | 21 | want to use those variables in the preprocessor directives of |
22 | &man.make.1; (for example <literal>.if</literal> or | | 22 | &man.make.1; (for example <literal>.if</literal> or |
23 | <literal>.for</literal>), you need to include the file | | 23 | <literal>.for</literal>), you need to include the file |
24 | <filename>../../mk/bsd.prefs.mk</filename> before, which in turn | | 24 | <filename>../../mk/bsd.prefs.mk</filename> before, which in turn |
25 | loads the user preferences.</para> | | 25 | loads the user preferences.</para> |
26 | | | 26 | |
27 | <para>But note that some variables may not be completely defined | | 27 | <para>But note that some variables may not be completely defined |
28 | after <filename>../../mk/bsd.prefs.mk</filename> has been | | 28 | after <filename>../../mk/bsd.prefs.mk</filename> has been |
29 | included, as they may contain references to variables that are | | 29 | included, as they may contain references to variables that are |
30 | not yet defined. In shell commands (the lines in | | 30 | not yet defined. In shell commands (the lines in |
31 | <filename>Makefile</filename> that are indented with a tab) this | | 31 | <filename>Makefile</filename> that are indented with a tab) this |
32 | is no problem, since variables are only expanded when they are | | 32 | is no problem, since variables are only expanded when they are |
33 | used. But in the preprocessor directives mentioned above and in | | 33 | used. But in the preprocessor directives mentioned above and in |
34 | dependency lines (of the form <literal>target: | | 34 | dependency lines (of the form <literal>target: |
35 | dependencies</literal>) the variables are expanded at load | | 35 | dependencies</literal>) the variables are expanded at load |
36 | time.</para> | | 36 | time.</para> |
37 | | | 37 | |
38 | <note><para>To check whether a variable can be used at load time, | | 38 | <note><para>To check whether a variable can be used at load time, |
39 | run <command>pkglint -Wall</command> on your package.</para></note> | | 39 | run <command>pkglint -Wall</command> on your package.</para></note> |
40 | | | 40 | |
41 | </sect2> | | 41 | </sect2> |
42 | | | 42 | |
43 | <sect2 id="user-interaction"> | | 43 | <sect2 id="user-interaction"> |
44 | <title>User interaction</title> | | 44 | <title>User interaction</title> |
45 | | | 45 | |
46 | <para>Occasionally, packages require interaction from the user, | | 46 | <para>Occasionally, packages require interaction from the user, |
47 | and this can be in a number of ways:</para> | | 47 | and this can be in a number of ways:</para> |
48 | | | 48 | |
49 | <itemizedlist> | | 49 | <itemizedlist> |
50 | | | 50 | |
51 | <listitem> | | 51 | <listitem> |
52 | <para>When fetching the distfiles, some packages require user | | 52 | <para>When fetching the distfiles, some packages require user |
53 | interaction such as entering username/password or accepting a | | 53 | interaction such as entering username/password or accepting a |
54 | license on a web page.</para> | | 54 | license on a web page.</para> |
55 | </listitem> | | 55 | </listitem> |
56 | | | 56 | |
57 | <listitem> | | 57 | <listitem> |
58 | <para>When extracting the distfiles, some packages may ask for | | 58 | <para>When extracting the distfiles, some packages may ask for |
59 | passwords.</para> | | 59 | passwords.</para> |
60 | </listitem> | | 60 | </listitem> |
61 | | | 61 | |
62 | <listitem> | | 62 | <listitem> |
63 | <para>help to configure the package before it is built</para> | | 63 | <para>help to configure the package before it is built</para> |
64 | </listitem> | | 64 | </listitem> |
65 | | | 65 | |
66 | <listitem> | | 66 | <listitem> |
67 | <para>help during the build process</para> | | 67 | <para>help during the build process</para> |
68 | </listitem> | | 68 | </listitem> |
69 | | | 69 | |
70 | <listitem> | | 70 | <listitem> |
71 | <para>help during the installation of a package</para> | | 71 | <para>help during the installation of a package</para> |
72 | </listitem> | | 72 | </listitem> |
73 | </itemizedlist> | | 73 | </itemizedlist> |
74 | | | 74 | |
75 | <para>A package can set the <varname>INTERACTIVE_STAGE</varname> | | 75 | <para>A package can set the <varname>INTERACTIVE_STAGE</varname> |
76 | variable to define which stages need interaction. This should be | | 76 | variable to define which stages need interaction. This should be |
77 | done in the package's <filename>Makefile</filename>, e.g.:</para> | | 77 | done in the package's <filename>Makefile</filename>, e.g.:</para> |
78 | | | 78 | |
79 | <programlisting> | | 79 | <programlisting> |
80 | INTERACTIVE_STAGE= configure install | | 80 | INTERACTIVE_STAGE= configure install |
81 | </programlisting> | | 81 | </programlisting> |
82 | | | 82 | |
83 | <para>The user can then decide to skip this package by setting the | | 83 | <para>The user can then decide to skip this package by setting the |
84 | <varname>BATCH</varname> variable. Packages that require interaction | | 84 | <varname>BATCH</varname> variable. Packages that require interaction |
85 | are also excluded from bulk builds.</para> | | 85 | are also excluded from bulk builds.</para> |
86 | </sect2> | | 86 | </sect2> |
87 | | | 87 | |
88 | <sect2 id="handling-licenses"> | | 88 | <sect2 id="handling-licenses"> |
89 | <title>Handling licenses</title> | | 89 | <title>Handling licenses</title> |
90 | | | 90 | |
91 | <para>Authors of software can choose the licence under which software | | 91 | <para>Authors of software can choose the licence under which software |
92 | can be copied. The Free Software Foundation has declared some | | 92 | can be copied. The Free Software Foundation has declared some |
93 | licenses "Free", and the Open Source Initiative has a definition of | | 93 | licenses "Free", and the Open Source Initiative has a definition of |
94 | "Open Source".</para> | | 94 | "Open Source".</para> |
95 | | | 95 | |
96 | <para>By default, pkgsrc allows packages with Free or Open Source | | 96 | <para>By default, pkgsrc allows packages with Free or Open Source |
97 | licenses to be built. To allow packages with other licenses to be | | 97 | licenses to be built. To allow packages with other licenses to be |
98 | built as well, the pkgsrc user needs to add these licenses to the | | 98 | built as well, the pkgsrc user needs to add these licenses to the |
99 | <varname>ACCEPTABLE_LICENSES</varname> variable in &mk.conf;. Note | | 99 | <varname>ACCEPTABLE_LICENSES</varname> variable in &mk.conf;. Note |
100 | that this variable only affects which packages may be | | 100 | that this variable only affects which packages may be |
101 | <emphasis>built</emphasis>, while the license terms often also | | 101 | <emphasis>built</emphasis>, while the license terms often also |
102 | restrict the actual use of the package and its redistribution.</para> | | 102 | restrict the actual use of the package and its redistribution.</para> |
103 | | | 103 | |
104 | <para>One might want to only install packages with a BSD license, | | 104 | <para>One might want to only install packages with a BSD license, |
105 | or the GPL, and not the other. The free licenses are added to the | | 105 | or the GPL, and not the other. The free licenses are added to the |
106 | default <varname>ACCEPTABLE_LICENSES</varname> variable. The pkgsrc | | 106 | default <varname>ACCEPTABLE_LICENSES</varname> variable. The pkgsrc |
107 | user can override the default by setting the | | 107 | user can override the default by setting the |
108 | <varname>ACCEPTABLE_LICENSES</varname> variable with "=" instead | | 108 | <varname>ACCEPTABLE_LICENSES</varname> variable with "=" instead |
109 | of "+=". The licenses accepted by default are defined in the | | 109 | of "+=". The licenses accepted by default are defined in the |
110 | <varname>DEFAULT_ACCEPTABLE_LICENSES</varname> variable in the file | | 110 | <varname>DEFAULT_ACCEPTABLE_LICENSES</varname> variable in the file |
111 | <filename>pkgsrc/mk/license.mk</filename>.</para> | | 111 | <filename>pkgsrc/mk/license.mk</filename>.</para> |
112 | | | 112 | |
113 | <para>The license tag mechanism is intended to address | | 113 | <para>The license tag mechanism is intended to address |
114 | copyright-related issues surrounding building, installing and | | 114 | copyright-related issues surrounding building, installing and |
115 | using a package, and not to address redistribution issues (see | | 115 | using a package, and not to address redistribution issues (see |
116 | <varname>RESTRICTED</varname> and | | 116 | <varname>RESTRICTED</varname> and |
117 | <varname>NO_SRC_ON_FTP</varname>, etc.). | | 117 | <varname>NO_SRC_ON_FTP</varname>, etc.). |
118 | Packages with redistribution restrictions should set these | | 118 | Packages with redistribution restrictions should set these |
119 | tags.</para> | | 119 | tags.</para> |
120 | | | 120 | |
121 | <para>Denoting that a package may be copied according to a | | 121 | <para>Denoting that a package may be copied according to a |
122 | particular license is done by placing the license in | | 122 | particular license is done by placing the license in |
123 | <filename>pkgsrc/licenses</filename> and setting the | | 123 | <filename>pkgsrc/licenses</filename> and setting the |
124 | <varname>LICENSE</varname> variable to a string identifying the | | 124 | <varname>LICENSE</varname> variable to a string identifying the |
125 | license, e.g. in <filename | | 125 | license, e.g. in <filename |
126 | role="pkg">graphics/xv</filename>:</para> | | 126 | role="pkg">graphics/xv</filename>:</para> |
127 | | | 127 | |
128 | <programlisting> | | 128 | <programlisting> |
129 | LICENSE= xv-license | | 129 | LICENSE= xv-license |
130 | </programlisting> | | 130 | </programlisting> |
131 | | | 131 | |
132 | <para>When trying to build, the user will get a notice that the | | 132 | <para>When trying to build, the user will get a notice that the |
133 | package is covered by a license which has not been placed in the | | 133 | package is covered by a license which has not been placed in the |
134 | <varname>ACCEPTABLE_LICENSES</varname> variable:</para> | | 134 | <varname>ACCEPTABLE_LICENSES</varname> variable:</para> |
135 | | | 135 | |
136 | <programlisting> | | 136 | <programlisting> |
137 | &cprompt; <userinput>make</userinput> | | 137 | &cprompt; <userinput>make</userinput> |
138 | ===> xv-3.10anb9 has an unacceptable license: xv-license. | | 138 | ===> xv-3.10anb9 has an unacceptable license: xv-license. |
139 | ===> To view the license, enter "/usr/bin/make show-license". | | 139 | ===> To view the license, enter "/usr/bin/make show-license". |
140 | ===> To indicate acceptance, add this line to your /etc/mk.conf: | | 140 | ===> To indicate acceptance, add this line to your /etc/mk.conf: |
141 | ===> ACCEPTABLE_LICENSES+=xv-license | | 141 | ===> ACCEPTABLE_LICENSES+=xv-license |
142 | *** Error code 1 | | 142 | *** Error code 1 |
143 | </programlisting> | | 143 | </programlisting> |
144 | | | 144 | |
145 | <para>The license can be viewed with <command>make | | 145 | <para>The license can be viewed with <command>make |
146 | show-license</command>, and if the user so chooses, the line | | 146 | show-license</command>, and if the user so chooses, the line |
147 | printed above can be added to &mk.conf; to | | 147 | printed above can be added to &mk.conf; to |
148 | convey to pkgsrc that it should not in the future fail because of | | 148 | convey to pkgsrc that it should not in the future fail because of |
149 | that license:</para> | | 149 | that license:</para> |
150 | | | 150 | |
151 | <programlisting> | | 151 | <programlisting> |
152 | ACCEPTABLE_LICENSES+=xv-license | | 152 | ACCEPTABLE_LICENSES+=xv-license |
153 | </programlisting> | | 153 | </programlisting> |
154 | | | 154 | |
155 | <para>The use of <varname>LICENSE=shareware</varname>, | | 155 | <para>The use of <varname>LICENSE=shareware</varname>, |
156 | <varname>LICENSE=no-commercial-use</varname>, and similar language | | 156 | <varname>LICENSE=no-commercial-use</varname>, and similar language |
157 | is deprecated because it does not crisply refer to a particular | | 157 | is deprecated because it does not crisply refer to a particular |
158 | license text. Another problem with such usage is that it does not | | 158 | license text. Another problem with such usage is that it does not |
159 | enable a user to tell pkgsrc to proceed for a single package | | 159 | enable a user to tell pkgsrc to proceed for a single package |
160 | without also telling pkgsrc to proceed for all packages with that | | 160 | without also telling pkgsrc to proceed for all packages with that |
161 | tag.</para> | | 161 | tag.</para> |
162 | | | 162 | |
163 | <sect3 id="new-license"> | | 163 | <sect3 id="new-license"> |
164 | <title>Adding a package with a new license</title> | | 164 | <title>Adding a package with a new license</title> |
165 | | | 165 | |
166 | <para>When adding a package with a new license, the following steps | | 166 | <para>When adding a package with a new license, the following steps |
167 | are required:</para> | | 167 | are required:</para> |
168 | <orderedlist> | | 168 | <orderedlist> |
169 | | | 169 | |
170 | <listitem> | | 170 | <listitem> |
171 | | | 171 | |
172 | <para>Check whether the license qualifies as Free or Open Source by | | 172 | <para>Check whether the license qualifies as Free or Open Source by |
173 | referencing <ulink | | 173 | referencing <ulink |
174 | url="https://www.gnu.org/licenses/license-list.en.html">Various | | 174 | url="https://www.gnu.org/licenses/license-list.en.html">Various |
175 | Licenses and Comments about Them</ulink> and <ulink | | 175 | Licenses and Comments about Them</ulink> and <ulink |
176 | url="https://opensource.org/licenses/alphabetical">Licenses by Name | | | 176 | url="https://opensource.org/licenses/alphabetical">Licenses by Name | |
177 | Open Source Initiative</ulink>. If this is the case, the filename in | | 177 | Open Source Initiative</ulink>. If this is the case, the filename in |
178 | <filename>pkgsrc/licenses/</filename> does not need the | | 178 | <filename>pkgsrc/licenses/</filename> does not need the |
179 | <filename>-license</filename> suffix, and the license name should be | | 179 | <filename>-license</filename> suffix, and the license name should be |
180 | added to:</para> | | 180 | added to:</para> |
181 | | | 181 | |
182 | <itemizedlist> | | 182 | <itemizedlist> |
183 | | | 183 | |
184 | <listitem><para>DEFAULT_ACCEPTABLE_LICENSES in | | 184 | <listitem><para>DEFAULT_ACCEPTABLE_LICENSES in |
185 | <filename>pkgsrc/mk/license.mk</filename></para></listitem> | | 185 | <filename>pkgsrc/mk/license.mk</filename></para></listitem> |
186 | | | 186 | |
187 | <listitem><para>default_acceptable_licenses in | | 187 | <listitem><para>default_acceptable_licenses in |
188 | <filename>pkgsrc/pkgtools/pkg_install/files/lib/license.c</filename></para></listitem> | | 188 | <filename>pkgsrc/pkgtools/pkg_install/files/lib/license.c</filename></para></listitem> |
189 | | | 189 | |
190 | </itemizedlist> | | 190 | </itemizedlist> |
191 | </listitem> | | 191 | </listitem> |
192 | | | 192 | |
193 | <listitem><para>The license text should be added to | | 193 | <listitem><para>The license text should be added to |
194 | <filename>pkgsrc/licenses</filename> for displaying. A list of known | | 194 | <filename>pkgsrc/licenses</filename> for displaying. A list of known |
195 | licenses can be seen in this directory.</para></listitem> | | 195 | licenses can be seen in this directory.</para></listitem> |
196 | | | 196 | |
197 | </orderedlist> | | 197 | </orderedlist> |
198 | </sect3> | | 198 | </sect3> |
199 | | | 199 | |
200 | <sect3 id="change-license"> | | 200 | <sect3 id="change-license"> |
201 | <title>Change to the license</title> | | 201 | <title>Change to the license</title> |
202 | | | 202 | |
203 | <para>When the license changes (in a way other than formatting), | | 203 | <para>When the license changes (in a way other than formatting), |
204 | make sure that the new license has a different name (e.g., | | 204 | make sure that the new license has a different name (e.g., |
205 | append the version number if it exists, or the date). Just | | 205 | append the version number if it exists, or the date). Just |
206 | because a user told pkgsrc to build programs under a previous | | 206 | because a user told pkgsrc to build programs under a previous |
207 | version of a license does not mean that pkgsrc should build | | 207 | version of a license does not mean that pkgsrc should build |
208 | programs under the new licenses. The higher-level point is that | | 208 | programs under the new licenses. The higher-level point is that |
209 | pkgsrc does not evaluate licenses for reasonableness; the only | | 209 | pkgsrc does not evaluate licenses for reasonableness; the only |
210 | test is a mechanistic test of whether a particular text has been | | 210 | test is a mechanistic test of whether a particular text has been |
211 | approved by either of two bodies (FSF or OSI).</para> | | 211 | approved by either of two bodies (FSF or OSI).</para> |
212 | </sect3> | | 212 | </sect3> |
213 | </sect2> | | 213 | </sect2> |
214 | | | 214 | |
215 | <sect2 id="restricted-packages"> | | 215 | <sect2 id="restricted-packages"> |
216 | <title>Restricted packages</title> | | 216 | <title>Restricted packages</title> |
217 | | | 217 | |
218 | <para>Some licenses restrict how software may be re-distributed. | | 218 | <para>Some licenses restrict how software may be re-distributed. |
219 | By declaring the restrictions, package tools can | | 219 | By declaring the restrictions, package tools can |
220 | automatically refrain from e.g. placing binary packages on FTP | | 220 | automatically refrain from e.g. placing binary packages on FTP |
221 | sites.</para> | | 221 | sites.</para> |
222 | | | 222 | |
223 | <para>There are four possible restrictions, which are | | 223 | <para>There are four possible restrictions, which are |
224 | the cross product of sources (distfiles) and binaries not being | | 224 | the cross product of sources (distfiles) and binaries not being |
225 | placed on FTP sites and CD-ROMs. Because this is rarely the exact | | 225 | placed on FTP sites and CD-ROMs. Because this is rarely the exact |
226 | language in any license, and because non-Free licenses tend to be | | 226 | language in any license, and because non-Free licenses tend to be |
227 | different from each other, pkgsrc adopts a definition of FTP and | | 227 | different from each other, pkgsrc adopts a definition of FTP and |
228 | CD-ROM. | | 228 | CD-ROM. |
229 | | | 229 | |
230 | "FTP" means making the source or binary file available over the | | 230 | "FTP" means making the source or binary file available over the |
231 | Internet at no charge. | | 231 | Internet at no charge. |
232 | | | 232 | |
233 | "CD-ROM" means making the source or binary available on some kind of | | 233 | "CD-ROM" means making the source or binary available on some kind of |
234 | media, together with other source and binary packages, which is sold | | 234 | media, together with other source and binary packages, which is sold |
235 | for a distribution charge. | | 235 | for a distribution charge. |
236 | </para> | | 236 | </para> |
237 | | | 237 | |
238 | <para>In order to encode these restrictions, the package system | | 238 | <para>In order to encode these restrictions, the package system |
239 | defines five make variables that can be set to note these | | 239 | defines five make variables that can be set to note these |
240 | restrictions:</para> | | 240 | restrictions:</para> |
241 | | | 241 | |
242 | <itemizedlist> | | 242 | <itemizedlist> |
243 | <listitem> | | 243 | <listitem> |
244 | <para><varname>RESTRICTED</varname></para> | | 244 | <para><varname>RESTRICTED</varname></para> |
245 | | | 245 | |
246 | <para>This variable should be set whenever a restriction | | 246 | <para>This variable should be set whenever a restriction |
247 | exists (regardless of its kind). Set this variable to a | | 247 | exists (regardless of its kind). Set this variable to a |
248 | string containing the reason for the restriction. It should | | 248 | string containing the reason for the restriction. It should |
249 | be understood that those wanting to understand the restriction | | 249 | be understood that those wanting to understand the restriction |
250 | will have to read the license, and perhaps seek advice of | | 250 | will have to read the license, and perhaps seek advice of |
251 | counsel.</para> | | 251 | counsel.</para> |
252 | </listitem> | | 252 | </listitem> |
253 | | | 253 | |
254 | <listitem> | | 254 | <listitem> |
255 | <para><varname>NO_BIN_ON_CDROM</varname></para> | | 255 | <para><varname>NO_BIN_ON_CDROM</varname></para> |
256 | | | 256 | |
257 | <para>Binaries may not be placed on CD-ROM containing other | | 257 | <para>Binaries may not be placed on CD-ROM containing other |
258 | binary packages, for which a distribution charge may be made. | | 258 | binary packages, for which a distribution charge may be made. |
259 | In this case, set this variable to | | 259 | In this case, set this variable to |
260 | <varname>${RESTRICTED}</varname>.</para> | | 260 | <varname>${RESTRICTED}</varname>.</para> |
261 | </listitem> | | 261 | </listitem> |
262 | | | 262 | |
263 | <listitem> | | 263 | <listitem> |
264 | <para><varname>NO_BIN_ON_FTP</varname></para> | | 264 | <para><varname>NO_BIN_ON_FTP</varname></para> |
265 | | | 265 | |
266 | <para>Binaries may not made available on the Internet without | | 266 | <para>Binaries may not made available on the Internet without |
267 | charge. In this case, set this variable to | | 267 | charge. In this case, set this variable to |
268 | <varname>${RESTRICTED}</varname>. If this variable is set, | | 268 | <varname>${RESTRICTED}</varname>. If this variable is set, |
269 | binary packages will not be included on ftp.NetBSD.org.</para> | | 269 | binary packages will not be included on ftp.NetBSD.org.</para> |
270 | </listitem> | | 270 | </listitem> |
271 | | | 271 | |
272 | <listitem> | | 272 | <listitem> |
273 | <para><varname>NO_SRC_ON_CDROM</varname></para> | | 273 | <para><varname>NO_SRC_ON_CDROM</varname></para> |
274 | | | 274 | |
275 | <para>Distfiles may not be placed on CD-ROM, together with | | 275 | <para>Distfiles may not be placed on CD-ROM, together with |
276 | other distfiles, for which a fee may be charged. In this | | 276 | other distfiles, for which a fee may be charged. In this |
277 | case, set this variable to <varname>${RESTRICTED}</varname>. | | 277 | case, set this variable to <varname>${RESTRICTED}</varname>. |
278 | </para> | | 278 | </para> |
279 | </listitem> | | 279 | </listitem> |
280 | | | 280 | |
281 | <listitem> | | 281 | <listitem> |
282 | <para><varname>NO_SRC_ON_FTP</varname></para> | | 282 | <para><varname>NO_SRC_ON_FTP</varname></para> |
283 | | | 283 | |
284 | <para>Distfiles may not made available via FTP at no charge. | | 284 | <para>Distfiles may not made available via FTP at no charge. |
285 | In this case, set this variable to | | 285 | In this case, set this variable to |
286 | <varname>${RESTRICTED}</varname>. If this variable is set, | | 286 | <varname>${RESTRICTED}</varname>. If this variable is set, |
287 | the distfile(s) will not be mirrored on ftp.NetBSD.org.</para> | | 287 | the distfile(s) will not be mirrored on ftp.NetBSD.org.</para> |
288 | </listitem> | | 288 | </listitem> |
289 | </itemizedlist> | | 289 | </itemizedlist> |
290 | | | 290 | |
291 | <para>Please note that packages will be removed from pkgsrc when the | | 291 | <para>Please note that packages will be removed from pkgsrc when the |
292 | distfiles are not distributable and cannot be obtained for a period | | 292 | distfiles are not distributable and cannot be obtained for a period |
293 | of one full quarter branch. Packages with manual/interactive fetch | | 293 | of one full quarter branch. Packages with manual/interactive fetch |
294 | must have a maintainer and it is his/her responsibility to ensure | | 294 | must have a maintainer and it is his/her responsibility to ensure |
295 | this.</para> | | 295 | this.</para> |
296 | </sect2> | | 296 | </sect2> |
297 | | | 297 | |
298 | | | 298 | |
299 | <sect2 id="dependencies"> | | 299 | <sect2 id="dependencies"> |
300 | <title>Handling dependencies</title> | | 300 | <title>Handling dependencies</title> |
301 | | | 301 | |
302 | <para>Your package may depend on some other package being present, | | 302 | <para>Your package may depend on some other package being present, |
303 | and there are various ways of expressing this dependency. | | 303 | and there are various ways of expressing this dependency. |
304 | pkgsrc supports the <varname>DEPENDS</varname>, | | 304 | pkgsrc supports the <varname>DEPENDS</varname>, |
305 | <varname>BUILD_DEPENDS</varname>, | | 305 | <varname>BUILD_DEPENDS</varname>, |
306 | <varname>TOOL_DEPENDS</varname>, and | | 306 | <varname>TOOL_DEPENDS</varname>, and |
307 | <varname>TEST_DEPENDS</varname> definitions, the | | 307 | <varname>TEST_DEPENDS</varname> definitions, the |
308 | <varname>USE_TOOLS</varname> definition, as well as dependencies | | 308 | <varname>USE_TOOLS</varname> definition, as well as dependencies |
309 | via <filename>buildlink3.mk</filename>, which is the preferred way | | 309 | via <filename>buildlink3.mk</filename>, which is the preferred way |
310 | to handle dependencies, and which uses the variables named above. | | 310 | to handle dependencies, and which uses the variables named above. |
311 | See <xref linkend="buildlink"/> for more information.</para> | | 311 | See <xref linkend="buildlink"/> for more information.</para> |
312 | | | 312 | |
313 | <para>The basic difference is that the <varname>DEPENDS</varname> | | 313 | <para>The basic difference is that the <varname>DEPENDS</varname> |
314 | definition registers that pre-requisite in the binary package so it | | 314 | definition registers that pre-requisite in the binary package so it |
315 | will be pulled in when the binary package is later installed, whilst | | 315 | will be pulled in when the binary package is later installed, whilst |
316 | the <varname>BUILD_DEPENDS</varname>, <varname>TOOL_DEPENDS</varname>, | | 316 | the <varname>BUILD_DEPENDS</varname>, <varname>TOOL_DEPENDS</varname>, |
317 | and <varname>TEST_DEPENDS</varname> definitions do not, marking a | | 317 | and <varname>TEST_DEPENDS</varname> definitions do not, marking a |
318 | dependency that is only needed for building or testing the resulting | | 318 | dependency that is only needed for building or testing the resulting |
319 | package. See also <xref linkend="creating"/> for more information.</para> | | 319 | package. See also <xref linkend="creating"/> for more information.</para> |
320 | | | 320 | |
321 | <para>This means that if you only need a package present whilst | | 321 | <para>This means that if you only need a package present whilst |
322 | you are building or testing, it should be noted as a | | 322 | you are building or testing, it should be noted as a |
323 | <varname>TOOL_DEPENDS</varname>, | | 323 | <varname>TOOL_DEPENDS</varname>, |
324 | <varname>BUILD_DEPENDS</varname>, or | | 324 | <varname>BUILD_DEPENDS</varname>, or |
325 | <varname>TEST_DEPENDS</varname>. When cross-compiling, | | 325 | <varname>TEST_DEPENDS</varname>. When cross-compiling, |
326 | <varname>TOOL_DEPENDS</varname> are <emphasis>native</emphasis> | | 326 | <varname>TOOL_DEPENDS</varname> are <emphasis>native</emphasis> |
327 | packages, i.e. packages for the architecture where the package | | 327 | packages, i.e. packages for the architecture where the package |
328 | is built; | | 328 | is built; |
329 | <varname>BUILD_DEPENDS</varname> are <emphasis>target</emphasis> | | 329 | <varname>BUILD_DEPENDS</varname> are <emphasis>target</emphasis> |
330 | packages, i.e., packages for the architecture for which the package | | 330 | packages, i.e., packages for the architecture for which the package |
331 | is built.</para> | | 331 | is built.</para> |
332 | | | 332 | |
333 | <para>The format for a <varname>DEPENDS</varname>, | | 333 | <para>The format for a <varname>DEPENDS</varname>, |
334 | <varname>BUILD_DEPENDS</varname>, <varname>TOOL_DEPENDS</varname>, | | 334 | <varname>BUILD_DEPENDS</varname>, <varname>TOOL_DEPENDS</varname>, |
335 | and <varname>TEST_DEPENDS</varname> definition is:</para> | | 335 | and <varname>TEST_DEPENDS</varname> definition is:</para> |
336 | | | 336 | |
337 | <programlisting> | | 337 | <programlisting> |
338 | <pre-req-package-name>:../../<category>/<pre-req-package> | | 338 | <pre-req-package-name>:../../<category>/<pre-req-package> |
339 | </programlisting> | | 339 | </programlisting> |
340 | | | 340 | |
341 | <para>Please note that the <quote>pre-req-package-name</quote> | | 341 | <para>Please note that the <quote>pre-req-package-name</quote> |
342 | may include any of the wildcard version numbers recognized by | | 342 | may include any of the wildcard version numbers recognized by |
343 | &man.pkg.info.1;.</para> | | 343 | &man.pkg.info.1;.</para> |
344 | | | 344 | |
345 | <orderedlist> | | 345 | <orderedlist> |
346 | <listitem> | | 346 | <listitem> |
347 | <para>If your package needs another package's binaries or | | 347 | <para>If your package needs another package's binaries or |
348 | libraries to build and run, and if that package has a | | 348 | libraries to build and run, and if that package has a |
349 | <filename>buildlink3.mk</filename> file available, use it:</para> | | 349 | <filename>buildlink3.mk</filename> file available, use it:</para> |
350 | | | 350 | |
351 | <programlisting> | | 351 | <programlisting> |
352 | .include "../../graphics/jpeg/buildlink3.mk" | | 352 | .include "../../graphics/jpeg/buildlink3.mk" |
353 | </programlisting> | | 353 | </programlisting> |
354 | </listitem> | | 354 | </listitem> |
355 | | | 355 | |
356 | <listitem> | | 356 | <listitem> |
357 | <para>If your package needs another package's binaries or | | 357 | <para>If your package needs another package's binaries or |
358 | libraries only for building, and if that package has a | | 358 | libraries only for building, and if that package has a |
359 | <filename>buildlink3.mk</filename> file available, use it:</para> | | 359 | <filename>buildlink3.mk</filename> file available, use it:</para> |
360 | | | 360 | |
361 | <programlisting> | | 361 | <programlisting> |
362 | .include "../../graphics/jpeg/buildlink3.mk" | | 362 | .include "../../graphics/jpeg/buildlink3.mk" |
363 | </programlisting> | | 363 | </programlisting> |
364 | <para>but set | | 364 | <para>but set |
365 | <varname>BUILDLINK_DEPMETHOD.<replaceable>jpeg</replaceable>?=build</varname> | | 365 | <varname>BUILDLINK_DEPMETHOD.<replaceable>jpeg</replaceable>?=build</varname> |
366 | to make it a build dependency only. This case is rather | | 366 | to make it a build dependency only. This case is rather |
367 | rare.</para> | | 367 | rare.</para> |
368 | </listitem> | | 368 | </listitem> |
369 | | | 369 | |
370 | <listitem> | | 370 | <listitem> |
371 | <para>If your package needs binaries from another package to build, | | 371 | <para>If your package needs binaries from another package to build, |
372 | use the <varname>TOOL_DEPENDS</varname> definition:</para> | | 372 | use the <varname>TOOL_DEPENDS</varname> definition:</para> |
373 | | | 373 | |
374 | <programlisting> | | 374 | <programlisting> |
375 | TOOL_DEPENDS+= itstool-[0-9]*:../../textproc/itstool | | 375 | TOOL_DEPENDS+= itstool-[0-9]*:../../textproc/itstool |
376 | </programlisting> | | 376 | </programlisting> |
377 | </listitem> | | 377 | </listitem> |
378 | | | 378 | |
379 | <listitem> | | 379 | <listitem> |
380 | <para>If your package needs static libraries to link against, header | | 380 | <para>If your package needs static libraries to link against, header |
381 | files to include, etc. from another package to build, | | 381 | files to include, etc. from another package to build, |
382 | use the <varname>BUILD_DEPENDS</varname> definition.</para> | | 382 | use the <varname>BUILD_DEPENDS</varname> definition.</para> |
383 | | | 383 | |
384 | <!-- | | 384 | <!-- |
385 | <programlisting> | | 385 | <programlisting> |
386 | BUILD_DEPENDS+= TODO: find a good example | | 386 | BUILD_DEPENDS+= TODO: find a good example |
387 | </programlisting> --> | | 387 | </programlisting> --> |
388 | </listitem> | | 388 | </listitem> |
389 | | | 389 | |
390 | <listitem> | | 390 | <listitem> |
391 | <para>If your package needs a library with which to link and | | 391 | <para>If your package needs a library with which to link and |
392 | there is no <filename>buildlink3.mk</filename> file | | 392 | there is no <filename>buildlink3.mk</filename> file |
393 | available, create one. Using | | 393 | available, create one. Using |
394 | <varname>DEPENDS</varname> won't be sufficient because the | | 394 | <varname>DEPENDS</varname> won't be sufficient because the |
395 | include files and libraries will be hidden from the compiler.</para> | | 395 | include files and libraries will be hidden from the compiler.</para> |
396 | </listitem> | | 396 | </listitem> |
397 | | | 397 | |
398 | <listitem> | | 398 | <listitem> |
399 | <para>If your package needs some executable to be able to run | | 399 | <para>If your package needs some executable to be able to run |
400 | correctly and if there's no | | 400 | correctly and if there's no |
401 | <filename>buildlink3.mk</filename> file, this is specified | | 401 | <filename>buildlink3.mk</filename> file, this is specified |
402 | using the <varname>DEPENDS</varname> variable. The | | 402 | using the <varname>DEPENDS</varname> variable. The |
403 | <filename role="pkg">print/lyx</filename> package needs to | | 403 | <filename role="pkg">print/lyx</filename> package needs to |
404 | be able to execute the latex binary from the tex-latex-bin package | | 404 | be able to execute the latex binary from the tex-latex-bin package |
405 | when it runs, and that is specified:</para> | | 405 | when it runs, and that is specified:</para> |
406 | | | 406 | |
407 | <programlisting> | | 407 | <programlisting> |
408 | DEPENDS+= tex-latex-bin-[0-9]*:../../print/tex-latex-bin | | 408 | DEPENDS+= tex-latex-bin-[0-9]*:../../print/tex-latex-bin |
409 | </programlisting> | | 409 | </programlisting> |
410 | </listitem> | | 410 | </listitem> |
411 | <listitem> | | 411 | <listitem> |
412 | <para>If your package includes a test suite that has extra | | 412 | <para>If your package includes a test suite that has extra |
413 | dependencies only required for this purpose (frequently this | | 413 | dependencies only required for this purpose (frequently this |
414 | can be run as a <quote>make test</quote> target), use the | | 414 | can be run as a <quote>make test</quote> target), use the |
415 | <varname>TEST_DEPENDS</varname> variable.</para> | | 415 | <varname>TEST_DEPENDS</varname> variable.</para> |
416 | </listitem> | | 416 | </listitem> |
417 | <listitem> | | 417 | <listitem> |
418 | <para>You can use wildcards in package dependencies. Note that | | 418 | <para>You can use wildcards in package dependencies. Note that |
419 | such wildcard dependencies are retained when creating binary | | 419 | such wildcard dependencies are retained when creating binary |
420 | packages. The dependency is checked when installing the binary | | 420 | packages. The dependency is checked when installing the binary |
421 | package and any package which matches the pattern will be | | 421 | package and any package which matches the pattern will be |
422 | used. Wildcard dependencies should be used with care.</para> | | 422 | used. Wildcard dependencies should be used with care.</para> |
423 | | | 423 | |
424 | <para>The <quote>-[0-9]*</quote> should be used instead of | | 424 | <para>The <quote>-[0-9]*</quote> should be used instead of |
425 | <quote>-*</quote> to avoid potentially ambiguous matches | | 425 | <quote>-*</quote> to avoid potentially ambiguous matches |
426 | such as <quote>tk-postgresql</quote> matching a | | 426 | such as <quote>tk-postgresql</quote> matching a |
427 | <quote>tk-*</quote> <varname>DEPENDS</varname>.</para> | | 427 | <quote>tk-*</quote> <varname>DEPENDS</varname>.</para> |
428 | | | 428 | |
429 | <para>Wildcards can also be used to specify that a package | | 429 | <para>Wildcards can also be used to specify that a package |
430 | will only build against a certain minimum version of a | | 430 | will only build against a certain minimum version of a |
431 | pre-requisite:</para> | | 431 | pre-requisite:</para> |
432 | | | 432 | |
433 | <programlisting> | | 433 | <programlisting> |
434 | DEPENDS+= ImageMagick>=6.0:../../graphics/ImageMagick | | 434 | DEPENDS+= ImageMagick>=6.0:../../graphics/ImageMagick |
435 | </programlisting> | | 435 | </programlisting> |
436 | | | 436 | |
437 | <para>This means that the package will build using version 6.0 | | 437 | <para>This means that the package will build using version 6.0 |
438 | of ImageMagick or newer. Such a dependency may be warranted | | 438 | of ImageMagick or newer. Such a dependency may be warranted |
439 | if, for example, the command line options of an executable | | 439 | if, for example, the command line options of an executable |
440 | have changed.</para> | | 440 | have changed.</para> |
441 | | | 441 | |
442 | <para>If you need to depend on minimum versions of libraries, | | 442 | <para>If you need to depend on minimum versions of libraries, |
443 | set | | 443 | set |
444 | <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname> | | 444 | <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname> |
445 | to the appropriate pattern before including its | | 445 | to the appropriate pattern before including its |
446 | <filename>buildlink3.mk</filename> file, e.g.</para> | | 446 | <filename>buildlink3.mk</filename> file, e.g.</para> |
447 | | | 447 | |
448 | <programlisting> | | 448 | <programlisting> |
449 | BUILDLINK_API_DEPENDS.jpeg+= jpeg>=9.0 | | 449 | BUILDLINK_API_DEPENDS.jpeg+= jpeg>=9.0 |
450 | .include "../../graphics/jpeg/buildlink3.mk" | | 450 | .include "../../graphics/jpeg/buildlink3.mk" |
451 | </programlisting> | | 451 | </programlisting> |
452 | | | 452 | |
453 | <para>For security fixes, please update the package | | 453 | <para>For security fixes, please update the package |
454 | vulnerabilities file. See <xref | | 454 | vulnerabilities file. See <xref |
455 | linkend="security-handling"/> for more | | 455 | linkend="security-handling"/> for more |
456 | information.</para> | | 456 | information.</para> |
457 | </listitem> | | 457 | </listitem> |
458 | </orderedlist> | | 458 | </orderedlist> |
459 | | | 459 | |
460 | <para>If your package needs files from another package to build, | | 460 | <para>If your package needs files from another package to build, |
461 | add the relevant distribution files to | | 461 | add the relevant distribution files to |
462 | <varname>DISTFILES</varname>, so they will be extracted | | 462 | <varname>DISTFILES</varname>, so they will be extracted |
463 | automatically. See the <filename | | 463 | automatically. See the <filename |
464 | role="pkg">print/ghostscript</filename> package for an example. | | 464 | role="pkg">print/ghostscript</filename> package for an example. |
465 | (It relies on the jpeg sources being present in source form | | 465 | (It relies on the jpeg sources being present in source form |
466 | during the build.)</para> | | 466 | during the build.)</para> |
467 | </sect2> | | 467 | </sect2> |
468 | | | 468 | |
469 | | | 469 | |
470 | <sect2 id="conflicts"> | | 470 | <sect2 id="conflicts"> |
471 | <title>Handling conflicts with other packages</title> | | 471 | <title>Handling conflicts with other packages</title> |
472 | | | 472 | |
473 | <para>Your package may conflict with other packages users might | | 473 | <para>Your package may conflict with other packages users might |
474 | already have installed on their system, e.g., if your package | | 474 | already have installed on their system, e.g., if your package |
475 | installs the same set of files as another package in the pkgsrc | | 475 | installs the same set of files as another package in the pkgsrc |
476 | tree.</para> | | 476 | tree.</para> |
477 | | | 477 | |
478 | <para>For example, <filename role="pkg">x11/libXaw3d</filename> | | 478 | <para>For example, <filename role="pkg">x11/libXaw3d</filename> |
479 | and <filename role="pkg">x11/Xaw-Xpm</filename> | | 479 | and <filename role="pkg">x11/Xaw-Xpm</filename> |
480 | install the same shared library, thus you set in | | 480 | install the same shared library, thus you set in |
481 | <filename>pkgsrc/x11/libXaw3d/Makefile</filename>:</para> | | 481 | <filename>pkgsrc/x11/libXaw3d/Makefile</filename>:</para> |
482 | | | 482 | |
483 | <programlisting> | | 483 | <programlisting> |
484 | CONFLICTS= Xaw-Xpm-[0-9]* | | 484 | CONFLICTS= Xaw-Xpm-[0-9]* |
485 | </programlisting> | | 485 | </programlisting> |
486 | | | 486 | |
487 | <para>and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>:</para> | | 487 | <para>and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>:</para> |
488 | | | 488 | |
489 | <programlisting> | | 489 | <programlisting> |
490 | CONFLICTS= libXaw3d-[0-9]* | | 490 | CONFLICTS= libXaw3d-[0-9]* |
491 | </programlisting> | | 491 | </programlisting> |
492 | | | 492 | |
493 | <para>&man.pkg.add.1 is able to detect attempts to install packages | | 493 | <para>&man.pkg.add.1 is able to detect attempts to install packages |
494 | that conflict with existing packages and abort. However, in many | | 494 | that conflict with existing packages and abort. However, in many |
495 | situations this is too late in the process. Binary package managers | | 495 | situations this is too late in the process. Binary package managers |
496 | will not know about the conflict until they attempt to install the | | 496 | will not know about the conflict until they attempt to install the |
497 | package after already downloading it and all its dependencies. | | 497 | package after already downloading it and all its dependencies. |
498 | Users may also waste time building a package and its dependencies | | 498 | Users may also waste time building a package and its dependencies |
499 | only to find out at the end that it conflicts with another package | | 499 | only to find out at the end that it conflicts with another package |
500 | they have installed.</para> | | 500 | they have installed.</para> |
501 | | | 501 | |
502 | <para>To avoid these issues <varname>CONFLICTS</varname> entries | | 502 | <para>To avoid these issues <varname>CONFLICTS</varname> entries |
503 | should be added in all cases where it is known that packages conflict | | 503 | should be added in all cases where it is known that packages conflict |
504 | with each other. These <varname>CONFLICTS</varname> entries are | | 504 | with each other. These <varname>CONFLICTS</varname> entries are |
505 | exported in &man.pkg.summary.5 files and consumed by binary package | | 505 | exported in &man.pkg.summary.5 files and consumed by binary package |
506 | managers to inform users that packages cannot be installed onto | | 506 | managers to inform users that packages cannot be installed onto |
507 | the target system.</para> | | 507 | the target system.</para> |
508 | </sect2> | | 508 | </sect2> |
509 | | | 509 | |
510 | | | 510 | |
511 | <sect2 id="not-building-packages"> | | 511 | <sect2 id="not-building-packages"> |
512 | <title>Packages that cannot or should not be built</title> | | 512 | <title>Packages that cannot or should not be built</title> |
513 | | | 513 | |
514 | <para>There are several reasons why a package might be | | 514 | <para>There are several reasons why a package might be |
515 | instructed to not build under certain circumstances. If the | | 515 | instructed to not build under certain circumstances. If the |
516 | package builds and runs on most platforms, the exceptions | | 516 | package builds and runs on most platforms, the exceptions |
517 | should be noted with <varname>BROKEN_ON_PLATFORM</varname>. If | | 517 | should be noted with <varname>BROKEN_ON_PLATFORM</varname>. If |
518 | the package builds and runs on a small handful of platforms, | | 518 | the package builds and runs on a small handful of platforms, |
519 | set <varname>BROKEN_EXCEPT_ON_PLATFORM</varname> instead. | | 519 | set <varname>BROKEN_EXCEPT_ON_PLATFORM</varname> instead. |
520 | Both <varname>BROKEN_ON_PLATFORM</varname> and | | 520 | Both <varname>BROKEN_ON_PLATFORM</varname> and |
521 | <varname>BROKEN_EXCEPT_ON_PLATFORM</varname> are OS triples | | 521 | <varname>BROKEN_EXCEPT_ON_PLATFORM</varname> are OS triples |
522 | (OS-version-platform) that can use glob-style | | 522 | (OS-version-platform) that can use glob-style |
523 | wildcards.</para> | | 523 | wildcards.</para> |
524 | <para>If a package is not appropriate for some platforms (as | | 524 | <para>If a package is not appropriate for some platforms (as |
525 | opposed to merely broken), a different set of variables should be | | 525 | opposed to merely broken), a different set of variables should be |
526 | used as this affects failure reporting and statistics. | | 526 | used as this affects failure reporting and statistics. |
527 | If the package is appropriate for most platforms, the exceptions | | 527 | If the package is appropriate for most platforms, the exceptions |
528 | should be noted with <varname>NOT_FOR_PLATFORM</varname>. If | | 528 | should be noted with <varname>NOT_FOR_PLATFORM</varname>. If |
529 | the package is appropriate for only a small handful of platforms | | 529 | the package is appropriate for only a small handful of platforms |
530 | (often exactly one), set <varname>ONLY_FOR_PLATFORM</varname> instead. | | 530 | (often exactly one), set <varname>ONLY_FOR_PLATFORM</varname> instead. |
531 | Both <varname>ONLY_FOR_PLATFORM</varname> and | | 531 | Both <varname>ONLY_FOR_PLATFORM</varname> and |
532 | <varname>NOT_FOR_PLATFORM</varname> are OS triples | | 532 | <varname>NOT_FOR_PLATFORM</varname> are OS triples |
533 | (OS-version-platform) that can use glob-style | | 533 | (OS-version-platform) that can use glob-style |
534 | wildcards.</para> | | 534 | wildcards.</para> |
535 | <para>Some packages are tightly bound to a specific version of an | | 535 | <para>Some packages are tightly bound to a specific version of an |
536 | operating system, e.g. LKMs or <filename | | 536 | operating system, e.g. LKMs or <filename |
537 | role="pkg">sysutils/lsof</filename>. Such binary packages are not | | 537 | role="pkg">sysutils/lsof</filename>. Such binary packages are not |
538 | backwards compatible with other versions of the OS, and should be | | 538 | backwards compatible with other versions of the OS, and should be |
539 | uploaded to a version specific directory on the FTP server. Mark | | 539 | uploaded to a version specific directory on the FTP server. Mark |
540 | these packages by setting <varname>OSVERSION_SPECIFIC</varname> to | | 540 | these packages by setting <varname>OSVERSION_SPECIFIC</varname> to |
541 | <quote>yes</quote>. This variable is not currently used by any of | | 541 | <quote>yes</quote>. This variable is not currently used by any of |
542 | the package system internals, but may be used in the | | 542 | the package system internals, but may be used in the |
543 | future.</para> | | 543 | future.</para> |
544 | <para>If the package should be skipped (for example, because it | | 544 | <para>If the package should be skipped (for example, because it |
545 | provides functionality already provided by the system), set | | 545 | provides functionality already provided by the system), set |
546 | <varname>PKG_SKIP_REASON</varname> to a descriptive message. If | | 546 | <varname>PKG_SKIP_REASON</varname> to a descriptive message. If |
547 | the package should fail because some preconditions are not met, | | 547 | the package should fail because some preconditions are not met, |
548 | set <varname>PKG_FAIL_REASON</varname> to a descriptive | | 548 | set <varname>PKG_FAIL_REASON</varname> to a descriptive |
549 | message.</para> | | 549 | message.</para> |
550 | </sect2> | | 550 | </sect2> |
551 | | | 551 | |
552 | | | 552 | |
553 | <sect2 id="undeletable-packages"> | | 553 | <sect2 id="undeletable-packages"> |
554 | <title>Packages which should not be deleted, once installed</title> | | 554 | <title>Packages which should not be deleted, once installed</title> |
555 | | | 555 | |
556 | <para>To ensure that a package may not be deleted, once it has been | | 556 | <para>To ensure that a package may not be deleted, once it has been |
557 | installed, the <varname>PKG_PRESERVE</varname> definition should | | 557 | installed, the <varname>PKG_PRESERVE</varname> definition should |
558 | be set in the package Makefile. This will be carried into any | | 558 | be set in the package Makefile. This will be carried into any |
559 | binary package that is made from this pkgsrc entry. A | | 559 | binary package that is made from this pkgsrc entry. A |
560 | <quote>preserved</quote> package will | | 560 | <quote>preserved</quote> package will |
561 | not be deleted using &man.pkg.delete.1; unless the | | 561 | not be deleted using &man.pkg.delete.1; unless the |
562 | <quote>-f</quote> option is used.</para> | | 562 | <quote>-f</quote> option is used.</para> |
563 | </sect2> | | 563 | </sect2> |
564 | | | 564 | |
565 | | | 565 | |
566 | <sect2 id="security-handling"> | | 566 | <sect2 id="security-handling"> |
567 | <title>Handling packages with security problems</title> | | 567 | <title>Handling packages with security problems</title> |
568 | | | 568 | |
569 | <para>When a vulnerability is found, this should be noted in | | 569 | <para>When a vulnerability is found, this should be noted in |
570 | <filename>localsrc/security/advisories/pkg-vulnerabilities</filename>. | | 570 | <filename>localsrc/security/advisories/pkg-vulnerabilities</filename>. |
571 | Entries in that file consist of three parts:</para> | | 571 | Entries in that file consist of three parts:</para> |
572 | <itemizedlist> | | 572 | <itemizedlist> |
573 | <listitem><para>package version pattern</para></listitem> | | 573 | <listitem><para>package version pattern</para></listitem> |
574 | <listitem><para>type of vulnerability (please cut'n'paste an existing one where possible)</para></listitem> | | 574 | <listitem><para>type of vulnerability (please cut'n'paste an existing one where possible)</para></listitem> |
575 | <listitem><para>URL providing additional information about the issue</para></listitem> | | 575 | <listitem><para>URL providing additional information about the issue</para></listitem> |
576 | </itemizedlist> | | 576 | </itemizedlist> |
577 | | | 577 | |
578 | <para>For the package version pattern please always use `<' to | | 578 | <para>For the package version pattern please always use `<' to |
579 | mark an upper bound (not `<='!). This will avoid possible | | 579 | mark an upper bound (not `<='!). This will avoid possible |
580 | problems due unrelated <varname>PKGREVISION</varname> bumps not | | 580 | problems due unrelated <varname>PKGREVISION</varname> bumps not |
581 | related to security fixes. Lower bounds can be added too, using | | 581 | related to security fixes. Lower bounds can be added too, using |
582 | '>' or '>='. For example, | | 582 | '>' or '>='. For example, |
583 | <quote><literal>foo>=1<1.2</literal></quote> would mark | | 583 | <quote><literal>foo>=1<1.2</literal></quote> would mark |
584 | versions 1.0 (included) to 1.2 (excluded) of | | 584 | versions 1.0 (included) to 1.2 (excluded) of |
585 | <quote><literal>foo</literal></quote> as affected by the security | | 585 | <quote><literal>foo</literal></quote> as affected by the security |
586 | issue.</para> | | 586 | issue.</para> |
587 | | | 587 | |
588 | <para>Entries should always be added at the bottom of the file.</para> | | 588 | <para>Entries should always be added at the bottom of the file.</para> |
589 | | | 589 | |
590 | <para>When fixing packages, please modify the upper bound of the | | 590 | <para>When fixing packages, please modify the upper bound of the |
591 | corresponding entry. To continue the previous example, if a fix | | 591 | corresponding entry. To continue the previous example, if a fix |
592 | was backported to version 1.1nb2, change the previous pattern to | | 592 | was backported to version 1.1nb2, change the previous pattern to |
593 | <quote><literal>foo>=1<1.1nb2</literal></quote>.</para> | | 593 | <quote><literal>foo>=1<1.1nb2</literal></quote>.</para> |
594 | | | 594 | |
595 | <para>To locally test a package version pattern against a | | 595 | <para>To locally test a package version pattern against a |
596 | <varname>PKGNAME</varname> you can use the <command>pkg_admin | | 596 | <varname>PKGNAME</varname> you can use the <command>pkg_admin |
597 | pmatch</command> command.</para> | | 597 | pmatch</command> command.</para> |
598 | | | 598 | |
599 | <para>The URL should be as permanent as possible and provide as | | 599 | <para>The URL should be as permanent as possible and provide as |
600 | much information about the issue as possible. CVE entries are | | 600 | much information about the issue as possible. CVE entries are |
601 | preferred.</para> | | 601 | preferred.</para> |
602 | | | 602 | |
603 | <para>After committing that file, ask pkgsrc-security@NetBSD.org to | | 603 | <para>After committing that file, ask pkgsrc-security@NetBSD.org to |
604 | update the file on ftp.NetBSD.org.</para> | | 604 | update the file on ftp.NetBSD.org.</para> |
605 | | | 605 | |
606 | <para>After fixing the vulnerability by a patch, its | | 606 | <para>After fixing the vulnerability by a patch, its |
607 | <varname>PKGREVISION</varname> should be increased (this is of | | 607 | <varname>PKGREVISION</varname> should be increased (this is of |
608 | course not necessary if the problem is fixed by using a newer | | 608 | course not necessary if the problem is fixed by using a newer |
609 | release of the software), and the pattern in the | | 609 | release of the software), and the pattern in the |
610 | pkg-vulnerabilities file must be updated.</para> | | 610 | pkg-vulnerabilities file must be updated.</para> |
611 | | | 611 | |
612 | <para>Also, if the fix should be applied to the stable pkgsrc | | 612 | <para>Also, if the fix should be applied to the stable pkgsrc |
613 | branch, be sure to submit a pullup request!</para> | | 613 | branch, be sure to submit a pullup request!</para> |
614 | | | 614 | |
615 | <para>Binary packages already on ftp.NetBSD.org will be handled | | 615 | <para>Binary packages already on ftp.NetBSD.org will be handled |
616 | semi-automatically by a weekly cron job.</para> | | 616 | semi-automatically by a weekly cron job.</para> |
617 | | | 617 | |
618 | <para>In case a security issue is disputed, please contact | | 618 | <para>In case a security issue is disputed, please contact |
619 | pkgsrc-security@NetBSD.org.</para> | | 619 | pkgsrc-security@NetBSD.org.</para> |
620 | </sect2> | | 620 | </sect2> |
621 | | | 621 | |
622 | | | 622 | |
623 | <sect2 id="bumping-pkgrevision"> | | 623 | <sect2 id="bumping-pkgrevision"> |
624 | <title>How to handle incrementing versions when fixing an existing package</title> | | 624 | <title>How to handle incrementing versions when fixing an existing package</title> |
625 | | | 625 | |
626 | <para>When making fixes to an existing package it can be useful | | 626 | <para>When making fixes to an existing package it can be useful |
627 | to change the version number in <varname>PKGNAME</varname>. To | | 627 | to change the version number in <varname>PKGNAME</varname>. To |
628 | avoid conflicting with future versions by the original author, a | | 628 | avoid conflicting with future versions by the original author, a |
629 | <quote>nb1</quote>, <quote>nb2</quote>, ... suffix can be used | | 629 | <quote>nb1</quote>, <quote>nb2</quote>, ... suffix can be used |
630 | on package versions by setting <varname>PKGREVISION=1</varname> | | 630 | on package versions by setting <varname>PKGREVISION=1</varname> |
631 | (2, ...). The <quote>nb</quote> is treated like a | | 631 | (2, ...). The <quote>nb</quote> is treated like a |
632 | <quote>.</quote> by the package tools. e.g.</para> | | 632 | <quote>.</quote> by the package tools. e.g.</para> |
633 | | | 633 | |
634 | <programlisting> | | 634 | <programlisting> |
635 | DISTNAME= foo-17.42 | | 635 | DISTNAME= foo-17.42 |
636 | PKGREVISION= 9 | | 636 | PKGREVISION= 9 |
637 | </programlisting> | | 637 | </programlisting> |
638 | | | 638 | |
639 | <para>will result in a <varname>PKGNAME</varname> of | | 639 | <para>will result in a <varname>PKGNAME</varname> of |
640 | <quote>foo-17.42nb9</quote>. If you want to use the original | | 640 | <quote>foo-17.42nb9</quote>. If you want to use the original |
641 | value of <varname>PKGNAME</varname> without the <quote>nbX</quote> | | 641 | value of <varname>PKGNAME</varname> without the <quote>nbX</quote> |
642 | suffix, e.g. for setting <varname>DIST_SUBDIR</varname>, use | | 642 | suffix, e.g. for setting <varname>DIST_SUBDIR</varname>, use |
643 | <varname>PKGNAME_NOREV</varname>.</para> | | 643 | <varname>PKGNAME_NOREV</varname>.</para> |
644 | | | 644 | |
645 | <para>When a new release of the package is released, the | | 645 | <para>When a new release of the package is released, the |
646 | <varname>PKGREVISION</varname> should be removed, e.g. on a new | | 646 | <varname>PKGREVISION</varname> should be removed, e.g. on a new |
647 | minor release of the above package, things should be like:</para> | | 647 | minor release of the above package, things should be like:</para> |
648 | | | 648 | |
649 | <programlisting> | | 649 | <programlisting> |
650 | DISTNAME= foo-17.43 | | 650 | DISTNAME= foo-17.43 |
651 | </programlisting> | | 651 | </programlisting> |
652 | | | 652 | |
653 | <para><varname>PKGREVISION</varname> should be incremented for any | | 653 | <para><varname>PKGREVISION</varname> should be incremented for any |
654 | non-trivial change in the resulting binary package. Without a | | 654 | non-trivial change in the resulting binary package. Without a |
655 | <varname>PKGREVISION</varname> bump, someone with the previous | | 655 | <varname>PKGREVISION</varname> bump, someone with the previous |
656 | version installed has no way of knowing that their package is out | | 656 | version installed has no way of knowing that their package is out |
657 | of date. Thus, changes without increasing | | 657 | of date. Thus, changes without increasing |
658 | <varname>PKGREVISION</varname> are essentially labeled "this is so | | 658 | <varname>PKGREVISION</varname> are essentially labeled "this is so |
659 | trivial that no reasonable person would want to upgrade", and this | | 659 | trivial that no reasonable person would want to upgrade", and this |
660 | is the rough test for when increasing | | 660 | is the rough test for when increasing |
661 | <varname>PKGREVISION</varname> is appropriate. Examples of | | 661 | <varname>PKGREVISION</varname> is appropriate. Examples of |
662 | changes that do not merit increasing | | 662 | changes that do not merit increasing |
663 | <varname>PKGREVISION</varname> are:</para> | | 663 | <varname>PKGREVISION</varname> are:</para> |
664 | | | 664 | |
665 | <itemizedlist> | | 665 | <itemizedlist> |
666 | | | 666 | |
667 | <listitem><para>Changing <varname>HOMEPAGE</varname>, | | 667 | <listitem><para>Changing <varname>HOMEPAGE</varname>, |
668 | <varname>MAINTAINER</varname>, <varname>OWNER</varname>, or | | 668 | <varname>MAINTAINER</varname>, <varname>OWNER</varname>, or |
669 | comments in Makefile.</para></listitem> | | 669 | comments in Makefile.</para></listitem> |
670 | | | 670 | |
671 | <listitem><para>Changing build variables if the resulting binary | | 671 | <listitem><para>Changing build variables if the resulting binary |
672 | package is the same.</para></listitem> | | 672 | package is the same.</para></listitem> |
673 | | | 673 | |
674 | <listitem><para>Changing | | 674 | <listitem><para>Changing |
675 | <filename>DESCR</filename>.</para></listitem> | | 675 | <filename>DESCR</filename>.</para></listitem> |
676 | | | 676 | |
677 | <listitem><para>Adding <varname>PKG_OPTIONS</varname> if the | | 677 | <listitem><para>Adding <varname>PKG_OPTIONS</varname> if the |
678 | default options don't change.</para></listitem> | | 678 | default options don't change.</para></listitem> |
679 | | | 679 | |
680 | </itemizedlist> | | 680 | </itemizedlist> |
681 | | | 681 | |
682 | <para>Examples of changes that do merit an increase to | | 682 | <para>Examples of changes that do merit an increase to |
683 | <varname>PKGREVISION</varname> include:</para> | | 683 | <varname>PKGREVISION</varname> include:</para> |
684 | | | 684 | |
685 | <itemizedlist> | | 685 | <itemizedlist> |
686 | | | 686 | |
687 | <listitem><para>Security fixes</para></listitem> | | 687 | <listitem><para>Security fixes</para></listitem> |
688 | | | 688 | |
689 | <listitem><para>Changes or additions to a patch | | 689 | <listitem><para>Changes or additions to a patch |
690 | file</para></listitem> | | 690 | file</para></listitem> |
691 | | | 691 | |
692 | <listitem><para>Changes to the | | 692 | <listitem><para>Changes to the |
693 | <filename>PLIST</filename></para></listitem> | | 693 | <filename>PLIST</filename></para></listitem> |
694 | | | 694 | |
695 | <listitem><para>A dependency is changed or | | 695 | <listitem><para>A dependency is changed or |
696 | renamed.</para></listitem> | | 696 | renamed.</para></listitem> |
697 | | | 697 | |
698 | </itemizedlist> | | 698 | </itemizedlist> |
699 | | | 699 | |
700 | <para>PKGREVISION must also be incremented when dependencies have ABI | | 700 | <para>PKGREVISION must also be incremented when dependencies have ABI |
701 | changes.</para> | | 701 | changes.</para> |
702 | </sect2> | | 702 | </sect2> |
703 | | | 703 | |
704 | <sect2 id="fixes.subst"> | | 704 | <sect2 id="fixes.subst"> |
705 | <title>Substituting variable text in the package files (the SUBST framework)</title> | | 705 | <title>Substituting variable text in the package files (the SUBST framework)</title> |
706 | | | 706 | |
707 | <para>When you want to replace the same text in multiple files, or | | 707 | <para>When you want to replace the same text in multiple files, or |
708 | multiple times in the same file, it is cumbersome to maintain a patch | | 708 | multiple times in the same file, it is cumbersome to maintain a patch |
709 | file for this. This is where the SUBST framework steps in. It provides an | | 709 | file for this. This is where the SUBST framework steps in. It provides an |
710 | easy-to-use interface for replacing text in files. It just needs the | | 710 | easy-to-use interface for replacing text in files. It just needs the |
711 | following information:</para> | | 711 | following information:</para> |
712 | | | 712 | |
713 | <itemizedlist> | | 713 | <itemizedlist> |
714 | | | 714 | |
715 | <listitem><para>In which phase of the package build cycle should the | | 715 | <listitem><para>In which phase of the package build cycle should the |
716 | replacement happen?</para></listitem> | | 716 | replacement happen?</para></listitem> |
717 | | | 717 | |
718 | <listitem><para>In which files should the replacement | | 718 | <listitem><para>In which files should the replacement |
719 | happen?</para></listitem> | | 719 | happen?</para></listitem> |
720 | | | 720 | |
721 | <listitem><para>Which text should be replaced with | | 721 | <listitem><para>Which text should be replaced with |
722 | what?</para></listitem> | | 722 | what?</para></listitem> |
723 | | | 723 | |
724 | </itemizedlist> | | 724 | </itemizedlist> |
725 | | | 725 | |
726 | <para>This information is encoded in a block of <varname>SUBST</varname> | | 726 | <para>This information is encoded in a block of <varname>SUBST</varname> |
727 | variables. A minimal example is:</para> | | 727 | variables. A minimal example is:</para> |
728 | | | 728 | |
729 | <programlisting> | | 729 | <programlisting> |
730 | SUBST_CLASSES+= paths | | 730 | SUBST_CLASSES+= paths |
731 | SUBST_STAGE.paths= pre-configure | | 731 | SUBST_STAGE.paths= pre-configure |
732 | SUBST_FILES.paths= src/*.c | | 732 | SUBST_FILES.paths= src/*.c |
733 | SUBST_SED.paths= -e 's,/usr/local,${PREFIX},g' | | 733 | SUBST_SED.paths= -e 's,/usr/local,${PREFIX},g' |
734 | </programlisting> | | 734 | </programlisting> |
735 | | | 735 | |
736 | <para>Translated into English, it means: In the pre-configure stage (that | | 736 | <para>Translated into English, it means: In the pre-configure stage (that |
737 | is, after applying the patches from the patches/ directory and before | | 737 | is, after applying the patches from the patches/ directory and before |
738 | running the configure script and the portability check), replace the text | | 738 | running the configure script and the portability check), replace the text |
739 | <literal>/usr/local</literal> with the content of the variable | | 739 | <literal>/usr/local</literal> with the content of the variable |
740 | <varname>PREFIX</varname>.</para> | | 740 | <varname>PREFIX</varname>.</para> |
741 | | | 741 | |
742 | <para>Each SUBST block starts by appending an identifier to | | 742 | <para>Each SUBST block starts by appending an identifier to |
743 | <varname>SUBST_CLASSES</varname> (note the <literal>+=</literal>). This | | 743 | <varname>SUBST_CLASSES</varname> (note the <literal>+=</literal>). This |
744 | identifier can be chosen freely by the package. If there should ever be | | 744 | identifier can be chosen freely by the package. If there should ever be |
745 | duplicate identifiers, the pkgsrc infrastructure will catch this and fail | | 745 | duplicate identifiers, the pkgsrc infrastructure will catch this and fail |
746 | early, so don't worry about name collisions.</para> | | 746 | early, so don't worry about name collisions.</para> |
747 | | | 747 | |
748 | <para>Except for <varname>SUBST_CLASSES</varname>, all variables in a | | 748 | <para>Except for <varname>SUBST_CLASSES</varname>, all variables in a |
749 | SUBST block are parameterized using this identifier. In the remainder of | | 749 | SUBST block are parameterized using this identifier. In the remainder of |
750 | this section, these parameterized variables are written as | | 750 | this section, these parameterized variables are written as |
751 | <varname>SUBST_STAGE.*</varname>.</para> | | 751 | <varname>SUBST_STAGE.*</varname>.</para> |
752 | | | 752 | |
753 | <programlisting> | | 753 | <programlisting> |
754 | SUBST_CLASSES+= paths | | 754 | SUBST_CLASSES+= paths |
755 | SUBST_STAGE.paths= pre-configure | | 755 | SUBST_STAGE.paths= pre-configure |
756 | SUBST_MESSAGE.paths= Fixing absolute paths. | | 756 | SUBST_MESSAGE.paths= Fixing absolute paths. |
757 | SUBST_FILES.paths= src/*.c | | 757 | SUBST_FILES.paths= src/*.c |
758 | SUBST_FILES.paths+= scripts/*.sh | | 758 | SUBST_FILES.paths+= scripts/*.sh |
759 | SUBST_SED.paths= -e 's,"/usr/local,"${PREFIX},g' | | 759 | SUBST_SED.paths= -e 's,"/usr/local,"${PREFIX},g' |
760 | SUBST_SED.paths+= -e 's,"/var/log,"${VARBASE}/log,g' | | 760 | SUBST_SED.paths+= -e 's,"/var/log,"${VARBASE}/log,g' |
761 | SUBST_VARS.paths= LOCALBASE PREFIX PKGVERSION | | 761 | SUBST_VARS.paths= LOCALBASE PREFIX PKGVERSION |
762 | </programlisting> | | 762 | </programlisting> |
763 | | | 763 | |
764 | <para>To get a complete picture about the SUBST substitutions, run | | 764 | <para>To get a complete picture about the SUBST substitutions, run |
765 | <command>bmake show-all-subst</command>. If something doesn't work as | | 765 | <command>bmake show-all-subst</command>. If something doesn't work as |
766 | expected, run pkglint on the package, which detects several typical | | 766 | expected, run pkglint on the package, which detects several typical |
767 | mistakes surrounding the SUBST blocks. For any questions that might | | 767 | mistakes surrounding the SUBST blocks. For any questions that might |
768 | remain after this, have a look at | | 768 | remain after this, have a look at |
769 | <filename>mk/subst.mk</filename>.</para> | | 769 | <filename>mk/subst.mk</filename>.</para> |
770 | | | 770 | |
771 | <sect3 id="fixes.subst.when"> | | 771 | <sect3 id="fixes.subst.when"> |
772 | <title>Choosing the time where the substitutions happen</title> | | 772 | <title>Choosing the time where the substitutions happen</title> |
773 | | | 773 | |
774 | <para>The <varname>SUBST_STAGE.*</varname> is one of | | 774 | <para>The <varname>SUBST_STAGE.*</varname> is one of |
775 | {pre,do,post}-{extract,patch,configure,build,test,install}. Of these, | | 775 | {pre,do,post}-{extract,patch,configure,build,test,install}. Of these, |
776 | <literal>pre-configure</literal> is used most often, by far. The most | | 776 | <literal>pre-configure</literal> is used most often, by far. The most |
777 | popular stages are, in chronological order:</para> | | 777 | popular stages are, in chronological order:</para> |
778 | | | 778 | |
779 | <variablelist> | | 779 | <variablelist> |
780 | | | 780 | |
781 | <varlistentry><term><literal>post-extract</literal></term> | | 781 | <varlistentry><term><literal>post-extract</literal></term> |
782 | <listitem><para>The substitutions are applied immediately after the | | 782 | <listitem><para>The substitutions are applied immediately after the |
783 | distfiles are extracted. Running <command>bmake extract</command> on the | | 783 | distfiles are extracted. Running <command>bmake extract</command> on the |
784 | package will leave no traces of the original files.</para> | | 784 | package will leave no traces of the original files.</para> |
785 | | | 785 | |
786 | <para>When the substitution applies to files for which there is also a | | 786 | <para>When the substitution applies to files for which there is also a |
787 | patch in the <filename>patches/</filename> directory, this means that the | | 787 | patch in the <filename>patches/</filename> directory, this means that the |
788 | patches will be computed based on the result of the substitution. When | | 788 | patches will be computed based on the result of the substitution. When |
789 | these patches are sent to the upstream maintainer later, to be fixed in | | 789 | these patches are sent to the upstream maintainer later, to be fixed in |
790 | the upstream package, these patches may no longer match what the upstream | | 790 | the upstream package, these patches may no longer match what the upstream |
791 | author is used to. Because of this, <literal>pre-configure</literal> is | | 791 | author is used to. Because of this, <literal>pre-configure</literal> is |
792 | often a better choice.</para></listitem></varlistentry> | | 792 | often a better choice.</para></listitem></varlistentry> |
793 | | | 793 | |
794 | <varlistentry><term><literal>pre-configure</literal></term> | | 794 | <varlistentry><term><literal>pre-configure</literal></term> |
795 | <listitem><para>The substitutions are applied after the patches from the | | 795 | <listitem><para>The substitutions are applied after the patches from the |
796 | <filename>patches/</filename> directory. This makes it possible to run | | 796 | <filename>patches/</filename> directory. This makes it possible to run |
797 | <command>bmake patch</command> on the package, after which the patches | | 797 | <command>bmake patch</command> on the package, after which the patches |
798 | can be edited using the tools pkgvi and mkpatches from the <filename | | 798 | can be edited using the tools pkgvi and mkpatches from the <filename |
799 | role="pkg">pkgtools/pkgdiff</filename> package.</para> | | 799 | role="pkg">pkgtools/pkgdiff</filename> package.</para> |
800 | | | 800 | |
801 | <para>When updating the patches, it is helpful to explicitly separate the | | 801 | <para>When updating the patches, it is helpful to explicitly separate the |
802 | <command>bmake patch</command> from the <command>bmake | | 802 | <command>bmake patch</command> from the <command>bmake |
803 | configure</command>, and to only edit the patches between these commands. | | 803 | configure</command>, and to only edit the patches between these commands. |
804 | Otherwise the substitutions from the SUBST block will end up in the patch | | 804 | Otherwise the substitutions from the SUBST block will end up in the patch |
805 | file. When this happens in really obvious ways, pkglint will complain | | 805 | file. When this happens in really obvious ways, pkglint will complain |
806 | about patches that contain a hard-coded <literal>/usr/pkg</literal> | | 806 | about patches that contain a hard-coded <literal>/usr/pkg</literal> |
807 | instead of the correct and intended <literal>@PREFIX@</literal>, but it | | 807 | instead of the correct and intended <literal>@PREFIX@</literal>, but it |
808 | can only detect these really obvious | | 808 | can only detect these really obvious |
809 | cases.</para></listitem></varlistentry> | | 809 | cases.</para></listitem></varlistentry> |
810 | | | 810 | |
811 | <varlistentry><term><literal>do-configure</literal></term> | | 811 | <varlistentry><term><literal>do-configure</literal></term> |
812 | <listitem><para>This stage should only be used if the package defines a | | 812 | <listitem><para>This stage should only be used if the package defines a |
813 | <literal>pre-configure</literal> action itself, and the substitution must | | 813 | <literal>pre-configure</literal> action itself, and the substitution must |
814 | happen after that. Typical examples are packages that use the | | 814 | happen after that. Typical examples are packages that use the |
815 | <literal>pre-configure</literal> stage to regenerate the GNU configure | | 815 | <literal>pre-configure</literal> stage to regenerate the GNU configure |
816 | script from | | 816 | script from |
817 | <filename>configure.ac</filename>.</para></listitem></varlistentry> | | 817 | <filename>configure.ac</filename>.</para></listitem></varlistentry> |
818 | | | 818 | |
819 | <varlistentry><term><literal>post-configure</literal></term> | | 819 | <varlistentry><term><literal>post-configure</literal></term> |
820 | <listitem><para>This stage is used to fix up any mistakes by the | | 820 | <listitem><para>This stage is used to fix up any mistakes by the |
821 | configure stage.</para></listitem></varlistentry> | | 821 | configure stage.</para></listitem></varlistentry> |
822 | | | 822 | |
823 | <varlistentry><term><literal>pre-build</literal></term> | | 823 | <varlistentry><term><literal>pre-build</literal></term> |
824 | <listitem><para>This stage should only be used for substitutions that are | | 824 | <listitem><para>This stage should only be used for substitutions that are |
825 | clearly related to building the package, not for fixing the | | 825 | clearly related to building the package, not for fixing the |
826 | configuration. Substitutions for pathnames (such as replacing | | 826 | configuration. Substitutions for pathnames (such as replacing |
827 | <filename>/usr/local</filename> with <literal>${PREFIX}</literal>) or | | 827 | <filename>/usr/local</filename> with <literal>${PREFIX}</literal>) or |
828 | user names (such as replacing <literal>@MY_USER@</literal> with the | | 828 | user names (such as replacing <literal>@MY_USER@</literal> with the |
829 | actual username) belong in pre-configure or post-configure | | 829 | actual username) belong in pre-configure or post-configure |
830 | instead.</para></listitem></varlistentry> | | 830 | instead.</para></listitem></varlistentry> |
831 | | | 831 | |
832 | <varlistentry><term><literal>post-build</literal></term> | | 832 | <varlistentry><term><literal>post-build</literal></term> |
833 | <listitem><para>Just as with pre-build, this stage should only be used | | 833 | <listitem><para>Just as with pre-build, this stage should only be used |
834 | for substitutions that are clearly related to building the package, not | | 834 | for substitutions that are clearly related to building the package, not |
835 | for fixing the configuration. Substitutions for pathnames (such as | | 835 | for fixing the configuration. Substitutions for pathnames (such as |
836 | replacing <filename>/usr/local</filename> with | | 836 | replacing <filename>/usr/local</filename> with |
837 | <literal>${PREFIX}</literal>) or user names (such as replacing | | 837 | <literal>${PREFIX}</literal>) or user names (such as replacing |
838 | <literal>@MY_USER@</literal> with the actual username) belong in | | 838 | <literal>@MY_USER@</literal> with the actual username) belong in |
839 | pre-configure or post-configure instead.</para> | | 839 | pre-configure or post-configure instead.</para> |
840 | | | 840 | |
841 | <para>A typical use is to update pkg-config files to include the rpath | | 841 | <para>A typical use is to update pkg-config files to include the rpath |
842 | compiler options.</para></listitem></varlistentry> | | 842 | compiler options.</para></listitem></varlistentry> |
843 | | | 843 | |
844 | <varlistentry><term><literal>pre-install</literal></term> | | 844 | <varlistentry><term><literal>pre-install</literal></term> |
845 | <listitem><para>In general, the install phase should be as simple as | | 845 | <listitem><para>In general, the install phase should be as simple as |
846 | possible. As with the pre-build and post-build stages, it should not be | | 846 | possible. As with the pre-build and post-build stages, it should not be |
847 | used to fix pathnames or user names, these belong in pre-configure | | 847 | used to fix pathnames or user names, these belong in pre-configure |
848 | instead. There are only few legitimate use cases for applying | | 848 | instead. There are only few legitimate use cases for applying |
849 | substitutions in this stage.</para></listitem></varlistentry> | | 849 | substitutions in this stage.</para></listitem></varlistentry> |
850 | | | 850 | |
851 | </variablelist> | | 851 | </variablelist> |
852 | | | 852 | |
853 | </sect3> | | 853 | </sect3> |
854 | | | 854 | |
855 | <sect3 id="fixes.subst.where"> | | 855 | <sect3 id="fixes.subst.where"> |
856 | <title>Choosing the files where the substitutions happen</title> | | 856 | <title>Choosing the files where the substitutions happen</title> |
857 | | | 857 | |
858 | <para>The <varname>SUBST_FILES.*</varname> variable contains a list of | | 858 | <para>The <varname>SUBST_FILES.*</varname> variable contains a list of |
859 | filename patterns. These patterns are relative to | | 859 | filename patterns. These patterns are relative to |
860 | <varname>WRKSRC</varname> since that is where most substitutions happen. | | 860 | <varname>WRKSRC</varname> since that is where most substitutions happen. |
861 | A typical example is:</para> | | 861 | A typical example is:</para> |
862 | | | 862 | |
863 | <programlisting> | | 863 | <programlisting> |
864 | SUBST_FILES.path= Makefile */Makefile */*/Makefile *.[ch] | | 864 | SUBST_FILES.path= Makefile */Makefile */*/Makefile *.[ch] |
865 | </programlisting> | | 865 | </programlisting> |
866 | | | 866 | |
867 | | | 867 | |
868 | <para>The above patterns, especially the last, are quite broad. The SUBST | | 868 | <para>The above patterns, especially the last, are quite broad. The SUBST |
869 | implementation checks that each filename pattern that is mentioned here | | 869 | implementation checks that each filename pattern that is mentioned here |
870 | has an effect. For example, if none of the | | 870 | has an effect. For example, if none of the |
871 | <filename>*/*/Makefile</filename> files contains the patterns to be found | | 871 | <filename>*/*/Makefile</filename> files contains the patterns to be found |
872 | and substituted, that filename pattern is redundant and should be left | | 872 | and substituted, that filename pattern is redundant and should be left |
873 | out. By default, the SUBST framework will complain with an error message. | | 873 | out. By default, the SUBST framework will complain with an error message. |
874 | If the text to be substituted occurs in some of the files from a single | | 874 | If the text to be substituted occurs in some of the files from a single |
875 | pattern, but not in all of them, that is totally ok, and the SUBST | | 875 | pattern, but not in all of them, that is totally ok, and the SUBST |
876 | framework will only print an INFO message for those files.</para> | | 876 | framework will only print an INFO message for those files.</para> |
877 | | | 877 | |
878 | <para>If there is a good reason for having redundant filename patterns, | | 878 | <para>If there is a good reason for having redundant filename patterns, |
879 | set <varname>SUBST_NOOP_OK.*</varname> to <literal>yes</literal>.</para> | | 879 | set <varname>SUBST_NOOP_OK.*</varname> to <literal>yes</literal>.</para> |
880 | | | 880 | |
881 | <para>Another popular way of choosing the files for the substitutions is | | 881 | <para>Another popular way of choosing the files for the substitutions is |
882 | via a shell command, like this:</para> | | 882 | via a shell command, like this:</para> |
883 | | | 883 | |
884 | <programlisting> | | 884 | <programlisting> |
885 | C_FILES_CMD= cd ${WRKSRC} && ${FIND} . -name '*.c' | | 885 | C_FILES_CMD= cd ${WRKSRC} && ${FIND} . -name '*.c' |
886 | SUBST_FILES.path= ${C_FILES_CMD:sh} | | 886 | SUBST_FILES.path= ${C_FILES_CMD:sh} |
887 | </programlisting> | | 887 | </programlisting> |
888 | | | 888 | |
889 | <para>The variable name <varname>C_FILES_CMD</varname> in this example is | | 889 | <para>The variable name <varname>C_FILES_CMD</varname> in this example is |
890 | freely chosen and independent of the SUBST framework.</para> | | 890 | freely chosen and independent of the SUBST framework.</para> |
891 | | | 891 | |
892 | <para>In this variant, the <varname>SUBST_FILES.*</varname> variable | | 892 | <para>In this variant, the <varname>SUBST_FILES.*</varname> variable |
893 | lists each file individually. Thereby chances are higher that there are | | 893 | lists each file individually. Thereby chances are higher that there are |
894 | filename patterns in which no substitution happens. Since the SUBST | | 894 | filename patterns in which no substitution happens. Since the SUBST |
895 | framework cannot know whether the filename patterns in | | 895 | framework cannot know whether the filename patterns in |
896 | <varname>SUBST_FILES.*</varname> have been explicitly listed in the | | 896 | <varname>SUBST_FILES.*</varname> have been explicitly listed in the |
897 | Makefile (where any redundant filename pattern would be suspicious) or | | 897 | Makefile (where any redundant filename pattern would be suspicious) or |
898 | been generated by a shell command (in which redundant filename patterns | | 898 | been generated by a shell command (in which redundant filename patterns |
899 | are more likely and to be expected), it will complain about these | | 899 | are more likely and to be expected), it will complain about these |
900 | redundant filename patterns. Therefore, SUBST blocks that use a shell | | 900 | redundant filename patterns. Therefore, SUBST blocks that use a shell |
901 | command to generate the list of filename patterns often need to set | | 901 | command to generate the list of filename patterns often need to set |
902 | <varname>SUBST_NOOP_OK.*</varname> to <literal>yes</literal>.</para> | | 902 | <varname>SUBST_NOOP_OK.*</varname> to <literal>yes</literal>.</para> |
903 | | | 903 | |
904 | </sect3> | | 904 | </sect3> |
905 | | | 905 | |
906 | <sect3 id="fixes.subst.what"> | | 906 | <sect3 id="fixes.subst.what"> |
907 | <title>Choosing what to substitute</title> | | 907 | <title>Choosing what to substitute</title> |
908 | | | 908 | |
909 | <para>In most cases, the substitutions are given using one or more | | 909 | <para>In most cases, the substitutions are given using one or more |
910 | &man.sed.1; commands, like this:</para> | | 910 | &man.sed.1; commands, like this:</para> |
911 | | | 911 | |
912 | <programlisting> | | 912 | <programlisting> |
913 | SUBST_SED.path= -e 's|/usr/local|${PREFIX}|g' | | 913 | SUBST_SED.path= -e 's|/usr/local|${PREFIX}|g' |
914 | </programlisting> | | 914 | </programlisting> |
915 | | | 915 | |
916 | <para>Each of the sed commands needs to be preceded by the | | 916 | <para>Each of the sed commands needs to be preceded by the |
917 | <literal>-e</literal> option and should be specified on a line of its | | 917 | <literal>-e</literal> option and should be specified on a line of its |
918 | own, to avoid hiding short sed commands at the end of a line.</para> | | 918 | own, to avoid hiding short sed commands at the end of a line.</para> |
919 | | | 919 | |
920 | <para>Since the sed commands often contain shell metacharacters as the | | 920 | <para>Since the sed commands often contain shell metacharacters as the |
921 | separator (the <literal>|</literal> in the above example), it is common | | 921 | separator (the <literal>|</literal> in the above example), it is common |
922 | to enclose them in single quotes.</para> | | 922 | to enclose them in single quotes.</para> |
923 | | | 923 | |
924 | <para>A common substitution is to replace placeholders of the form | | 924 | <para>A common substitution is to replace placeholders of the form |
925 | <literal>@VARNAME@</literal> with their pkgsrc counterpart variable | | 925 | <literal>@VARNAME@</literal> with their pkgsrc counterpart variable |
926 | <literal>${VARNAME}</literal>. A typical example is:</para> | | 926 | <literal>${VARNAME}</literal>. A typical example is:</para> |
927 | | | 927 | |
928 | <programlisting> | | 928 | <programlisting> |
929 | SUBST_VARS.path= PREFIX | | 929 | SUBST_VARS.path= PREFIX |
930 | </programlisting> | | 930 | </programlisting> |
931 | | | 931 | |
932 | <para>This type of substitutions is typically done by the GNU configure | | 932 | <para>This type of substitutions is typically done by the GNU configure |
933 | scripts during the do-configure stage, but in some cases these need to be | | 933 | scripts during the do-configure stage, but in some cases these need to be |
934 | overridden. The same pattern is also used when a package defines patches | | 934 | overridden. The same pattern is also used when a package defines patches |
935 | that replace previously hard-coded paths like | | 935 | that replace previously hard-coded paths like |
936 | <literal>/usr/local</literal> with a <literal>@PREFIX@</literal> | | 936 | <literal>/usr/local</literal> with a <literal>@PREFIX@</literal> |
937 | placeholder first, which then gets substituted by the actual | | 937 | placeholder first, which then gets substituted by the actual |
938 | <literal>${PREFIX}</literal> in the pre-configure stage. In many of these | | 938 | <literal>${PREFIX}</literal> in the pre-configure stage. In many of these |
939 | cases, it works equally well to just use the SUBST framework to directly | | 939 | cases, it works equally well to just use the SUBST framework to directly |
940 | replace <literal>/usr/local</literal> with <literal>${PREFIX}</literal>, | | 940 | replace <literal>/usr/local</literal> with <literal>${PREFIX}</literal>, |
941 | thereby omitting the intermediate patch file.</para> | | 941 | thereby omitting the intermediate patch file.</para> |
942 | | | 942 | |
943 | <para>If the above is not flexible enough, it is possible to not use sed | | 943 | <para>If the above is not flexible enough, it is possible to not use sed |
944 | at all for the substitution but to specify an entirely different command, | | 944 | at all for the substitution but to specify an entirely different command, |
945 | like this:</para> | | 945 | like this:</para> |
946 | | | 946 | |
947 | <programlisting> | | 947 | <programlisting> |
948 | SUBST_FILTER_CMD.path= LC_ALL=C ${TR} -d '\r' | | 948 | SUBST_FILTER_CMD.path= LC_ALL=C ${TR} -d '\r' |
949 | </programlisting> | | 949 | </programlisting> |
950 | | | 950 | |
951 | <para>This is used for the few remaining packages in which the | | 951 | <para>This is used for the few remaining packages in which the |
952 | distributed files use Windows-style line endings that need to be | | 952 | distributed files use Windows-style line endings that need to be |
953 | converted to UNIX-style line endings.</para> | | 953 | converted to UNIX-style line endings.</para> |
954 | | | 954 | |
955 | </sect3> | | 955 | </sect3> |
956 | | | 956 | |
957 | <sect3 id="fixes.subst.other"> | | 957 | <sect3 id="fixes.subst.other"> |
958 | <title>Other SUBST variables</title> | | 958 | <title>Other SUBST variables</title> |
959 | | | 959 | |
960 | <para>When a SUBST block is applied during a package build, a message is | | 960 | <para>When a SUBST block is applied during a package build, a message is |
961 | logged. The default message is fine for most purposes but can be | | 961 | logged. The default message is fine for most purposes but can be |
962 | overridden by setting <literal>SUBST_MESSAGE.*</literal> to an individual | | 962 | overridden by setting <literal>SUBST_MESSAGE.*</literal> to an individual |
963 | message.</para> | | 963 | message.</para> |
964 | | | 964 | |
965 | </sect3> | | 965 | </sect3> |
966 | | | 966 | |
967 | </sect2> | | 967 | </sect2> |
968 | | | 968 | |
969 | </sect1> | | 969 | </sect1> |
970 | | | 970 | |
971 | <sect1 id="fixes.fetch"> | | 971 | <sect1 id="fixes.fetch"> |
972 | <title>The <emphasis>fetch</emphasis> phase</title> | | 972 | <title>The <emphasis>fetch</emphasis> phase</title> |
973 | | | 973 | |
974 | <sect2 id="no-plain-download"> | | 974 | <sect2 id="no-plain-download"> |
975 | <title>Packages whose distfiles aren't available for plain downloading</title> | | 975 | <title>Packages whose distfiles aren't available for plain downloading</title> |
976 | | | 976 | |
977 | <para>If you need to download from a dynamic URL you can set | | 977 | <para>If you need to download from a dynamic URL you can set |
978 | <varname>DYNAMIC_MASTER_SITES</varname> and a <command>make | | 978 | <varname>DYNAMIC_MASTER_SITES</varname> and a <command>make |
979 | fetch</command> will call <filename>files/getsite.sh</filename> | | 979 | fetch</command> will call <filename>files/getsite.sh</filename> |
980 | with the name of each file to download as an argument, expecting | | 980 | with the name of each file to download as an argument, expecting |
981 | it to output the URL of the directory from which to download | | 981 | it to output the URL of the directory from which to download |
982 | it. <filename role="pkg">graphics/ns-cult3d</filename> is an | | 982 | it. <filename role="pkg">graphics/ns-cult3d</filename> is an |
983 | example of this usage.</para> | | 983 | example of this usage.</para> |
984 | | | 984 | |
985 | <para>If the download can't be automated, because the user must | | 985 | <para>If the download can't be automated, because the user must |
986 | submit personal information to apply for a password, or must pay | | 986 | submit personal information to apply for a password, or must pay |
987 | for the source, or whatever, you can set | | 987 | for the source, or whatever, you can set |
988 | <varname>FETCH_MESSAGE</varname> to a list of lines that are | | 988 | <varname>FETCH_MESSAGE</varname> to a list of lines that are |
989 | displayed to the user before aborting the build. Example:</para> | | 989 | displayed to the user before aborting the build. Example:</para> |
990 | | | 990 | |
991 | <programlisting> | | 991 | <programlisting> |
992 | FETCH_MESSAGE= "Please download the files" | | 992 | FETCH_MESSAGE= "Please download the files" |
993 | FETCH_MESSAGE+= " "${DISTFILES:Q} | | 993 | FETCH_MESSAGE+= " "${DISTFILES:Q} |
994 | FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"." | | 994 | FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"." |
995 | </programlisting> | | 995 | </programlisting> |
996 | | | 996 | |
997 | </sect2> | | 997 | </sect2> |
998 | | | 998 | |
999 | | | 999 | |
1000 | <sect2 id="modified-distfiles-same-name"> | | 1000 | <sect2 id="modified-distfiles-same-name"> |
1001 | <title>How to handle modified distfiles with the 'old' name</title> | | 1001 | <title>How to handle modified distfiles with the 'old' name</title> |
1002 | | | 1002 | |
1003 | <para>Sometimes authors of a software package make some | | 1003 | <para>Sometimes authors of a software package make some |
1004 | modifications after the software was released, and they put up a | | 1004 | modifications after the software was released, and they put up a |
1005 | new distfile without changing the package's version number. If a | | 1005 | new distfile without changing the package's version number. If a |
1006 | package is already in pkgsrc at that time, the checksum will | | 1006 | package is already in pkgsrc at that time, the checksum will |
1007 | no longer match. The contents of the new distfile should be | | 1007 | no longer match. The contents of the new distfile should be |
1008 | compared against the old one before changing anything, to make | | 1008 | compared against the old one before changing anything, to make |
1009 | sure the distfile was really updated on purpose, and that | | 1009 | sure the distfile was really updated on purpose, and that |
1010 | no trojan horse or so crept in. | | 1010 | no trojan horse or so crept in. |
1011 | Please mention that the distfiles were compared and what was found | | 1011 | Please mention that the distfiles were compared and what was found |
1012 | in your commit message.</para> | | 1012 | in your commit message.</para> |
1013 | <para>Then, the correct way to work around this is to set | | 1013 | <para>Then, the correct way to work around this is to set |
1014 | <varname>DIST_SUBDIR</varname> to a unique directory name, usually | | 1014 | <varname>DIST_SUBDIR</varname> to a unique directory name, usually |
1015 | based on <varname>PKGNAME_NOREV</varname> (but take care with | | 1015 | based on <varname>PKGNAME_NOREV</varname> (but take care with |
1016 | python or ruby packages, where <varname>PKGNAME</varname> includes | | 1016 | python or ruby packages, where <varname>PKGNAME</varname> includes |
1017 | a variable prefix). All <varname>DISTFILES</varname> and | | 1017 | a variable prefix). All <varname>DISTFILES</varname> and |
1018 | <varname>PATCHFILES</varname> for this package will be put in that | | 1018 | <varname>PATCHFILES</varname> for this package will be put in that |
1019 | subdirectory of the local distfiles directory. (See <xref | | 1019 | subdirectory of the local distfiles directory. (See <xref |
1020 | linkend="bumping-pkgrevision"/> for more details.) In case this | | 1020 | linkend="bumping-pkgrevision"/> for more details.) In case this |
1021 | happens more often, <varname>PKGNAME</varname> can be used (thus | | 1021 | happens more often, <varname>PKGNAME</varname> can be used (thus |
1022 | including the <filename>nbX</filename> suffix) or a date stamp can | | 1022 | including the <filename>nbX</filename> suffix) or a date stamp can |
1023 | be appended, like | | 1023 | be appended, like |
1024 | <varname>${PKGNAME_NOREV}-YYYYMMDD</varname>.</para> | | 1024 | <varname>${PKGNAME_NOREV}-YYYYMMDD</varname>.</para> |
1025 | | | 1025 | |
1026 | <para><varname>DIST_SUBDIR</varname> is also used when a distfile's | | 1026 | <para><varname>DIST_SUBDIR</varname> is also used when a distfile's |
1027 | name does not contain a version and the distfile is apt to change. In | | 1027 | name does not contain a version and the distfile is apt to change. In |
1028 | cases where the likelihood of this is very small, | | 1028 | cases where the likelihood of this is very small, |
1029 | <varname>DIST_SUBDIR</varname> might not be required. Additionally, | | 1029 | <varname>DIST_SUBDIR</varname> might not be required. Additionally, |
1030 | <varname>DIST_SUBDIR</varname> must not be removed unless the | | 1030 | <varname>DIST_SUBDIR</varname> must not be removed unless the |
1031 | distfile name changes, even if a package is being moved or | | 1031 | distfile name changes, even if a package is being moved or |
1032 | renamed.</para> | | 1032 | renamed.</para> |
1033 | | | 1033 | |
1034 | <para>Do not forget regenerating the <filename>distinfo</filename> file | | 1034 | <para>Do not forget regenerating the <filename>distinfo</filename> file |
1035 | after that, since it contains the <varname>DIST_SUBDIR</varname> | | 1035 | after that, since it contains the <varname>DIST_SUBDIR</varname> |
1036 | path in the filenames. | | 1036 | path in the filenames. |
1037 | Also, increase the PKGREVISION if the installed package is different. | | 1037 | Also, increase the PKGREVISION if the installed package is different. |
1038 | Furthermore, a mail to the package's authors seems appropriate | | 1038 | Furthermore, a mail to the package's authors seems appropriate |
1039 | telling them that changing distfiles after releases without | | 1039 | telling them that changing distfiles after releases without |
1040 | changing the file names is not good practice.</para> | | 1040 | changing the file names is not good practice.</para> |
1041 | </sect2> | | 1041 | </sect2> |
1042 | | | 1042 | |
1043 | <sect2 id="build.fetch.github"> | | 1043 | <sect2 id="build.fetch.github"> |
1044 | <title>Packages hosted on github.com</title> | | 1044 | <title>Packages hosted on github.com</title> |
1045 | | | 1045 | |
1046 | <para>Helper methods exist for packages hosted on github.com which | | 1046 | <para>Helper methods exist for packages hosted on github.com which |
1047 | will often have distfile names that clash with other packages, for | | 1047 | will often have distfile names that clash with other packages, for |
1048 | example <filename>1.0.tar.gz</filename>. Use one of the three recipes | | 1048 | example <filename>1.0.tar.gz</filename>. Use one of the three recipes |
1049 | from below:</para> | | 1049 | from below:</para> |
1050 | | | 1050 | |
1051 | <sect3 id="build.fetch.github.tag"> | | 1051 | <sect3 id="build.fetch.github.tag"> |
1052 | <title>Fetch based on a tagged release</title> | | 1052 | <title>Fetch based on a tagged release</title> |
1053 | | | 1053 | |
1054 | <para>If your distfile URL looks similar to | | 1054 | <para>If your distfile URL looks similar to |
1055 | <literal>https://github.com/username/example/archive/v1.0.zip</literal>, | | 1055 | <literal>https://github.com/username/example/archive/v1.0.zip</literal>, |
1056 | then you are packaging a tagged release.</para> | | 1056 | then you are packaging a tagged release.</para> |
1057 | | | 1057 | |
1058 | <programlisting> | | 1058 | <programlisting> |
1059 | DISTNAME= example-1.0 | | 1059 | DISTNAME= example-1.0 |
1060 | MASTER_SITES= ${MASTER_SITE_GITHUB:=username/} | | 1060 | MASTER_SITES= ${MASTER_SITE_GITHUB:=username/} |
1061 | #GITHUB_PROJECT= example # can be omitted if same as DISTNAME | | 1061 | #GITHUB_PROJECT= example # can be omitted if same as DISTNAME |
1062 | GITHUB_TAG= v${PKGVERSION_NOREV} | | 1062 | GITHUB_TAG= v${PKGVERSION_NOREV} |
1063 | EXTRACT_SUFX= .zip | | 1063 | EXTRACT_SUFX= .zip |
1064 | </programlisting> | | 1064 | </programlisting> |
1065 | | | 1065 | |
1066 | <para>Here, DISTNAME combined with use of GITHUB_TAG leads the | | 1066 | <para>Here, DISTNAME combined with use of GITHUB_TAG leads the |
1067 | file fetching infrastructure to save the resulting file locally as | | 1067 | file fetching infrastructure to save the resulting file locally as |
1068 | <literal>example-1.0.zip</literal>.</para> | | 1068 | <literal>example-1.0.zip</literal>.</para> |
1069 | | | 1069 | |
1070 | </sect3> | | 1070 | </sect3> |
1071 | | | 1071 | |
1072 | <sect3 id="build.fetch.github.commit.prerelease"> | | 1072 | <sect3 id="build.fetch.github.commit.prerelease"> |
1073 | <title>Fetch based on a specific commit before the first release</title> | | 1073 | <title>Fetch based on a specific commit before the first release</title> |
1074 | | | 1074 | |
1075 | <para>If your distfile looks similar to | | 1075 | <para>If your distfile looks similar to |
1076 | <literal>https://github.com/username/example/archive/988881adc9fc3655077dc2d4d757d480b5ea0e11</literal> and is from a commit before the first | | 1076 | <literal>https://github.com/username/example/archive/988881adc9fc3655077dc2d4d757d480b5ea0e11</literal> and is from a commit before the first |
1077 | release, then set the package version to 0.0.0.N, where N is the number | | 1077 | release, then set the package version to 0.0.0.N, where N is the number |
1078 | of commits to the repository, and set GITHUB_TAG to the commit hash. | | 1078 | of commits to the repository, and set GITHUB_TAG to the commit hash. |
1079 | This will (almost) ensure that the first tagged release will have a | | 1079 | This will (almost) ensure that the first tagged release will have a |
1080 | version greater than this one so that package upgrades will function | | 1080 | version greater than this one so that package upgrades will function |
1081 | properly.</para> | | 1081 | properly.</para> |
1082 | | | 1082 | |
1083 | <programlisting> | | 1083 | <programlisting> |
1084 | DISTNAME= example-0.0.0.347 | | 1084 | DISTNAME= example-0.0.0.347 |
1085 | MASTER_SITES= ${MASTER_SITE_GITHUB:=username/} | | 1085 | MASTER_SITES= ${MASTER_SITE_GITHUB:=username/} |
1086 | #GITHUB_PROJECT= example # can be omitted if same as DISTNAME | | 1086 | #GITHUB_PROJECT= example # can be omitted if same as DISTNAME |
1087 | GITHUB_TAG= 988881adc9fc3655077dc2d4d757d480b5ea0e11 | | 1087 | GITHUB_TAG= 988881adc9fc3655077dc2d4d757d480b5ea0e11 |
1088 | </programlisting> | | 1088 | </programlisting> |
1089 | </sect3> | | 1089 | </sect3> |
1090 | | | 1090 | |
1091 | <sect3 id="build.fetch.github.commit.postrelease"> | | 1091 | <sect3 id="build.fetch.github.commit.postrelease"> |
1092 | <title>Fetch based on a specific commit after a release</title> | | 1092 | <title>Fetch based on a specific commit after a release</title> |
1093 | | | 1093 | |
1094 | <para>If your distfile looks similar to | | 1094 | <para>If your distfile looks similar to |
1095 | <literal>https://github.com/username/example/archive/988881adc9fc3655077dc2d4d757d480b5ea0e11</literal> and is from a commit after a release, | | 1095 | <literal>https://github.com/username/example/archive/988881adc9fc3655077dc2d4d757d480b5ea0e11</literal> and is from a commit after a release, |
1096 | then include the last release version and the commit count since that | | 1096 | then include the last release version and the commit count since that |
1097 | release in the package version and set GITHUB_TAG to the commit hash. | | 1097 | release in the package version and set GITHUB_TAG to the commit hash. |
1098 | The latest release and commit count are shown in the output of | | 1098 | The latest release and commit count are shown in the output of |
1099 | "git describe --tags": | | 1099 | "git describe --tags": |
1100 | </para> | | 1100 | </para> |
1101 | | | 1101 | |
1102 | <screen> | | 1102 | <screen> |
1103 | # git clone https://github.com/username/example | | 1103 | # git clone https://github.com/username/example |
1104 | # cd example | | 1104 | # cd example |
1105 | # git describe --tags | | 1105 | # git describe --tags |
1106 | 1.2.3-5-g988881a | | 1106 | 1.2.3-5-g988881a |
1107 | </screen> | | 1107 | </screen> |
1108 | | | 1108 | |
1109 | <programlisting> | | 1109 | <programlisting> |
1110 | DISTNAME= example-1.2.3.5 | | 1110 | DISTNAME= example-1.2.3.5 |
1111 | MASTER_SITES= ${MASTER_SITE_GITHUB:=username/} | | 1111 | MASTER_SITES= ${MASTER_SITE_GITHUB:=username/} |
1112 | #GITHUB_PROJECT= example # can be omitted if same as DISTNAME | | 1112 | #GITHUB_PROJECT= example # can be omitted if same as DISTNAME |
1113 | GITHUB_TAG= 988881adc9fc3655077dc2d4d757d480b5ea0e11 | | 1113 | GITHUB_TAG= 988881adc9fc3655077dc2d4d757d480b5ea0e11 |
1114 | </programlisting> | | 1114 | </programlisting> |
1115 | </sect3> | | 1115 | </sect3> |
1116 | | | 1116 | |
1117 | <sect3 id="build.fetch.github.release"> | | 1117 | <sect3 id="build.fetch.github.release"> |
1118 | <title>Fetch based on release</title> | | 1118 | <title>Fetch based on release</title> |
1119 | | | 1119 | |
1120 | <para>If your distfile URL looks similar to | | 1120 | <para>If your distfile URL looks similar to |
1121 | <literal>https://github.com/username/example/releases/download/rel-1.6/offensive-1.6.zip</literal>, | | 1121 | <literal>https://github.com/username/example/releases/download/rel-1.6/offensive-1.6.zip</literal>, |
1122 | then you are packaging a release.</para> | | 1122 | then you are packaging a release.</para> |
1123 | | | 1123 | |
1124 | <programlisting> | | 1124 | <programlisting> |
1125 | DISTNAME= offensive-1.6 | | 1125 | DISTNAME= offensive-1.6 |
1126 | PKGNAME= ${DISTNAME:S/offensive/proper/} | | 1126 | PKGNAME= ${DISTNAME:S/offensive/proper/} |
1127 | MASTER_SITES= ${MASTER_SITE_GITHUB:=username/} | | 1127 | MASTER_SITES= ${MASTER_SITE_GITHUB:=username/} |
1128 | GITHUB_PROJECT= example | | 1128 | GITHUB_PROJECT= example |
1129 | GITHUB_RELEASE= rel-${PKGVERSION_NOREV} # usually just set this to ${DISTNAME} | | 1129 | GITHUB_RELEASE= rel-${PKGVERSION_NOREV} # usually just set this to ${DISTNAME} |
1130 | EXTRACT_SUFX= .zip | | 1130 | EXTRACT_SUFX= .zip |
1131 | </programlisting> | | 1131 | </programlisting> |
1132 | </sect3> | | 1132 | </sect3> |
1133 | </sect2> | | 1133 | </sect2> |
1134 | </sect1> | | 1134 | </sect1> |
1135 | | | 1135 | |
1136 | | | 1136 | |
1137 | <sect1 id="fixes.configure"> | | 1137 | <sect1 id="fixes.configure"> |
1138 | <title>The <emphasis>configure</emphasis> phase</title> | | 1138 | <title>The <emphasis>configure</emphasis> phase</title> |
1139 | | | 1139 | |
1140 | <sect2 id="fixes.libtool"> | | 1140 | <sect2 id="fixes.libtool"> |
1141 | <title>Shared libraries - libtool</title> | | 1141 | <title>Shared libraries - libtool</title> |
1142 | | | 1142 | |
1143 | <para>pkgsrc supports many different machines, with different | | 1143 | <para>pkgsrc supports many different machines, with different |
1144 | object formats like a.out and ELF, and varying abilities to do | | 1144 | object formats like a.out and ELF, and varying abilities to do |
1145 | shared library and dynamic loading at all. To accompany this, | | 1145 | shared library and dynamic loading at all. To accompany this, |
1146 | varying commands and options have to be passed to the | | 1146 | varying commands and options have to be passed to the |
1147 | compiler, linker, etc. to get the Right Thing, which can be | | 1147 | compiler, linker, etc. to get the Right Thing, which can be |
1148 | pretty annoying especially if you don't have all the machines | | 1148 | pretty annoying especially if you don't have all the machines |
1149 | at your hand to test things. The | | 1149 | at your hand to test things. The |
1150 | <filename role="pkg">devel/libtool</filename> pkg | | 1150 | <filename role="pkg">devel/libtool</filename> pkg |
1151 | can help here, as it just <quote>knows</quote> how to build | | 1151 | can help here, as it just <quote>knows</quote> how to build |
1152 | both static and dynamic libraries from a set of source files, | | 1152 | both static and dynamic libraries from a set of source files, |
1153 | thus being platform-independent.</para> | | 1153 | thus being platform-independent.</para> |
1154 | | | 1154 | |
1155 | <para>Here's how to use libtool in a package in seven simple | | 1155 | <para>Here's how to use libtool in a package in seven simple |
1156 | steps:</para> | | 1156 | steps:</para> |
1157 | | | 1157 | |
1158 | <orderedlist> | | 1158 | <orderedlist> |
1159 | <listitem> | | 1159 | <listitem> |
1160 | <para>Add <varname>USE_LIBTOOL=yes</varname> to the package | | 1160 | <para>Add <varname>USE_LIBTOOL=yes</varname> to the package |
1161 | Makefile.</para> | | 1161 | Makefile.</para> |
1162 | </listitem> | | 1162 | </listitem> |
1163 | | | 1163 | |
1164 | <listitem> | | 1164 | <listitem> |
1165 | <para>For library objects, use <quote>${LIBTOOL} --mode=compile | | 1165 | <para>For library objects, use <quote>${LIBTOOL} --mode=compile |
1166 | ${CC}</quote> in place of <quote>${CC}</quote>. You could even | | 1166 | ${CC}</quote> in place of <quote>${CC}</quote>. You could even |
1167 | add it to the definition of <varname>CC</varname>, if only | | 1167 | add it to the definition of <varname>CC</varname>, if only |
1168 | libraries are being built in a given Makefile. This one command | | 1168 | libraries are being built in a given Makefile. This one command |
1169 | will build both PIC and non-PIC library objects, so you need not | | 1169 | will build both PIC and non-PIC library objects, so you need not |
1170 | have separate shared and non-shared library rules.</para> | | 1170 | have separate shared and non-shared library rules.</para> |
1171 | </listitem> | | 1171 | </listitem> |
1172 | | | 1172 | |
1173 | <listitem> | | 1173 | <listitem> |
1174 | <para>For the linking of the library, remove any | | 1174 | <para>For the linking of the library, remove any |
1175 | <quote>ar</quote>, <quote>ranlib</quote>, and <quote>ld | | 1175 | <quote>ar</quote>, <quote>ranlib</quote>, and <quote>ld |
1176 | -Bshareable</quote> commands, and instead use:</para> | | 1176 | -Bshareable</quote> commands, and instead use:</para> |
1177 | | | 1177 | |
1178 | <programlisting> | | 1178 | <programlisting> |
1179 | ${LIBTOOL} --mode=link \ | | 1179 | ${LIBTOOL} --mode=link \ |
1180 | ${CC} -o ${.TARGET:.a=.la} \ | | 1180 | ${CC} -o ${.TARGET:.a=.la} \ |
1181 | ${OBJS:.o=.lo} \ | | 1181 | ${OBJS:.o=.lo} \ |
1182 | -rpath ${PREFIX}/lib \ | | 1182 | -rpath ${PREFIX}/lib \ |
1183 | -version-info major:minor | | 1183 | -version-info major:minor |
1184 | </programlisting> | | 1184 | </programlisting> |
1185 | | | 1185 | |
1186 | <para>Note that the library is changed to have a | | 1186 | <para>Note that the library is changed to have a |
1187 | <filename>.la</filename> extension, and the objects are | | 1187 | <filename>.la</filename> extension, and the objects are |
1188 | changed to have a <filename>.lo</filename> | | 1188 | changed to have a <filename>.lo</filename> |
1189 | extension. Change <varname>OBJS</varname> as | | 1189 | extension. Change <varname>OBJS</varname> as |
1190 | necessary. This automatically creates all of the | | 1190 | necessary. This automatically creates all of the |
1191 | <filename>.a</filename>, | | 1191 | <filename>.a</filename>, |
1192 | <filename>.so.major.minor</filename>, and ELF symlinks (if | | 1192 | <filename>.so.major.minor</filename>, and ELF symlinks (if |
1193 | necessary) in the build directory. Be sure to include | | 1193 | necessary) in the build directory. Be sure to include |
1194 | <quote>-version-info</quote>, especially when major and | | 1194 | <quote>-version-info</quote>, especially when major and |
1195 | minor are zero, as libtool will otherwise strip off the | | 1195 | minor are zero, as libtool will otherwise strip off the |
1196 | shared library version.</para> | | 1196 | shared library version.</para> |
1197 | | | 1197 | |
1198 | <para>From the libtool manual:</para> | | 1198 | <para>From the libtool manual:</para> |
1199 | | | 1199 | |
1200 | <programlisting> | | 1200 | <programlisting> |
1201 | So, libtool library versions are described by three integers: | | 1201 | So, libtool library versions are described by three integers: |
1202 | | | 1202 | |
1203 | CURRENT | | 1203 | CURRENT |
1204 | The most recent interface number that this library implements. | | 1204 | The most recent interface number that this library implements. |
1205 | | | 1205 | |
1206 | REVISION | | 1206 | REVISION |
1207 | The implementation number of the CURRENT interface. | | 1207 | The implementation number of the CURRENT interface. |
1208 | | | 1208 | |
1209 | AGE | | 1209 | AGE |
1210 | The difference between the newest and oldest interfaces that | | 1210 | The difference between the newest and oldest interfaces that |
1211 | this library implements. In other words, the library implements | | 1211 | this library implements. In other words, the library implements |
1212 | all the interface numbers in the range from number `CURRENT - | | 1212 | all the interface numbers in the range from number `CURRENT - |
1213 | AGE' to `CURRENT'. | | 1213 | AGE' to `CURRENT'. |
1214 | | | 1214 | |
1215 | If two libraries have identical CURRENT and AGE numbers, then the | | 1215 | If two libraries have identical CURRENT and AGE numbers, then the |
1216 | dynamic linker chooses the library with the greater REVISION number. | | 1216 | dynamic linker chooses the library with the greater REVISION number. |
1217 | </programlisting> | | 1217 | </programlisting> |
1218 | | | 1218 | |
1219 | <para>The <quote>-release</quote> option will produce | | 1219 | <para>The <quote>-release</quote> option will produce |
1220 | different results for a.out and ELF (excluding symlinks) | | 1220 | different results for a.out and ELF (excluding symlinks) |
1221 | in only one case. An ELF library of the form | | 1221 | in only one case. An ELF library of the form |
1222 | <quote>libfoo-release.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> | | 1222 | <quote>libfoo-release.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> |
1223 | will have a symlink of | | 1223 | will have a symlink of |
1224 | <quote>libfoo.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> | | 1224 | <quote>libfoo.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> |
1225 | on an a.out platform. This is handled | | 1225 | on an a.out platform. This is handled |
1226 | automatically.</para> | | 1226 | automatically.</para> |
1227 | | | 1227 | |
1228 | <para>The <quote>-rpath argument</quote> is the install | | 1228 | <para>The <quote>-rpath argument</quote> is the install |
1229 | directory of the library being built.</para> | | 1229 | directory of the library being built.</para> |
1230 | | | 1230 | |
1231 | <para>In the <filename>PLIST</filename>, include only the | | 1231 | <para>In the <filename>PLIST</filename>, include only the |
1232 | <filename>.la</filename> file, the other files will be | | 1232 | <filename>.la</filename> file, the other files will be |
1233 | added automatically.</para> | | 1233 | added automatically.</para> |
1234 | </listitem> | | 1234 | </listitem> |
1235 | | | 1235 | |
1236 | <listitem> | | 1236 | <listitem> |
1237 | <para>When linking shared object (<filename>.so</filename>) | | 1237 | <para>When linking shared object (<filename>.so</filename>) |
1238 | files, i.e. files that are loaded via &man.dlopen.3;, NOT | | 1238 | files, i.e. files that are loaded via &man.dlopen.3;, NOT |
1239 | shared libraries, use <quote>-module | | 1239 | shared libraries, use <quote>-module |
1240 | -avoid-version</quote> to prevent them getting version | | 1240 | -avoid-version</quote> to prevent them getting version |
1241 | tacked on.</para> | | 1241 | tacked on.</para> |
1242 | | | 1242 | |
1243 | <para>The <filename>PLIST</filename> file gets the | | 1243 | <para>The <filename>PLIST</filename> file gets the |
1244 | <filename>foo.so</filename> entry.</para> | | 1244 | <filename>foo.so</filename> entry.</para> |
1245 | </listitem> | | 1245 | </listitem> |
1246 | | | 1246 | |
1247 | <listitem> | | 1247 | <listitem> |
1248 | <para>When linking programs that depend on these libraries | | 1248 | <para>When linking programs that depend on these libraries |
1249 | <emphasis>before</emphasis> they are installed, preface | | 1249 | <emphasis>before</emphasis> they are installed, preface |
1250 | the &man.cc.1; or &man.ld.1; line with <quote>${LIBTOOL} | | 1250 | the &man.cc.1; or &man.ld.1; line with <quote>${LIBTOOL} |
1251 | --mode=link</quote>, and it will find the correct | | 1251 | --mode=link</quote>, and it will find the correct |
1252 | libraries (static or shared), but please be aware that | | 1252 | libraries (static or shared), but please be aware that |
1253 | libtool will not allow you to specify a relative path in | | 1253 | libtool will not allow you to specify a relative path in |
1254 | -L (such as <quote>-L../somelib</quote>), because it | | 1254 | -L (such as <quote>-L../somelib</quote>), because it |
1255 | expects you to change that argument to be the | | 1255 | expects you to change that argument to be the |
1256 | <filename>.la</filename> file. e.g.</para> | | 1256 | <filename>.la</filename> file. e.g.</para> |
1257 | | | 1257 | |
1258 | <programlisting> | | 1258 | <programlisting> |
1259 | ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib | | 1259 | ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib |
1260 | </programlisting> | | 1260 | </programlisting> |
1261 | | | 1261 | |
1262 | <para>should be changed to:</para> | | 1262 | <para>should be changed to:</para> |
1263 | | | 1263 | |
1264 | <programlisting> | | 1264 | <programlisting> |
1265 | ${LIBTOOL} --mode=link ${CC} -o <replaceable>someprog</replaceable> <replaceable>../somelib/somelib.la</replaceable> | | 1265 | ${LIBTOOL} --mode=link ${CC} -o <replaceable>someprog</replaceable> <replaceable>../somelib/somelib.la</replaceable> |
1266 | </programlisting> | | 1266 | </programlisting> |
1267 | | | 1267 | |
1268 | <para>and it will do the right thing with the libraries.</para> | | 1268 | <para>and it will do the right thing with the libraries.</para> |
1269 | </listitem> | | 1269 | </listitem> |
1270 | | | 1270 | |
1271 | <listitem> | | 1271 | <listitem> |
1272 | <para>When installing libraries, preface the &man.install.1; | | 1272 | <para>When installing libraries, preface the &man.install.1; |
1273 | or &man.cp.1; command with <quote>${LIBTOOL} | | 1273 | or &man.cp.1; command with <quote>${LIBTOOL} |
1274 | --mode=install</quote>, and change the library name to | | 1274 | --mode=install</quote>, and change the library name to |
1275 | <filename>.la</filename>. e.g.</para> | | 1275 | <filename>.la</filename>. e.g.</para> |
1276 | | | 1276 | |
1277 | <programlisting> | | 1277 | <programlisting> |
1278 | ${LIBTOOL} --mode=install ${BSD_INSTALL_LIB} ${SOMELIB:.a=.la} ${PREFIX}/lib | | 1278 | ${LIBTOOL} --mode=install ${BSD_INSTALL_LIB} ${SOMELIB:.a=.la} ${PREFIX}/lib |
1279 | </programlisting> | | 1279 | </programlisting> |
1280 | | | 1280 | |
1281 | <para>This will install the static <filename>.a</filename>, | | 1281 | <para>This will install the static <filename>.a</filename>, |
1282 | shared library, any needed symlinks, and run | | 1282 | shared library, any needed symlinks, and run |
1283 | &man.ldconfig.8;.</para> | | 1283 | &man.ldconfig.8;.</para> |
1284 | </listitem> | | 1284 | </listitem> |
1285 | | | 1285 | |
1286 | <listitem> | | 1286 | <listitem> |
1287 | <para>In your <filename>PLIST</filename>, include only | | 1287 | <para>In your <filename>PLIST</filename>, include only |
1288 | the <filename>.la</filename> | | 1288 | the <filename>.la</filename> |
1289 | file (this is a change from previous behaviour).</para> | | 1289 | file (this is a change from previous behaviour).</para> |
1290 | </listitem> | | 1290 | </listitem> |
1291 | </orderedlist> | | 1291 | </orderedlist> |
1292 | </sect2> | | 1292 | </sect2> |
1293 | | | 1293 | |
1294 | | | 1294 | |
1295 | <sect2 id="using-libtool"> | | 1295 | <sect2 id="using-libtool"> |
1296 | <title>Using libtool on GNU packages that already support libtool</title> | | 1296 | <title>Using libtool on GNU packages that already support libtool</title> |
1297 | | | 1297 | |
1298 | <para>Add <varname>USE_LIBTOOL=yes</varname> to the | | 1298 | <para>Add <varname>USE_LIBTOOL=yes</varname> to the |
1299 | package Makefile. This will override the package's own libtool | | 1299 | package Makefile. This will override the package's own libtool |
1300 | in most cases. For older libtool using packages, libtool is | | 1300 | in most cases. For older libtool using packages, libtool is |
1301 | made by ltconfig script during the do-configure step; you can | | 1301 | made by ltconfig script during the do-configure step; you can |
1302 | check the libtool script location by doing <command>make | | 1302 | check the libtool script location by doing <command>make |
1303 | configure; find work*/ -name libtool</command>.</para> | | 1303 | configure; find work*/ -name libtool</command>.</para> |
1304 | | | 1304 | |
1305 | <para><varname>LIBTOOL_OVERRIDE</varname> specifies which libtool | | 1305 | <para><varname>LIBTOOL_OVERRIDE</varname> specifies which libtool |
1306 | scripts, relative to <varname>WRKSRC</varname>, to override. By | | 1306 | scripts, relative to <varname>WRKSRC</varname>, to override. By |
1307 | default, it is set to <quote>libtool */libtool | | 1307 | default, it is set to <quote>libtool */libtool |
1308 | */*/libtool</quote>. If this does not match the location of the | | 1308 | */*/libtool</quote>. If this does not match the location of the |
1309 | package's libtool script(s), set it as appropriate.</para> | | 1309 | package's libtool script(s), set it as appropriate.</para> |
1310 | | | 1310 | |
1311 | <para>If you do not need <filename>*.a</filename> static | | 1311 | <para>If you do not need <filename>*.a</filename> static |
1312 | libraries built and installed, then use | | 1312 | libraries built and installed, then use |
1313 | <varname>SHLIBTOOL_OVERRIDE</varname> instead.</para> | | 1313 | <varname>SHLIBTOOL_OVERRIDE</varname> instead.</para> |
1314 | | | 1314 | |
1315 | <para>If your package makes use of the platform-independent library | | 1315 | <para>If your package makes use of the platform-independent library |
1316 | for loading dynamic shared objects, that comes with libtool | | 1316 | for loading dynamic shared objects, that comes with libtool |
1317 | (libltdl), you should include devel/libltdl/buildlink3.mk.</para> | | 1317 | (libltdl), you should include devel/libltdl/buildlink3.mk.</para> |
1318 | | | 1318 | |
1319 | <para>Some packages use libtool incorrectly so that the package | | 1319 | <para>Some packages use libtool incorrectly so that the package |
1320 | may not work or build in some circumstances. Some of the more | | 1320 | may not work or build in some circumstances. Some of the more |
1321 | common errors are:</para> | | 1321 | common errors are:</para> |
1322 | | | 1322 | |
1323 | <itemizedlist> | | 1323 | <itemizedlist> |
1324 | <listitem> | | 1324 | <listitem> |
1325 | <para>The inclusion of a shared object (-module) as a dependent library in an | | 1325 | <para>The inclusion of a shared object (-module) as a dependent library in an |
1326 | executable or library. This in itself isn't a problem if one of two things | | 1326 | executable or library. This in itself isn't a problem if one of two things |
1327 | has been done:</para> | | 1327 | has been done:</para> |
1328 | | | 1328 | |
1329 | <orderedlist> | | 1329 | <orderedlist> |
1330 | <listitem> | | 1330 | <listitem> |
1331 | <para>The shared object is named correctly, i.e. | | 1331 | <para>The shared object is named correctly, i.e. |
1332 | <filename>libfoo.la</filename>, not | | 1332 | <filename>libfoo.la</filename>, not |
1333 | <filename>foo.la</filename></para> | | 1333 | <filename>foo.la</filename></para> |
1334 | </listitem> | | 1334 | </listitem> |
1335 | | | 1335 | |
1336 | <listitem> | | 1336 | <listitem> |
1337 | <para>The -dlopen option is used when linking an executable.</para> | | 1337 | <para>The -dlopen option is used when linking an executable.</para> |
1338 | </listitem> | | 1338 | </listitem> |
1339 | </orderedlist> | | 1339 | </orderedlist> |
1340 | </listitem> | | 1340 | </listitem> |
1341 | | | 1341 | |
1342 | <listitem> | | 1342 | <listitem> |
1343 | <para>The use of libltdl without the correct calls to initialisation routines. | | 1343 | <para>The use of libltdl without the correct calls to initialisation routines. |
1344 | The function lt_dlinit() should be called and the macro | | 1344 | The function lt_dlinit() should be called and the macro |
1345 | <varname>LTDL_SET_PRELOADED_SYMBOLS</varname> included in | | 1345 | <varname>LTDL_SET_PRELOADED_SYMBOLS</varname> included in |
1346 | executables.</para> | | 1346 | executables.</para> |
1347 | </listitem> | | 1347 | </listitem> |
1348 | </itemizedlist> | | 1348 | </itemizedlist> |
1349 | </sect2> | | 1349 | </sect2> |
1350 | | | 1350 | |
1351 | | | 1351 | |
1352 | <sect2 id="autoconf-automake"> | | 1352 | <sect2 id="autoconf-automake"> |
1353 | <title>GNU Autoconf/Automake</title> | | 1353 | <title>GNU Autoconf/Automake</title> |
1354 | | | 1354 | |
1355 | <para>If a package needs GNU autoconf or automake to be executed | | 1355 | <para>If a package needs GNU autoconf or automake to be executed |
1356 | to regenerate the | | 1356 | to regenerate the |
1357 | <filename>configure</filename> | | 1357 | <filename>configure</filename> |
1358 | script and <filename>Makefile.in</filename> makefile | | 1358 | script and <filename>Makefile.in</filename> makefile |
1359 | templates from <filename>configure.ac</filename> and | | 1359 | templates from <filename>configure.ac</filename> and |
1360 | <filename>Makefile.am</filename>, | | 1360 | <filename>Makefile.am</filename>, |
1361 | then they should be executed in a pre-configure target:</para> | | 1361 | then they should be executed in a pre-configure target:</para> |
1362 | | | 1362 | |
1363 | <programlisting> | | 1363 | <programlisting> |
1364 | USE_TOOLS+= autoconf automake autoreconf | | 1364 | USE_TOOLS+= autoconf automake autoreconf |
1365 | GNU_CONFIGURE= yes | | 1365 | GNU_CONFIGURE= yes |
1366 | ... | | 1366 | ... |
1367 | | | 1367 | |
1368 | pre-configure: | | 1368 | pre-configure: |
1369 | set -e; cd ${WRKSRC} && autoreconf -fi | | 1369 | set -e; cd ${WRKSRC} && autoreconf -fi |
1370 | ... | | 1370 | ... |
1371 | </programlisting> | | 1371 | </programlisting> |
1372 | | | 1372 | |
1373 | <para>Packages which use GNU Automake will sometimes | | 1373 | <para>Packages which use GNU Automake will sometimes |
1374 | require GNU Make (<literal>gmake</literal> in | | 1374 | require GNU Make (<literal>gmake</literal> in |
1375 | <varname>USE_TOOLS</varname>), | | 1375 | <varname>USE_TOOLS</varname>), |
1376 | but not always. Note that autoreconf | | 1376 | but not always. Note that autoreconf |
1377 | only needs to be executed if <filename>configure.ac</filename> | | 1377 | only needs to be executed if <filename>configure.ac</filename> |
1378 | or Makefiles are modified, or <filename>configure</filename> | | 1378 | or Makefiles are modified, or <filename>configure</filename> |
1379 | is not present.</para> | | 1379 | is not present.</para> |
1380 | | | 1380 | |
1381 | <para>There are times when the configure process makes | | 1381 | <para>There are times when the configure process makes |
1382 | additional changes to the generated files, which then causes | | 1382 | additional changes to the generated files, which then causes |
1383 | the build process to try to re-execute the automake sequence. | | 1383 | the build process to try to re-execute the automake sequence. |
1384 | This is prevented by touching various files in the configure | | 1384 | This is prevented by touching various files in the configure |
1385 | stage. If this causes problems with your package you can set | | 1385 | stage. If this causes problems with your package you can set |
1386 | <varname>AUTOMAKE_OVERRIDE=NO</varname> in the package | | 1386 | <varname>AUTOMAKE_OVERRIDE=NO</varname> in the package |
1387 | Makefile.</para> | | 1387 | Makefile.</para> |
1388 | </sect2> | | 1388 | </sect2> |
1389 | | | 1389 | |
1390 | <sect2 id="meson"> | | 1390 | <sect2 id="meson"> |
1391 | <title>Meson / ninja</title> | | 1391 | <title>Meson / ninja</title> |
1392 | | | 1392 | |
1393 | <para>Packages using Meson to configure need to include: | | 1393 | <para>Packages using Meson to configure need to include: |
1394 | | | 1394 | |
1395 | <programlisting> | | 1395 | <programlisting> |
1396 | .include "../../devel/meson/build.mk" | | 1396 | .include "../../devel/meson/build.mk" |
1397 | </programlisting></para> | | 1397 | </programlisting></para> |
1398 | | | 1398 | |
1399 | <para>In nearly all cases (any program with dependencies), | | 1399 | <para>In nearly all cases (any program with dependencies), |
1400 | pkg-config needs to be added to | | 1400 | pkg-config needs to be added to |
1401 | <varname>USE_TOOLS</varname>. If the package installs | | 1401 | <varname>USE_TOOLS</varname>. If the package installs |
1402 | translation files for non-English languages, also | | 1402 | translation files for non-English languages, also |
1403 | add msgfmt and xgettext: | | 1403 | add msgfmt and xgettext: |
1404 | | | 1404 | |
1405 | <programlisting> | | 1405 | <programlisting> |
1406 | USE_TOOLS+= pkg-config msgfmt xgettext | | 1406 | USE_TOOLS+= pkg-config msgfmt xgettext |
1407 | </programlisting></para> | | 1407 | </programlisting></para> |
1408 | | | 1408 | |
1409 | <para>If any options need to be passed to Meson, use | | 1409 | <para>If any options need to be passed to Meson, use |
1410 | <varname>MESON_ARGS</varname> instead of | | 1410 | <varname>MESON_ARGS</varname> instead of |
1411 | <varname>CONFIGURE_ARGS</varname>: | | 1411 | <varname>CONFIGURE_ARGS</varname>: |
1412 | | | 1412 | |
1413 | <programlisting> | | 1413 | <programlisting> |
1414 | MESON_ARGS+= -Dx11=false | | 1414 | MESON_ARGS+= -Dx11=false |
1415 | </programlisting></para> | | 1415 | </programlisting></para> |
1416 | </sect2> | | 1416 | </sect2> |
1417 | | | 1417 | |
1418 | </sect1> | | 1418 | </sect1> |
1419 | | | 1419 | |
1420 | <sect1 id="programming-languages"> | | 1420 | <sect1 id="programming-languages"> |
1421 | <title>Programming languages</title> | | 1421 | <title>Programming languages</title> |
1422 | | | 1422 | |
1423 | <sect2 id="basic-programming-languages"> | | 1423 | <sect2 id="basic-programming-languages"> |
1424 | <title>C, C++, and Fortran</title> | | 1424 | <title>C, C++, and Fortran</title> |
1425 | | | 1425 | |
1426 | <para>Compilers for the C and C++ languages comes with | | 1426 | <para>Compilers for the C and C++ languages comes with |
1427 | the NetBSD base system. By default, pkgsrc assumes that a package | | 1427 | the NetBSD base system. By default, pkgsrc assumes that a package |
1428 | is written in C and will hide all other compilers (via the wrapper | | 1428 | is written in C and will hide all other compilers (via the wrapper |
1429 | framework, see <xref linkend="buildlink" />).</para> | | 1429 | framework, see <xref linkend="buildlink" />).</para> |
1430 | | | 1430 | |
1431 | <para>To declare which languages should be made available through | | 1431 | <para>To declare which languages should be made available through |
1432 | pkgsrc's compiler wrappers, use | | 1432 | pkgsrc's compiler wrappers, use |
1433 | the <varname>USE_LANGUAGES</varname> variable. Allowed values | | 1433 | the <varname>USE_LANGUAGES</varname> variable. Allowed values |
1434 | currently are: | | 1434 | currently are: |
1435 | <programlisting> | | 1435 | <programlisting> |
1436 | c99, c++, c++03, gnu++03, c++0x, gnu++0x, c++11, gnu++11, | | 1436 | c99, c++, c++03, gnu++03, c++0x, gnu++0x, c++11, gnu++11, |
1437 | c++14, gnu++14, c++17, gnu++17, c++20, gnu++20, fortran, | | 1437 | c++14, gnu++14, c++17, gnu++17, c++20, gnu++20, fortran, |
1438 | fortran77, java, objc, obj-c++, and ada. | | 1438 | fortran77, java, objc, obj-c++, and ada. |
1439 | </programlisting> | | 1439 | </programlisting> |
1440 | (and any combination). The default is | | 1440 | (and any combination). The default is |
1441 | <quote>c</quote>. Packages using GNU configure scripts, even if | | 1441 | <quote>c</quote>. Packages using GNU configure scripts, even if |
1442 | written in C++, usually need a C compiler for the configure | | 1442 | written in C++, usually need a C compiler for the configure |
1443 | phase. | | 1443 | phase. |
1444 | Language variants like <literal>c++11</literal> | | 1444 | Language variants like <literal>c++11</literal> |
1445 | can be specified if the package does not explicitly set | | 1445 | can be specified if the package does not explicitly set |
1446 | <literal>-std=...</literal> when compiling (i.e. the package | | 1446 | <literal>-std=...</literal> when compiling (i.e. the package |
1447 | assumes the compiler defaults to C++11 or some other standard). | | 1447 | assumes the compiler defaults to C++11 or some other standard). |
1448 | This is a common bug in upstream build systems.</para> | | 1448 | This is a common bug in upstream build systems.</para> |
1449 | | | 1449 | |
1450 | <para>To declare which features a package requies from the | | 1450 | <para>To declare which features a package requies from the |
1451 | compiler, set either <varname>USE_CC_FEATURES</varname> | | 1451 | compiler, set either <varname>USE_CC_FEATURES</varname> |
1452 | or <varname>USE_CXX_FEATURES</varname>. Allowed values for | | 1452 | or <varname>USE_CXX_FEATURES</varname>. Allowed values for |
1453 | <varname>USE_CC_FEATURES</varname> are currently: | | 1453 | <varname>USE_CC_FEATURES</varname> are currently: |
1454 | <programlisting> | | 1454 | <programlisting> |
1455 | c11, c99, has_include | | 1455 | c11, c99, has_include |
1456 | </programlisting> | | 1456 | </programlisting> |
1457 | Allowed values for <varname>USE_CXX_FEATURES</varname> are | | 1457 | Allowed values for <varname>USE_CXX_FEATURES</varname> are |
1458 | currently: | | 1458 | currently: |
1459 | <programlisting> | | 1459 | <programlisting> |
1460 | c++11, c++14, c++17, c++20, has_include, regex, filesystem, | | 1460 | c++11, c++14, c++17, c++20, has_include, regex, filesystem, |
1461 | charconv, parallelism_ts, unique_ptr, put_time | | 1461 | charconv, parallelism_ts, unique_ptr, put_time, |
| | | 1462 | is_trivially_copy_constructible |
1462 | </programlisting> | | 1463 | </programlisting> |
1463 | .</para> | | 1464 | .</para> |
1464 | </para> | | 1465 | </para> |
1465 | </sect2> | | 1466 | </sect2> |
1466 | | | 1467 | |
1467 | <sect2 id="java-programming-language"> | | 1468 | <sect2 id="java-programming-language"> |
1468 | <title>Java</title> | | 1469 | <title>Java</title> |
1469 | | | 1470 | |
1470 | <para>If a program is written in Java, use the Java framework in | | 1471 | <para>If a program is written in Java, use the Java framework in |
1471 | pkgsrc. The package must include | | 1472 | pkgsrc. The package must include |
1472 | <filename>../../mk/java-vm.mk</filename>. This Makefile fragment | | 1473 | <filename>../../mk/java-vm.mk</filename>. This Makefile fragment |
1473 | provides the following variables:</para> | | 1474 | provides the following variables:</para> |
1474 | | | 1475 | |
1475 | <itemizedlist> | | 1476 | <itemizedlist> |
1476 | <listitem><para><varname>USE_JAVA</varname> defines if a build | | 1477 | <listitem><para><varname>USE_JAVA</varname> defines if a build |
1477 | dependency on the JDK is added. If | | 1478 | dependency on the JDK is added. If |
1478 | <varname>USE_JAVA</varname> is set to <quote>run</quote>, then | | 1479 | <varname>USE_JAVA</varname> is set to <quote>run</quote>, then |
1479 | there is only a runtime dependency on the JDK. The default is | | 1480 | there is only a runtime dependency on the JDK. The default is |
1480 | <quote>yes</quote>, which also adds a build dependency on the | | 1481 | <quote>yes</quote>, which also adds a build dependency on the |
1481 | JDK.</para></listitem> | | 1482 | JDK.</para></listitem> |
1482 | | | 1483 | |
1483 | <listitem><para>Set <varname>USE_JAVA2</varname> to declare that | | 1484 | <listitem><para>Set <varname>USE_JAVA2</varname> to declare that |
1484 | a package needs a Java2 implementation. The supported values | | 1485 | a package needs a Java2 implementation. The supported values |
1485 | are <quote>yes</quote>, <quote>1.4</quote>, and | | 1486 | are <quote>yes</quote>, <quote>1.4</quote>, and |
1486 | <quote>1.5</quote>. <quote>yes</quote> accepts any Java2 | | 1487 | <quote>1.5</quote>. <quote>yes</quote> accepts any Java2 |
1487 | implementation, <quote>1.4</quote> insists on versions 1.4 or | | 1488 | implementation, <quote>1.4</quote> insists on versions 1.4 or |
1488 | above, and <quote>1.5</quote> only accepts versions 1.5 or | | 1489 | above, and <quote>1.5</quote> only accepts versions 1.5 or |
1489 | above. This variable is not set by default.</para></listitem> | | 1490 | above. This variable is not set by default.</para></listitem> |
1490 | | | 1491 | |
1491 | <listitem><para><varname>PKG_JAVA_HOME</varname> is | | 1492 | <listitem><para><varname>PKG_JAVA_HOME</varname> is |
1492 | automatically set to the runtime location of the used Java | | 1493 | automatically set to the runtime location of the used Java |
1493 | implementation dependency. It may be used to set | | 1494 | implementation dependency. It may be used to set |
1494 | <varname>JAVA_HOME</varname> to a good value if the program | | 1495 | <varname>JAVA_HOME</varname> to a good value if the program |
1495 | needs this variable to be defined. | | 1496 | needs this variable to be defined. |
1496 | </para></listitem> | | 1497 | </para></listitem> |
1497 | <!-- XXX: describe PKG_JVM_DEFAULT and PKG_JVMS_ACCEPTED, but | | 1498 | <!-- XXX: describe PKG_JVM_DEFAULT and PKG_JVMS_ACCEPTED, but |
1498 | not here --> | | 1499 | not here --> |
1499 | </itemizedlist> | | 1500 | </itemizedlist> |
1500 | </sect2> | | 1501 | </sect2> |
1501 | | | 1502 | |
1502 | <sect2 id="go-programming-language"> | | 1503 | <sect2 id="go-programming-language"> |
1503 | <title>Go</title> | | 1504 | <title>Go</title> |
1504 | | | 1505 | |
1505 | <para>If a program is written in Go and has any dependencies on | | 1506 | <para>If a program is written in Go and has any dependencies on |
1506 | other Go modules, have the package include | | 1507 | other Go modules, have the package include |
1507 | <filename>../../lang/go/go-module.mk</filename>.</para> | | 1508 | <filename>../../lang/go/go-module.mk</filename>.</para> |
1508 | | | 1509 | |
1509 | | | 1510 | |
1510 | <orderedlist> | | 1511 | <orderedlist> |
1511 | <listitem><para>Generate a list of those dependencies with | | 1512 | <listitem><para>Generate a list of those dependencies with |
1512 | <command>make clean && make patch && make show-go-modules > | | 1513 | <command>make clean && make patch && make show-go-modules > |
1513 | go-modules.mk</command>.</para></listitem> | | 1514 | go-modules.mk</command>.</para></listitem> |
1514 | | | 1515 | |
1515 | <listitem><para>Prepend | | 1516 | <listitem><para>Prepend |
1516 | <literal>.include "go-modules.mk"</literal> to any other | | 1517 | <literal>.include "go-modules.mk"</literal> to any other |
1517 | <literal>.include</literal>s.</para></listitem> | | 1518 | <literal>.include</literal>s.</para></listitem> |
1518 | | | 1519 | |
1519 | <listitem><para>Incorporate these modules in | | 1520 | <listitem><para>Incorporate these modules in |
1520 | <filename>distinfo</filename> with <command>make | | 1521 | <filename>distinfo</filename> with <command>make |
1521 | makesum</command>.</para></listitem> | | 1522 | makesum</command>.</para></listitem> |
1522 | </orderedlist> | | 1523 | </orderedlist> |
1523 | </sect2> | | 1524 | </sect2> |
1524 | | | 1525 | |
1525 | <sect2 id="rust-programming-language"> | | 1526 | <sect2 id="rust-programming-language"> |
1526 | <title>Rust</title> | | 1527 | <title>Rust</title> |
1527 | | | 1528 | |
1528 | <para>If a program is written in Rust and uses Cargo to build, | | 1529 | <para>If a program is written in Rust and uses Cargo to build, |
1529 | have the package include | | 1530 | have the package include |
1530 | <filename>../../lang/rust/cargo.mk</filename>.</para> | | 1531 | <filename>../../lang/rust/cargo.mk</filename>.</para> |
1531 | | | 1532 | |
1532 | <orderedlist> | | 1533 | <orderedlist> |
1533 | <listitem><para>Generate a list of those dependencies with | | 1534 | <listitem><para>Generate a list of those dependencies with |
1534 | <command>make CARGO_ARGS="build --release" build && | | 1535 | <command>make CARGO_ARGS="build --release" build && |
1535 | make print-cargo-depends > cargo-depends.mk</command>.</para></listitem> | | 1536 | make print-cargo-depends > cargo-depends.mk</command>.</para></listitem> |
1536 | | | 1537 | |
1537 | <listitem><para>Prepend | | 1538 | <listitem><para>Prepend |
1538 | <literal>.include "cargo-depends.mk"</literal> to any other | | 1539 | <literal>.include "cargo-depends.mk"</literal> to any other |
1539 | <literal>.include</literal>s.</para></listitem> | | 1540 | <literal>.include</literal>s.</para></listitem> |
1540 | | | 1541 | |
1541 | <listitem><para>Incorporate these modules in | | 1542 | <listitem><para>Incorporate these modules in |
1542 | <filename>distinfo</filename> with <command>make | | 1543 | <filename>distinfo</filename> with <command>make |
1543 | makesum</command>.</para></listitem> | | 1544 | makesum</command>.</para></listitem> |
1544 | </orderedlist> | | 1545 | </orderedlist> |
1545 | </sect2> | | 1546 | </sect2> |
1546 | | | 1547 | |
1547 | <sect2 id="perl-scripts"> | | 1548 | <sect2 id="perl-scripts"> |
1548 | <title>Packages containing Perl scripts</title> | | 1549 | <title>Packages containing Perl scripts</title> |
1549 | | | 1550 | |
1550 | <para>If your package contains interpreted Perl scripts, add | | 1551 | <para>If your package contains interpreted Perl scripts, add |
1551 | <quote>perl</quote> to the <varname>USE_TOOLS</varname> variable | | 1552 | <quote>perl</quote> to the <varname>USE_TOOLS</varname> variable |
1552 | and set <varname>REPLACE_PERL</varname> to ensure that the proper | | 1553 | and set <varname>REPLACE_PERL</varname> to ensure that the proper |
1553 | interpreter path is set. <varname>REPLACE_PERL</varname> should | | 1554 | interpreter path is set. <varname>REPLACE_PERL</varname> should |
1554 | contain a list of scripts, relative to <varname>WRKSRC</varname>, | | 1555 | contain a list of scripts, relative to <varname>WRKSRC</varname>, |
1555 | that you want adjusted. Every occurrence of | | 1556 | that you want adjusted. Every occurrence of |
1556 | <filename>*/bin/perl</filename> in a she-bang line will be | | 1557 | <filename>*/bin/perl</filename> in a she-bang line will be |
1557 | replaced with the full path to the Perl executable.</para> | | 1558 | replaced with the full path to the Perl executable.</para> |
1558 | | | 1559 | |
1559 | <para>If a particular version of Perl is needed, set the | | 1560 | <para>If a particular version of Perl is needed, set the |
1560 | <varname>PERL5_REQD</varname> variable to the version number. The | | 1561 | <varname>PERL5_REQD</varname> variable to the version number. The |
1561 | default is <quote>5.0</quote>.</para> | | 1562 | default is <quote>5.0</quote>.</para> |
1562 | | | 1563 | |
1563 | <para>See <xref linkend="perl-modules" /> for information | | 1564 | <para>See <xref linkend="perl-modules" /> for information |
1564 | about handling Perl modules.</para> | | 1565 | about handling Perl modules.</para> |
1565 | | | 1566 | |
1566 | <para>There is also the <varname>REPLACE_PERL6</varname> variable | | 1567 | <para>There is also the <varname>REPLACE_PERL6</varname> variable |
1567 | for the language now known as Raku.</para> | | 1568 | for the language now known as Raku.</para> |
1568 | </sect2> | | 1569 | </sect2> |
1569 | | | 1570 | |
1570 | <sect2 id="shell-scripts"> | | 1571 | <sect2 id="shell-scripts"> |
1571 | <title>Packages containing shell scripts</title> | | 1572 | <title>Packages containing shell scripts</title> |
1572 | | | 1573 | |
1573 | <para><varname>REPLACE_SH</varname>, | | 1574 | <para><varname>REPLACE_SH</varname>, |
1574 | <varname>REPLACE_BASH</varname>, <varname>REPLACE_CSH</varname>, | | 1575 | <varname>REPLACE_BASH</varname>, <varname>REPLACE_CSH</varname>, |
1575 | and <varname>REPLACE_KSH</varname> can be used to replace shell | | 1576 | and <varname>REPLACE_KSH</varname> can be used to replace shell |
1576 | she-bangs in files. Please use the appropriate one, preferring | | 1577 | she-bangs in files. Please use the appropriate one, preferring |
1577 | <varname>REPLACE_SH</varname> when this shell is sufficient. | | 1578 | <varname>REPLACE_SH</varname> when this shell is sufficient. |
1578 | Each should contain a list of scripts, relative to | | 1579 | Each should contain a list of scripts, relative to |
1579 | <varname>WRKSRC</varname>, that you want adjusted. Every | | 1580 | <varname>WRKSRC</varname>, that you want adjusted. Every |
1580 | occurrence of the matching shell in a she-bang line will be | | 1581 | occurrence of the matching shell in a she-bang line will be |
1581 | replaced with the full path to the shell executable. | | 1582 | replaced with the full path to the shell executable. |
1582 | When using <varname>REPLACE_BASH</varname>, don't forget to add | | 1583 | When using <varname>REPLACE_BASH</varname>, don't forget to add |
1583 | <filename>bash</filename> to <varname>USE_TOOLS</varname>.</para> | | 1584 | <filename>bash</filename> to <varname>USE_TOOLS</varname>.</para> |
1584 | </sect2> | | 1585 | </sect2> |
1585 | | | 1586 | |
1586 | <sect2 id="other-programming-languages"> | | 1587 | <sect2 id="other-programming-languages"> |
1587 | <title>Other programming languages</title> | | 1588 | <title>Other programming languages</title> |
1588 | | | 1589 | |
1589 | <para>There are further similar REPLACE variables available, e.g., | | 1590 | <para>There are further similar REPLACE variables available, e.g., |
1590 | <varname>REPLACE_AWK</varname> for packages containing awk scripts, | | 1591 | <varname>REPLACE_AWK</varname> for packages containing awk scripts, |
1591 | and <varname>REPLACE_R</varname> for R. These two, like the others | | 1592 | and <varname>REPLACE_R</varname> for R. These two, like the others |
1592 | noted above, have their actions defined centrally in | | 1593 | noted above, have their actions defined centrally in |
1593 | <filename>mk/configure/replace-interpreter.mk</filename>. Other | | 1594 | <filename>mk/configure/replace-interpreter.mk</filename>. Other |
1594 | languages define the actions of these variables within their own | | 1595 | languages define the actions of these variables within their own |
1595 | dedicated part of the tree, e.g., <varname>REPLACE_PHP</varname> is | | 1596 | dedicated part of the tree, e.g., <varname>REPLACE_PHP</varname> is |
1596 | actioned in <filename>lang/php/phpversion.mk</filename>, and | | 1597 | actioned in <filename>lang/php/phpversion.mk</filename>, and |
1597 | <varname>REPLACE_PYTHON</varname> is actioned in | | 1598 | <varname>REPLACE_PYTHON</varname> is actioned in |
1598 | <filename>lang/python/application.mk</filename>. For other languages, | | 1599 | <filename>lang/python/application.mk</filename>. For other languages, |
1599 | consult the mk files found within their specific directories (the | | 1600 | consult the mk files found within their specific directories (the |
1600 | naming convention varies), or check the list found in | | 1601 | naming convention varies), or check the list found in |
1601 | <xref linkend="help-topics" />.</para> | | 1602 | <xref linkend="help-topics" />.</para> |
1602 | | | 1603 | |
1603 | <para>Currently, special handling for other languages varies | | 1604 | <para>Currently, special handling for other languages varies |
1604 | in pkgsrc. If a compiler package provides a | | 1605 | in pkgsrc. If a compiler package provides a |
1605 | <filename>buildlink3.mk</filename> file, include that, otherwise | | 1606 | <filename>buildlink3.mk</filename> file, include that, otherwise |
1606 | just add a (build) dependency on the appropriate compiler | | 1607 | just add a (build) dependency on the appropriate compiler |
1607 | package.</para> | | 1608 | package.</para> |
1608 | </sect2> | | 1609 | </sect2> |
1609 | </sect1> | | 1610 | </sect1> |
1610 | | | 1611 | |
1611 | <sect1 id="fixes.build"> | | 1612 | <sect1 id="fixes.build"> |
1612 | <title>The <emphasis>build</emphasis> phase</title> | | 1613 | <title>The <emphasis>build</emphasis> phase</title> |
1613 | | | 1614 | |
1614 | <para>The most common failures when building a package are that | | 1615 | <para>The most common failures when building a package are that |
1615 | some platforms do not provide certain header files, functions or | | 1616 | some platforms do not provide certain header files, functions or |
1616 | libraries, or they provide the functions in a library that the | | 1617 | libraries, or they provide the functions in a library that the |
1617 | original package author didn't know. To work around this, you | | 1618 | original package author didn't know. To work around this, you |
1618 | can rewrite the source code in most cases so that it does not | | 1619 | can rewrite the source code in most cases so that it does not |
1619 | use the missing functions or provides a replacement function.</para> | | 1620 | use the missing functions or provides a replacement function.</para> |
1620 | | | 1621 | |
1621 | <sect2 id="fixes.build.cpp"> | | 1622 | <sect2 id="fixes.build.cpp"> |
1622 | <title>Compiling C and C++ code conditionally</title> | | 1623 | <title>Compiling C and C++ code conditionally</title> |
1623 | | | 1624 | |
1624 | <para>If a package already comes with a GNU configure script, the | | 1625 | <para>If a package already comes with a GNU configure script, the |
1625 | preferred way to fix the build failure is to change the | | 1626 | preferred way to fix the build failure is to change the |
1626 | configure script, not the code. In the other cases, you can | | 1627 | configure script, not the code. In the other cases, you can |
1627 | utilize the C preprocessor, which defines certain macros | | 1628 | utilize the C preprocessor, which defines certain macros |
1628 | depending on the operating system and hardware architecture it | | 1629 | depending on the operating system and hardware architecture it |
1629 | compiles for. These macros can be queried using for example | | 1630 | compiles for. These macros can be queried using for example |
1630 | <varname>#if defined(__i386)</varname>. Almost every operating | | 1631 | <varname>#if defined(__i386)</varname>. Almost every operating |
1631 | system, hardware architecture and compiler has its own macro. | | 1632 | system, hardware architecture and compiler has its own macro. |
1632 | For example, if the macros <varname>__GNUC__</varname>, | | 1633 | For example, if the macros <varname>__GNUC__</varname>, |
1633 | <varname>__i386__</varname> and <varname>__NetBSD__</varname> | | 1634 | <varname>__i386__</varname> and <varname>__NetBSD__</varname> |
1634 | are all defined, you know that you are using NetBSD on an i386 | | 1635 | are all defined, you know that you are using NetBSD on an i386 |
1635 | compatible CPU, and your compiler is GCC.</para> | | 1636 | compatible CPU, and your compiler is GCC.</para> |
1636 | | | 1637 | |
1637 | <para>The list of the following macros for hardware and | | 1638 | <para>The list of the following macros for hardware and |
1638 | operating system depends on the compiler that is used. For | | 1639 | operating system depends on the compiler that is used. For |
1639 | example, if you want to conditionally compile code on Solaris, | | 1640 | example, if you want to conditionally compile code on Solaris, |
1640 | don't use <varname>__sun__</varname>, as the SunPro compiler | | 1641 | don't use <varname>__sun__</varname>, as the SunPro compiler |
1641 | does not define it. Use <varname>__sun</varname> instead.</para> | | 1642 | does not define it. Use <varname>__sun</varname> instead.</para> |
1642 | | | 1643 | |
1643 | <sect3 id="fixes.build.cpp.os"> | | 1644 | <sect3 id="fixes.build.cpp.os"> |
1644 | <title>C preprocessor macros to identify the operating system</title> | | 1645 | <title>C preprocessor macros to identify the operating system</title> |
1645 | | | 1646 | |
1646 | <para>To distinguish between specific NetBSD versions, | | 1647 | <para>To distinguish between specific NetBSD versions, |
1647 | you should use the following code.</para> | | 1648 | you should use the following code.</para> |
1648 | | | 1649 | |
1649 | <programlisting> | | 1650 | <programlisting> |
1650 | #ifdef __NetBSD__ | | 1651 | #ifdef __NetBSD__ |
1651 | #include <sys/param.h> | | 1652 | #include <sys/param.h> |
1652 | #if __NetBSD_Prereq__(9,99,17) | | 1653 | #if __NetBSD_Prereq__(9,99,17) |
1653 | /* use a newer feature */ | | 1654 | /* use a newer feature */ |
1654 | #else | | 1655 | #else |
1655 | /* older code */ | | 1656 | /* older code */ |
1656 | #endif | | 1657 | #endif |
1657 | #endif | | 1658 | #endif |
1658 | | | 1659 | |
1659 | #ifndef _WIN32 | | 1660 | #ifndef _WIN32 |
1660 | /* Unix-like specific code */ | | 1661 | /* Unix-like specific code */ |
1661 | #endif | | 1662 | #endif |
1662 | </programlisting> | | 1663 | </programlisting> |
1663 | | | 1664 | |
1664 | <para>To distinguish between 4.4 BSD-derived systems and the | | 1665 | <para>To distinguish between 4.4 BSD-derived systems and the |
1665 | rest of the world, you should use the following code.</para> | | 1666 | rest of the world, you should use the following code.</para> |
1666 | | | 1667 | |
1667 | <programlisting> | | 1668 | <programlisting> |
1668 | #include <sys/param.h> | | 1669 | #include <sys/param.h> |
1669 | #if (defined(BSD) && BSD >= 199306) | | 1670 | #if (defined(BSD) && BSD >= 199306) |
1670 | /* BSD-specific code goes here */ | | 1671 | /* BSD-specific code goes here */ |
1671 | #else | | 1672 | #else |
1672 | /* non-BSD-specific code goes here */ | | 1673 | /* non-BSD-specific code goes here */ |
1673 | #endif | | 1674 | #endif |
1674 | </programlisting> | | 1675 | </programlisting> |
1675 | | | 1676 | |
1676 | <para>You can also test for the following macros:</para> | | 1677 | <para>You can also test for the following macros:</para> |
1677 | | | 1678 | |
1678 | <programlisting> | | 1679 | <programlisting> |
1679 | Cygwin __CYGWIN__ | | 1680 | Cygwin __CYGWIN__ |
1680 | DragonFly __DragonFly__ | | 1681 | DragonFly __DragonFly__ |
1681 | FreeBSD __FreeBSD__ | | 1682 | FreeBSD __FreeBSD__ |
1682 | Haiku __HAIKU__ | | 1683 | Haiku __HAIKU__ |
1683 | Interix __INTERIX | | 1684 | Interix __INTERIX |
1684 | IRIX __sgi (TODO: get a definite source for this) | | 1685 | IRIX __sgi (TODO: get a definite source for this) |
1685 | Linux __linux | | 1686 | Linux __linux |
1686 | Mac OS X __APPLE__ | | 1687 | Mac OS X __APPLE__ |
1687 | MirBSD __MirBSD__ (__OpenBSD__ is also defined) | | 1688 | MirBSD __MirBSD__ (__OpenBSD__ is also defined) |
1688 | Minix3 __minix | | 1689 | Minix3 __minix |
1689 | NetBSD __NetBSD__ | | 1690 | NetBSD __NetBSD__ |
1690 | OpenBSD __OpenBSD__ | | 1691 | OpenBSD __OpenBSD__ |
1691 | Solaris sun, __sun | | 1692 | Solaris sun, __sun |
1692 | </programlisting> | | 1693 | </programlisting> |
1693 | | | 1694 | |
1694 | </sect3> | | 1695 | </sect3> |
1695 | <sect3 id="fixes.build.cpp.arch"> | | 1696 | <sect3 id="fixes.build.cpp.arch"> |
1696 | <title>C preprocessor macros to identify the hardware architecture</title> | | 1697 | <title>C preprocessor macros to identify the hardware architecture</title> |
1697 | | | 1698 | |
1698 | <programlisting> | | 1699 | <programlisting> |
1699 | i386 i386, __i386, __i386__ | | 1700 | i386 i386, __i386, __i386__ |
1700 | x86-64 __amd64__, __x86_64__ | | 1701 | x86-64 __amd64__, __x86_64__ |
1701 | ARM __arm__ | | 1702 | ARM __arm__ |
1702 | MIPS __mips | | 1703 | MIPS __mips |
1703 | SPARC sparc, __sparc | | 1704 | SPARC sparc, __sparc |
1704 | PowerPC __powerpc | | 1705 | PowerPC __powerpc |
1705 | </programlisting> | | 1706 | </programlisting> |
1706 | | | 1707 | |
1707 | </sect3> | | 1708 | </sect3> |
1708 | <sect3 id="fixes.build.cpp.compiler"> | | 1709 | <sect3 id="fixes.build.cpp.compiler"> |
1709 | <title>C preprocessor macros to identify the compiler</title> | | 1710 | <title>C preprocessor macros to identify the compiler</title> |
1710 | | | 1711 | |
1711 | <programlisting> | | 1712 | <programlisting> |
1712 | GCC __GNUC__ (major version), __GNUC_MINOR__ | | 1713 | GCC __GNUC__ (major version), __GNUC_MINOR__ |
1713 | MIPSpro _COMPILER_VERSION (0x741 for MIPSpro 7.41) | | 1714 | MIPSpro _COMPILER_VERSION (0x741 for MIPSpro 7.41) |
1714 | SunPro __SUNPRO_C (0x570 for Sun C 5.7) | | 1715 | SunPro __SUNPRO_C (0x570 for Sun C 5.7) |
1715 | SunPro C++ __SUNPRO_CC (0x580 for Sun C++ 5.8) | | 1716 | SunPro C++ __SUNPRO_CC (0x580 for Sun C++ 5.8) |
1716 | </programlisting> | | 1717 | </programlisting> |
1717 | | | 1718 | |
1718 | </sect3> | | 1719 | </sect3> |
1719 | </sect2> | | 1720 | </sect2> |
1720 | <sect2 id="compiler-bugs"> | | 1721 | <sect2 id="compiler-bugs"> |
1721 | <title>How to handle compiler bugs</title> | | 1722 | <title>How to handle compiler bugs</title> |
1722 | | | 1723 | |
1723 | <para>Some source files trigger bugs in the compiler, based on | | 1724 | <para>Some source files trigger bugs in the compiler, based on |
1724 | combinations of compiler version and architecture and almost | | 1725 | combinations of compiler version and architecture and almost |
1725 | always relation to optimisation being enabled. Common symptoms | | 1726 | always relation to optimisation being enabled. Common symptoms |
1726 | are gcc internal errors or never finishing compiling a | | 1727 | are gcc internal errors or never finishing compiling a |
1727 | file.</para> | | 1728 | file.</para> |
1728 | | | 1729 | |
1729 | <para>Typically, a workaround involves testing the | | 1730 | <para>Typically, a workaround involves testing the |
1730 | <varname>MACHINE_ARCH</varname> and compiler version, disabling | | 1731 | <varname>MACHINE_ARCH</varname> and compiler version, disabling |
1731 | optimisation for that combination of file, | | 1732 | optimisation for that combination of file, |
1732 | <varname>MACHINE_ARCH</varname> and compiler.</para> | | 1733 | <varname>MACHINE_ARCH</varname> and compiler.</para> |
1733 | | | 1734 | |
1734 | <para>This used to be a big problem in the past, but is rarely | | 1735 | <para>This used to be a big problem in the past, but is rarely |
1735 | needed now as compiler technology has matured. If you still need | | 1736 | needed now as compiler technology has matured. If you still need |
1736 | to add a compiler specific workaround, please do so in the file | | 1737 | to add a compiler specific workaround, please do so in the file |
1737 | <filename>hacks.mk</filename> and describe the symptom and | | 1738 | <filename>hacks.mk</filename> and describe the symptom and |
1738 | compiler version as detailed as possible.</para> | | 1739 | compiler version as detailed as possible.</para> |
1739 | | | 1740 | |
1740 | </sect2> | | 1741 | </sect2> |
1741 | | | 1742 | |
1742 | <sect2 id="fixes.build.header"> | | 1743 | <sect2 id="fixes.build.header"> |
1743 | <title>No such file or directory</title> | | 1744 | <title>No such file or directory</title> |
1744 | | | 1745 | |
1745 | <para>Compilation sometimes fails with an error message like this:</para> | | 1746 | <para>Compilation sometimes fails with an error message like this:</para> |
1746 | | | 1747 | |
1747 | <programlisting> | | 1748 | <programlisting> |
1748 | .../x11/gtk3/work/gtk+-3.24.12/gdk/gdktypes.h:35:10: | | 1749 | .../x11/gtk3/work/gtk+-3.24.12/gdk/gdktypes.h:35:10: |
1749 | fatal error: pango/pango.h: No such file or directory | | 1750 | fatal error: pango/pango.h: No such file or directory |
1750 | </programlisting> | | 1751 | </programlisting> |
1751 | | | 1752 | |
1752 | <para>The proper way to fix this problem depends on the type of the | | 1753 | <para>The proper way to fix this problem depends on the type of the |
1753 | header, which is described in the following sections.</para> | | 1754 | header, which is described in the following sections.</para> |
1754 | | | 1755 | |
1755 | <sect3 id="fixes.build.header.bl3"> | | 1756 | <sect3 id="fixes.build.header.bl3"> |
1756 | <title>Headers from other packages</title> | | 1757 | <title>Headers from other packages</title> |
1757 | | | 1758 | |
1758 | <para>If the header name looks like it comes from a different package, | | 1759 | <para>If the header name looks like it comes from a different package, |
1759 | that other package should be included via the buildlink3 | | 1760 | that other package should be included via the buildlink3 |
1760 | framework.</para> | | 1761 | framework.</para> |
1761 | | | 1762 | |
1762 | <para>First, look whether the header is somewhere in the buildlink3 | | 1763 | <para>First, look whether the header is somewhere in the buildlink3 |
1763 | directory below <varname>WRKDIR</varname>. In the above case of | | 1764 | directory below <varname>WRKDIR</varname>. In the above case of |
1764 | the missing Pango header:</para> | | 1765 | the missing Pango header:</para> |
1765 | | | 1766 | |
1766 | <programlisting> | | 1767 | <programlisting> |
1767 | &uprompt; find work/.buildlink/ -print | grep -F pango/pango.h | | 1768 | &uprompt; find work/.buildlink/ -print | grep -F pango/pango.h |
1768 | </programlisting> | | 1769 | </programlisting> |
1769 | | | 1770 | |
1770 | <para>In the case of Pango, the output is:</para> | | 1771 | <para>In the case of Pango, the output is:</para> |
1771 | | | 1772 | |
1772 | <programlisting> | | 1773 | <programlisting> |
1773 | work/.buildlink/include/pango-1.0/pango/pango.h | | 1774 | work/.buildlink/include/pango-1.0/pango/pango.h |
1774 | </programlisting> | | 1775 | </programlisting> |
1775 | | | 1776 | |
1776 | <para>If the <filename>pango/pango.h</filename> file were placed directly | | 1777 | <para>If the <filename>pango/pango.h</filename> file were placed directly |
1777 | in the <filename>.buildlink</filename> directory, it would have been | | 1778 | in the <filename>.buildlink</filename> directory, it would have been |
1778 | found automatically. There is an extra <filename>pango-1.0</filename> | | 1779 | found automatically. There is an extra <filename>pango-1.0</filename> |
1779 | path component though, which means that the compiler command line must | | 1780 | path component though, which means that the compiler command line must |
1780 | contain an option of the form | | 1781 | contain an option of the form |
1781 | <literal>-I${BUILDLINK3_PREFIX.pango}/include/pango-1.0</literal>. In | | 1782 | <literal>-I${BUILDLINK3_PREFIX.pango}/include/pango-1.0</literal>. In |
1782 | most cases this option is generated by the configure script, which can be examined using:</para> | | 1783 | most cases this option is generated by the configure script, which can be examined using:</para> |
1783 | | | 1784 | |
1784 | <programlisting> | | 1785 | <programlisting> |
1785 | &uprompt; $ grep -o '[-]I[^[:space:]]*/pango[^[:space:]]*' work/*/Makefile | | 1786 | &uprompt; $ grep -o '[-]I[^[:space:]]*/pango[^[:space:]]*' work/*/Makefile |
1786 | -I/usr/pkg/include/pango-1.0 | | 1787 | -I/usr/pkg/include/pango-1.0 |
1787 | -I/usr/pkg/include/pango-1.0 | | 1788 | -I/usr/pkg/include/pango-1.0 |
1788 | -I/usr/pkg/include/pango-1.0 | | 1789 | -I/usr/pkg/include/pango-1.0 |
1789 | -I/usr/pkg/include/pango-1.0 | | 1790 | -I/usr/pkg/include/pango-1.0 |
1790 | -I/usr/pkg/include/pango-1.0 | | 1791 | -I/usr/pkg/include/pango-1.0 |
1791 | </programlisting> | | 1792 | </programlisting> |
1792 | | | 1793 | |
1793 | <para>This looks good. These options are transformed by the buildlink | | 1794 | <para>This looks good. These options are transformed by the buildlink |
1794 | wrapper to refer to the correct path inside | | 1795 | wrapper to refer to the correct path inside |
1795 | <filename>work/.buildlink</filename>.</para> | | 1796 | <filename>work/.buildlink</filename>.</para> |
1796 | | | 1797 | |
1797 | <para>Since the compilation fails though, examine the compiler command | | 1798 | <para>Since the compilation fails though, examine the compiler command |
1798 | lines in <filename>work/.work.log</filename> to see whether the | | 1799 | lines in <filename>work/.work.log</filename> to see whether the |
1799 | <literal>-I</literal> option is included in the particular command | | 1800 | <literal>-I</literal> option is included in the particular command |
1800 | line.</para> | | 1801 | line.</para> |
1801 | | | 1802 | |
1802 | <para>To further analyze the situation, run <command>bmake | | 1803 | <para>To further analyze the situation, run <command>bmake |
1803 | build-env</command>, which sets up an interactive, realistic environment | | 1804 | build-env</command>, which sets up an interactive, realistic environment |
1804 | including all the pkgsrc wrapper commands and environment variables. From | | 1805 | including all the pkgsrc wrapper commands and environment variables. From |
1805 | there, try to compile some simple example programs that use the | | 1806 | there, try to compile some simple example programs that use the |
1806 | header.</para> | | 1807 | header.</para> |
1807 | | | 1808 | |
1808 | </sect3> | | 1809 | </sect3> |
1809 | | | 1810 | |
1810 | <sect3 id="fixes.build.header.gen"> | | 1811 | <sect3 id="fixes.build.header.gen"> |
1811 | <title>Headers generated during the build</title> | | 1812 | <title>Headers generated during the build</title> |
1812 | | | 1813 | |
1813 | <para>If the name of the header seems to come from the package itself, | | 1814 | <para>If the name of the header seems to come from the package itself, |
1814 | and if the build is run with parallel jobs, the package may have some | | 1815 | and if the build is run with parallel jobs, the package may have some |
1815 | undeclared dependencies between the <filename>.c</filename> and the | | 1816 | undeclared dependencies between the <filename>.c</filename> and the |
1816 | <filename>.h</filename> files, and a C file is compiled before its | | 1817 | <filename>.h</filename> files, and a C file is compiled before its |
1817 | required header is generated.</para> | | 1818 | required header is generated.</para> |
1818 | | | 1819 | |
1819 | <para>To see whether the build runs with parallel jobs, run | | 1820 | <para>To see whether the build runs with parallel jobs, run |
1820 | <command>bmake show-all-build | grep JOBS</command>. Its output looks | | 1821 | <command>bmake show-all-build | grep JOBS</command>. Its output looks |
1821 | like this:</para> | | 1822 | like this:</para> |
1822 | | | 1823 | |
1823 | <programlisting> | | 1824 | <programlisting> |
1824 | usr MAKE_JOBS= 7 | | 1825 | usr MAKE_JOBS= 7 |
1825 | pkg MAKE_JOBS_SAFE # undefined | | 1826 | pkg MAKE_JOBS_SAFE # undefined |
1826 | def _MAKE_JOBS_N= 7 | | 1827 | def _MAKE_JOBS_N= 7 |
1827 | </programlisting> | | 1828 | </programlisting> |
1828 | | | 1829 | |
1829 | <para>In this case the pkgsrc user has asked pkgsrc to build packages | | 1830 | <para>In this case the pkgsrc user has asked pkgsrc to build packages |
1830 | with 7 jobs in parallel (<varname>MAKE_JOBS</varname>). The | | 1831 | with 7 jobs in parallel (<varname>MAKE_JOBS</varname>). The |
1831 | package could have disabled parallel builds by setting | | 1832 | package could have disabled parallel builds by setting |
1832 | <varname>MAKE_JOBS_SAFE</varname> to <literal>no</literal>, but | | 1833 | <varname>MAKE_JOBS_SAFE</varname> to <literal>no</literal>, but |
1833 | in this case it hasn't.</para> | | 1834 | in this case it hasn't.</para> |
1834 | | | 1835 | |
1835 | <para>To see whether the build failure is caused by parallel builds, | | 1836 | <para>To see whether the build failure is caused by parallel builds, |
1836 | first save the exact error message and a bit of context, maybe you need | | 1837 | first save the exact error message and a bit of context, maybe you need |
1837 | it later for reporting a bug. Next, run:</para> | | 1838 | it later for reporting a bug. Next, run:</para> |
1838 | | | 1839 | |
1839 | <programlisting> | | 1840 | <programlisting> |
1840 | MAKE_JOBS_SAFE=no bmake clean build | | 1841 | MAKE_JOBS_SAFE=no bmake clean build |
1841 | </programlisting> | | 1842 | </programlisting> |
1842 | | | 1843 | |
1843 | <para>If that succeeds, <ulink | | 1844 | <para>If that succeeds, <ulink |
1844 | url="https://www.NetBSD.org/cgi-bin/sendpr.cgi?gndb=netbsd">file a bug | | 1845 | url="https://www.NetBSD.org/cgi-bin/sendpr.cgi?gndb=netbsd">file a bug |
1845 | report</ulink> against the pkgsrc package, including the exact error | | 1846 | report</ulink> against the pkgsrc package, including the exact error |
1846 | message and the contents of your &mk.conf; file.</para> | | 1847 | message and the contents of your &mk.conf; file.</para> |
1847 | | | 1848 | |
1848 | </sect3> | | 1849 | </sect3> |
1849 | | | 1850 | |
1850 | <sect3 id="fixes.build.header.symlink"> | | 1851 | <sect3 id="fixes.build.header.symlink"> |
1851 | <title>Symlinks</title> | | 1852 | <title>Symlinks</title> |
1852 | | | 1853 | |
1853 | <para>Pkgsrc does not work reliably if any of | | 1854 | <para>Pkgsrc does not work reliably if any of |
1854 | <varname>LOCALBASE</varname>, <varname>VARBASE</varname> or | | 1855 | <varname>LOCALBASE</varname>, <varname>VARBASE</varname> or |
1855 | <varname>WRKDIR</varname> contains a symlink. Since 2019Q2, the pkgsrc | | 1856 | <varname>WRKDIR</varname> contains a symlink. Since 2019Q2, the pkgsrc |
1856 | bootstrap program prevents installing pkgsrc in symlink-based | | 1857 | bootstrap program prevents installing pkgsrc in symlink-based |
1857 | directories. Existing pkgsrc installations are not checked for symlinks | | 1858 | directories. Existing pkgsrc installations are not checked for symlinks |
1858 | though.</para> | | 1859 | though.</para> |
1859 | | | 1860 | |
1860 | <para>The "No such file or directory" error messages are a typical | | 1861 | <para>The "No such file or directory" error messages are a typical |
1861 | symptom of symlinks, and it's quite difficult to find out that this is | | 1862 | symptom of symlinks, and it's quite difficult to find out that this is |
1862 | the actual cause.</para> | | 1863 | the actual cause.</para> |
1863 | | | 1864 | |
1864 | </sect3> | | 1865 | </sect3> |
1865 | | | 1866 | |
1866 | <sect3 id="fixes.build.header.stale"> | | 1867 | <sect3 id="fixes.build.header.stale"> |
1867 | <title>Stale working directories</title> | | 1868 | <title>Stale working directories</title> |
1868 | | | 1869 | |
1869 | <para>When building a hierarchy of packages, it may happen that one | | 1870 | <para>When building a hierarchy of packages, it may happen that one |
1870 | package is built and then pkgsrc is updated. This situation can provoke | | 1871 | package is built and then pkgsrc is updated. This situation can provoke |
1871 | various hard to diagnose build errors. To clean up the situation:</para> | | 1872 | various hard to diagnose build errors. To clean up the situation:</para> |
1872 | | | 1873 | |
1873 | <programlisting> | | 1874 | <programlisting> |
1874 | &uprompt; (cd ../../ && cat mk/bsd.pkg.mk >/dev/null && rm -rf */*/work) | | 1875 | &uprompt; (cd ../../ && cat mk/bsd.pkg.mk >/dev/null && rm -rf */*/work) |
1875 | </programlisting> | | 1876 | </programlisting> |
1876 | | | 1877 | |
1877 | <para>(The only purpose of the <filename>bsd.pkg.mk</filename> is to | | 1878 | <para>(The only purpose of the <filename>bsd.pkg.mk</filename> is to |
1878 | prevent running this command in the wrong directory.)</para> | | 1879 | prevent running this command in the wrong directory.)</para> |
1879 | | | 1880 | |
1880 | <para>If you have set <varname>WRKOBJDIR</varname> in &mk.conf;, remove | | 1881 | <para>If you have set <varname>WRKOBJDIR</varname> in &mk.conf;, remove |
1881 | that directory as well.</para> | | 1882 | that directory as well.</para> |
1882 | | | 1883 | |
1883 | </sect3> | | 1884 | </sect3> |
1884 | | | 1885 | |
1885 | <sect3 id="fixes.build.header.misc"> | | 1886 | <sect3 id="fixes.build.header.misc"> |
1886 | <title>Other possible reasons</title> | | 1887 | <title>Other possible reasons</title> |
1887 | | | 1888 | |
1888 | <para>On platforms other than BSD, third-party packages are installed in | | 1889 | <para>On platforms other than BSD, third-party packages are installed in |
1889 | <filename>/usr/include</filename>, together with the base system. This | | 1890 | <filename>/usr/include</filename>, together with the base system. This |
1890 | means that pkgsrc cannot distinguish between headers provided by the base | | 1891 | means that pkgsrc cannot distinguish between headers provided by the base |
1891 | system (which it needs) and headers from third-party packages (which are | | 1892 | system (which it needs) and headers from third-party packages (which are |
1892 | often included in pkgsrc as well). This can lead to subtle version | | 1893 | often included in pkgsrc as well). This can lead to subtle version |
1893 | mismatches.</para> | | 1894 | mismatches.</para> |
1894 | | | 1895 | |
1895 | <para>In pkgsrc installations that have been active for several years, it | | 1896 | <para>In pkgsrc installations that have been active for several years, it |
1896 | may happen that some files are manually deleted. To exclude this unlikely | | 1897 | may happen that some files are manually deleted. To exclude this unlikely |
1897 | reason, run <command>pkg_admin check</command>.</para> | | 1898 | reason, run <command>pkg_admin check</command>.</para> |
1898 | | | 1899 | |
1899 | <para>It may help to run <command>pkg_admin rebuild-tree</command> to | | 1900 | <para>It may help to run <command>pkg_admin rebuild-tree</command> to |
1900 | check/fix dependencies.</para> | | 1901 | check/fix dependencies.</para> |
1901 | | | 1902 | |
1902 | <para>If all of the above doesn't help, see <xref linkend="help-user"/> | | 1903 | <para>If all of the above doesn't help, see <xref linkend="help-user"/> |
1903 | for contact information. Be prepared to describe what you have tried so | | 1904 | for contact information. Be prepared to describe what you have tried so |
1904 | far and what any error messages were.</para> | | 1905 | far and what any error messages were.</para> |
1905 | | | 1906 | |
1906 | </sect3> | | 1907 | </sect3> |
1907 | | | 1908 | |
1908 | </sect2> | | 1909 | </sect2> |
1909 | | | 1910 | |
1910 | <sect2 id="undefined-reference"> | | 1911 | <sect2 id="undefined-reference"> |
1911 | <title>Undefined reference to <quote>...</quote></title> | | 1912 | <title>Undefined reference to <quote>...</quote></title> |
1912 | | | 1913 | |
1913 | <para>This error message often means that a package did not | | 1914 | <para>This error message often means that a package did not |
1914 | link to a shared library it needs. The following functions are | | 1915 | link to a shared library it needs. The following functions are |
1915 | known to cause this error message over and over.</para> | | 1916 | known to cause this error message over and over.</para> |
1916 | | | 1917 | |
1917 | <informaltable id="undefined-reference-functions"> | | 1918 | <informaltable id="undefined-reference-functions"> |
1918 | <tgroup cols="3"> | | 1919 | <tgroup cols="3"> |
1919 | <thead><row><entry>Function</entry><entry>Library</entry><entry>Affected platforms</entry></row></thead> | | 1920 | <thead><row><entry>Function</entry><entry>Library</entry><entry>Affected platforms</entry></row></thead> |
1920 | <tbody> | | 1921 | <tbody> |
1921 | <row><entry>accept, bind, connect</entry><entry>-lsocket</entry><entry>Solaris</entry></row> | | 1922 | <row><entry>accept, bind, connect</entry><entry>-lsocket</entry><entry>Solaris</entry></row> |
1922 | <row><entry>crypt</entry><entry>-lcrypt</entry><entry>DragonFly, NetBSD</entry></row> | | 1923 | <row><entry>crypt</entry><entry>-lcrypt</entry><entry>DragonFly, NetBSD</entry></row> |
1923 | <row><entry>dlopen, dlsym</entry><entry>-ldl</entry><entry>Linux</entry></row> | | 1924 | <row><entry>dlopen, dlsym</entry><entry>-ldl</entry><entry>Linux</entry></row> |
1924 | <row><entry>gethost*</entry><entry>-lnsl</entry><entry>Solaris</entry></row> | | 1925 | <row><entry>gethost*</entry><entry>-lnsl</entry><entry>Solaris</entry></row> |
1925 | <row><entry>inet_aton</entry><entry>-lresolv</entry><entry>Solaris</entry></row> | | 1926 | <row><entry>inet_aton</entry><entry>-lresolv</entry><entry>Solaris</entry></row> |
1926 | <row><entry>nanosleep, sem_*, timer_*</entry><entry>-lrt</entry><entry>Solaris</entry></row> | | 1927 | <row><entry>nanosleep, sem_*, timer_*</entry><entry>-lrt</entry><entry>Solaris</entry></row> |
1927 | <row><entry>openpty</entry><entry>-lutil</entry><entry>Linux</entry></row> | | 1928 | <row><entry>openpty</entry><entry>-lutil</entry><entry>Linux</entry></row> |
1928 | </tbody> | | 1929 | </tbody> |
1929 | </tgroup> | | 1930 | </tgroup> |
1930 | </informaltable> | | 1931 | </informaltable> |
1931 | | | 1932 | |
1932 | <para>To fix these linker errors, it is often sufficient to add | | 1933 | <para>To fix these linker errors, it is often sufficient to add |
1933 | <literal>LIBS.<replaceable>OperatingSystem</replaceable>+= | | 1934 | <literal>LIBS.<replaceable>OperatingSystem</replaceable>+= |
1934 | -l<replaceable>foo</replaceable></literal> to the package | | 1935 | -l<replaceable>foo</replaceable></literal> to the package |
1935 | <filename>Makefile</filename> and then run <command>bmake clean; | | 1936 | <filename>Makefile</filename> and then run <command>bmake clean; |
1936 | bmake</command>.</para> | | 1937 | bmake</command>.</para> |
1937 | | | 1938 | |
1938 | <sect3 id="undefined-reference-sunpro"> | | 1939 | <sect3 id="undefined-reference-sunpro"> |
1939 | <title>The SunPro compiler and inline functions</title> | | 1940 | <title>The SunPro compiler and inline functions</title> |
1940 | | | 1941 | |
1941 | <para>When you are using the SunPro compiler, there is another | | 1942 | <para>When you are using the SunPro compiler, there is another |
1942 | possibility. That compiler cannot handle the following code:</para> | | 1943 | possibility. That compiler cannot handle the following code:</para> |
1943 | | | 1944 | |
1944 | <programlisting> | | 1945 | <programlisting> |
1945 | extern int extern_func(int); | | 1946 | extern int extern_func(int); |
1946 | | | 1947 | |
1947 | static inline int | | 1948 | static inline int |
1948 | inline_func(int x) | | 1949 | inline_func(int x) |
1949 | { | | 1950 | { |
1950 | return extern_func(x); | | 1951 | return extern_func(x); |
1951 | } | | 1952 | } |
1952 | | | 1953 | |
1953 | int main(void) | | 1954 | int main(void) |
1954 | { | | 1955 | { |
1955 | return 0; | | 1956 | return 0; |
1956 | } | | 1957 | } |
1957 | </programlisting> | | 1958 | </programlisting> |
1958 | | | 1959 | |
1959 | <para>It generates the code for <function>inline_func</function> even if | | 1960 | <para>It generates the code for <function>inline_func</function> even if |
1960 | that function is never used. This code then refers to | | 1961 | that function is never used. This code then refers to |
1961 | <function>extern_func</function>, which can usually not be resolved. To | | 1962 | <function>extern_func</function>, which can usually not be resolved. To |
1962 | solve this problem you can try to tell the package to disable inlining | | 1963 | solve this problem you can try to tell the package to disable inlining |
1963 | of functions.</para> | | 1964 | of functions.</para> |
1964 | | | 1965 | |
1965 | </sect3> | | 1966 | </sect3> |
1966 | | | 1967 | |
1967 | <sect3 id="undefined-reference-atomic"> | | 1968 | <sect3 id="undefined-reference-atomic"> |
1968 | <title>Missing atomic functions</title> | | 1969 | <title>Missing atomic functions</title> |
1969 | | | 1970 | |
1970 | <para>When building for older machine architectures (e.g., i386, PowerPC), | | 1971 | <para>When building for older machine architectures (e.g., i386, PowerPC), |
1971 | builds may fail because the package expects modern 64-bit atomic functions | | 1972 | builds may fail because the package expects modern 64-bit atomic functions |
1972 | which the underlying hardware either doesn't support, or will only support | | 1973 | which the underlying hardware either doesn't support, or will only support |
1973 | with specific compiler flags. This is generally handled via inclusion of | | 1974 | with specific compiler flags. This is generally handled via inclusion of |
1974 | mk/atomic64.mk.</para> | | 1975 | mk/atomic64.mk.</para> |
1975 | </sect3> | | 1976 | </sect3> |
1976 | | | 1977 | |
1977 | </sect2> | | 1978 | </sect2> |
1978 | | | 1979 | |
1979 | <sect2 id="out-of-memory"> | | 1980 | <sect2 id="out-of-memory"> |
1980 | <title>Running out of memory</title> | | 1981 | <title>Running out of memory</title> |
1981 | | | 1982 | |
1982 | <para>Sometimes packages fail to build because the compiler runs | | 1983 | <para>Sometimes packages fail to build because the compiler runs |
1983 | into an operating system specific soft limit. With the | | 1984 | into an operating system specific soft limit. With the |
1984 | <varname>UNLIMIT_RESOURCES</varname> variable pkgsrc can be told | | 1985 | <varname>UNLIMIT_RESOURCES</varname> variable pkgsrc can be told |
1985 | to unlimit the resources. The allowed values are any combination of | | 1986 | to unlimit the resources. The allowed values are any combination of |
1986 | <quote>cputime</quote>, | | 1987 | <quote>cputime</quote>, |
1987 | <quote>datasize</quote>, | | 1988 | <quote>datasize</quote>, |
1988 | <quote>memorysize</quote>, | | 1989 | <quote>memorysize</quote>, |
1989 | <quote>stacksize</quote> and | | 1990 | <quote>stacksize</quote> and |
1990 | <quote>virtualsize</quote>. | | 1991 | <quote>virtualsize</quote>. |
1991 | Setting this variable is similar to running the shell builtin | | 1992 | Setting this variable is similar to running the shell builtin |
1992 | <command>ulimit</command> command to raise the maximum data | | 1993 | <command>ulimit</command> command to raise the maximum data |
1993 | segment size or maximum stack size of a process, respectively, to | | 1994 | segment size or maximum stack size of a process, respectively, to |
1994 | their hard limits.</para> | | 1995 | their hard limits.</para> |
1995 | </sect2> | | 1996 | </sect2> |
1996 | </sect1> | | 1997 | </sect1> |
1997 | | | 1998 | |
1998 | <sect1 id="fixes.install"> | | 1999 | <sect1 id="fixes.install"> |
1999 | <title>The <emphasis>install</emphasis> phase</title> | | 2000 | <title>The <emphasis>install</emphasis> phase</title> |
2000 | | | 2001 | |
2001 | <sect2 id="install-scripts"> | | 2002 | <sect2 id="install-scripts"> |
2002 | <title>Creating needed directories</title> | | 2003 | <title>Creating needed directories</title> |
2003 | | | 2004 | |
2004 | <para>The BSD-compatible <command>install</command> supplied | | 2005 | <para>The BSD-compatible <command>install</command> supplied |
2005 | with some operating systems cannot create more than one | | 2006 | with some operating systems cannot create more than one |
2006 | directory at a time. As such, you should call | | 2007 | directory at a time. As such, you should call |
2007 | <literal>${INSTALL_*_DIR}</literal> like this:</para> | | 2008 | <literal>${INSTALL_*_DIR}</literal> like this:</para> |
2008 | | | 2009 | |
2009 | <programlisting> | | 2010 | <programlisting> |
2010 | ${INSTALL_DATA_DIR} ${PREFIX}/dir1 | | 2011 | ${INSTALL_DATA_DIR} ${PREFIX}/dir1 |
2011 | ${INSTALL_DATA_DIR} ${PREFIX}/dir2 | | 2012 | ${INSTALL_DATA_DIR} ${PREFIX}/dir2 |
2012 | </programlisting> | | 2013 | </programlisting> |
2013 | | | 2014 | |
2014 | <para>Instead of running the <command>install</command> commands | | 2015 | <para>Instead of running the <command>install</command> commands |
2015 | directly, you can also append <quote><literal>dir1 | | 2016 | directly, you can also append <quote><literal>dir1 |
2016 | dir2</literal></quote> to the <varname>INSTALLATION_DIRS</varname> | | 2017 | dir2</literal></quote> to the <varname>INSTALLATION_DIRS</varname> |
2017 | variable, which will automatically do the right thing.</para> | | 2018 | variable, which will automatically do the right thing.</para> |
2018 | | | 2019 | |
2019 | </sect2> | | 2020 | </sect2> |
2020 | <sect2 id="where-to-install-documentation"> | | 2021 | <sect2 id="where-to-install-documentation"> |
2021 | <title>Where to install documentation</title> | | 2022 | <title>Where to install documentation</title> |
2022 | | | 2023 | |
2023 | <para>In general, documentation should be installed into | | 2024 | <para>In general, documentation should be installed into |
2024 | <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or | | 2025 | <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or |
2025 | <filename>${PREFIX}/share/doc/${PKGNAME_NOREV}</filename> (the latter | | 2026 | <filename>${PREFIX}/share/doc/${PKGNAME_NOREV}</filename> (the latter |
2026 | includes the version number of the package).</para> | | 2027 | includes the version number of the package).</para> |
2027 | | | 2028 | |
2028 | <para>Many modern packages using GNU autoconf allow to set the | | 2029 | <para>Many modern packages using GNU autoconf allow to set the |
2029 | directory where HTML documentation is installed with the | | 2030 | directory where HTML documentation is installed with the |
2030 | <quote>--with-html-dir</quote> option. Sometimes using this flag is | | 2031 | <quote>--with-html-dir</quote> option. Sometimes using this flag is |
2031 | needed because otherwise the documentation ends up in | | 2032 | needed because otherwise the documentation ends up in |
2032 | <filename>${PREFIX}/share/doc/html</filename> or other places. In | | 2033 | <filename>${PREFIX}/share/doc/html</filename> or other places. In |
2033 | pkgsrc, the HTML documentation should go into the package-specific | | 2034 | pkgsrc, the HTML documentation should go into the package-specific |
2034 | directory, just like any other documentation.</para> | | 2035 | directory, just like any other documentation.</para> |
2035 | | | 2036 | |
2036 | <para>An exception to the above is that library API documentation | | 2037 | <para>An exception to the above is that library API documentation |
2037 | generated with the <filename | | 2038 | generated with the <filename |
2038 | role="pkg">textproc/gtk-doc</filename> tools, for use by special | | 2039 | role="pkg">textproc/gtk-doc</filename> tools, for use by special |
2039 | browsers (devhelp) should be left at their default location, which | | 2040 | browsers (devhelp) should be left at their default location, which |
2040 | is <filename>${PREFIX}/share/gtk-doc</filename>. Such | | 2041 | is <filename>${PREFIX}/share/gtk-doc</filename>. Such |
2041 | documentation can be recognized from files ending in | | 2042 | documentation can be recognized from files ending in |
2042 | <filename>.devhelp</filename> or <filename>.devhelp2</filename>. | | 2043 | <filename>.devhelp</filename> or <filename>.devhelp2</filename>. |
2043 | (It is also acceptable to install such files in | | 2044 | (It is also acceptable to install such files in |
2044 | <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or | | 2045 | <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or |
2045 | <filename>${PREFIX}/share/doc/${PKGNAME}</filename>; the | | 2046 | <filename>${PREFIX}/share/doc/${PKGNAME}</filename>; the |
2046 | <filename>.devhelp*</filename> file must be directly in that | | 2047 | <filename>.devhelp*</filename> file must be directly in that |
2047 | directory then, no additional subdirectory level is allowed in | | 2048 | directory then, no additional subdirectory level is allowed in |
2048 | this case. This is usually achieved by using | | 2049 | this case. This is usually achieved by using |
2049 | <quote>--with-html-dir=${PREFIX}/share/doc</quote>. | | 2050 | <quote>--with-html-dir=${PREFIX}/share/doc</quote>. |
2050 | <filename>${PREFIX}/share/gtk-doc</filename> is preferred | | 2051 | <filename>${PREFIX}/share/gtk-doc</filename> is preferred |
2051 | though.)</para> | | 2052 | though.)</para> |
2052 | | | 2053 | |
2053 | </sect2> | | 2054 | </sect2> |
2054 | | | 2055 | |
2055 | <sect2 id="installing-score-files"> | | 2056 | <sect2 id="installing-score-files"> |
2056 | <title>Installing highscore files</title> | | 2057 | <title>Installing highscore files</title> |
2057 | | | 2058 | |
2058 | <para>Certain packages, most of them in the games category, install | | 2059 | <para>Certain packages, most of them in the games category, install |
2059 | a score file that allows all users on the system to record their | | 2060 | a score file that allows all users on the system to record their |
2060 | highscores. In order for this to work, the binaries need to be | | 2061 | highscores. In order for this to work, the binaries need to be |
2061 | installed setgid and the score files owned by the appropriate | | 2062 | installed setgid and the score files owned by the appropriate |
2062 | group and/or owner (traditionally the "games" user/group). Set | | 2063 | group and/or owner (traditionally the "games" user/group). Set |
2063 | <varname>USE_GAMESGROUP</varname> to yes to support this. The | | 2064 | <varname>USE_GAMESGROUP</varname> to yes to support this. The |
2064 | following variables, documented in more detail in | | 2065 | following variables, documented in more detail in |
2065 | <filename>mk/defaults/mk.conf</filename>, control this | | 2066 | <filename>mk/defaults/mk.conf</filename>, control this |
2066 | behaviour: <varname>GAMEDATAMODE</varname>, | | 2067 | behaviour: <varname>GAMEDATAMODE</varname>, |
2067 | <varname>GAMEDIRMODE</varname>, <varname>GAMES_GROUP</varname>, | | 2068 | <varname>GAMEDIRMODE</varname>, <varname>GAMES_GROUP</varname>, |
2068 | <varname>GAMEMODE</varname>, <varname>GAME_USER</varname>. | | 2069 | <varname>GAMEMODE</varname>, <varname>GAME_USER</varname>. |
2069 | Other useful variables are: <varname>GAMEDIR_PERMS</varname>, | | 2070 | Other useful variables are: <varname>GAMEDIR_PERMS</varname>, |
2070 | <varname>GAMEDATA_PERMS</varname> and | | 2071 | <varname>GAMEDATA_PERMS</varname> and |
2071 | <varname>SETGID_GAMES_PERMS</varname>.</para> | | 2072 | <varname>SETGID_GAMES_PERMS</varname>.</para> |
2072 | | | 2073 | |
2073 | <para>An example that illustrates some of the variables described above is | | 2074 | <para>An example that illustrates some of the variables described above is |
2074 | <filename>games/moon-buggy</filename>. <varname>OWN_DIRS_PERMS</varname> is | | 2075 | <filename>games/moon-buggy</filename>. <varname>OWN_DIRS_PERMS</varname> is |
2075 | used to properly set directory permissions of the directory where the | | 2076 | used to properly set directory permissions of the directory where the |
2076 | scorefile is saved, <varname>REQD_FILES_PERMS</varname> is used to create a | | 2077 | scorefile is saved, <varname>REQD_FILES_PERMS</varname> is used to create a |
2077 | dummy scorefile (<filename>mbscore</filename>) with the proper permissions | | 2078 | dummy scorefile (<filename>mbscore</filename>) with the proper permissions |
2078 | and <varname>SPECIAL_PERMS</varname> is used to install setgid the game | | 2079 | and <varname>SPECIAL_PERMS</varname> is used to install setgid the game |
2079 | binary:</para> | | 2080 | binary:</para> |
2080 | | | 2081 | |
2081 | <programlisting> | | 2082 | <programlisting> |
2082 | USE_GAMESGROUP= yes | | 2083 | USE_GAMESGROUP= yes |
2083 | | | 2084 | |
2084 | BUILD_DEFS+= VARBASE | | 2085 | BUILD_DEFS+= VARBASE |
2085 | | | 2086 | |
2086 | OWN_DIRS_PERMS+= ${VARBASE}/games/moon-buggy ${GAMEDIR_PERMS} | | 2087 | OWN_DIRS_PERMS+= ${VARBASE}/games/moon-buggy ${GAMEDIR_PERMS} |
2087 | REQD_FILES_PERMS+= /dev/null ${VARBASE}/games/moon-buggy/mbscore ${GAMEDATA_PERMS} | | 2088 | REQD_FILES_PERMS+= /dev/null ${VARBASE}/games/moon-buggy/mbscore ${GAMEDATA_PERMS} |
2088 | SPECIAL_PERMS+= ${PREFIX}/bin/moon-buggy ${SETGID_GAMES_PERMS} | | 2089 | SPECIAL_PERMS+= ${PREFIX}/bin/moon-buggy ${SETGID_GAMES_PERMS} |
2089 | </programlisting> | | 2090 | </programlisting> |
2090 | | | 2091 | |
2091 | <para>Various <varname>INSTALL_*</varname> variables are also available: | | 2092 | <para>Various <varname>INSTALL_*</varname> variables are also available: |
2092 | <varname>INSTALL_GAME</varname> to install setgid game binaries, | | 2093 | <varname>INSTALL_GAME</varname> to install setgid game binaries, |
2093 | <varname>INSTALL_GAME_DIR</varname> to install game directories that are | | 2094 | <varname>INSTALL_GAME_DIR</varname> to install game directories that are |
2094 | needed to be accessed by setgid games and | | 2095 | needed to be accessed by setgid games and |
2095 | <varname>INSTALL_GAME_DATA</varname> to install scorefiles.</para> | | 2096 | <varname>INSTALL_GAME_DATA</varname> to install scorefiles.</para> |
2096 | | | 2097 | |
2097 | <para>A package should therefore never hard code file ownership or | | 2098 | <para>A package should therefore never hard code file ownership or |
2098 | access permissions but rely on <varname>*_PERMS</varname> as described above | | 2099 | access permissions but rely on <varname>*_PERMS</varname> as described above |
2099 | or alternatively on <varname>INSTALL_GAME</varname>, | | 2100 | or alternatively on <varname>INSTALL_GAME</varname>, |
2100 | <varname>INSTALL_GAME_DATA</varname> and | | 2101 | <varname>INSTALL_GAME_DATA</varname> and |
2101 | <varname>INSTALL_GAME_DIR</varname> to set these correctly.</para> | | 2102 | <varname>INSTALL_GAME_DIR</varname> to set these correctly.</para> |
2102 | </sect2> | | 2103 | </sect2> |
2103 | | | 2104 | |
2104 | <sect2 id="destdir-support"> | | 2105 | <sect2 id="destdir-support"> |
2105 | <title>Adding DESTDIR support to packages</title> | | 2106 | <title>Adding DESTDIR support to packages</title> |
2106 | | | 2107 | |
2107 | <para><varname>DESTDIR</varname> support means that a package | | 2108 | <para><varname>DESTDIR</varname> support means that a package |
2108 | installs into a staging directory, not the final location of the | | 2109 | installs into a staging directory, not the final location of the |
2109 | files. Then a binary package is created which can be used for | | 2110 | files. Then a binary package is created which can be used for |
2110 | installation as usual. There are two ways: Either the package must | | 2111 | installation as usual. There are two ways: Either the package must |
2111 | install as root (<quote>destdir</quote>) or the package can | | 2112 | install as root (<quote>destdir</quote>) or the package can |
2112 | install as non-root user (<quote>user-destdir</quote>).</para> | | 2113 | install as non-root user (<quote>user-destdir</quote>).</para> |
2113 | | | 2114 | |
2114 | <itemizedlist> | | 2115 | <itemizedlist> |
2115 | <listitem><para><varname>PKG_DESTDIR_SUPPORT</varname> has to be | | 2116 | <listitem><para><varname>PKG_DESTDIR_SUPPORT</varname> has to be |
2116 | set to <quote>destdir</quote> or <quote>user-destdir</quote>. | | 2117 | set to <quote>destdir</quote> or <quote>user-destdir</quote>. |
2117 | By default <varname>PKG_DESTDIR_SUPPORT</varname> | | 2118 | By default <varname>PKG_DESTDIR_SUPPORT</varname> |
2118 | is set to <quote>user-destdir</quote> to help catching more | | 2119 | is set to <quote>user-destdir</quote> to help catching more |
2119 | potential packaging problems. If bsd.prefs.mk is included in the Makefile, | | 2120 | potential packaging problems. If bsd.prefs.mk is included in the Makefile, |
2120 | <varname>PKG_DESTDIR_SUPPORT</varname> needs to be set before | | 2121 | <varname>PKG_DESTDIR_SUPPORT</varname> needs to be set before |
2121 | the inclusion.</para></listitem> | | 2122 | the inclusion.</para></listitem> |
2122 | | | 2123 | |
2123 | <listitem><para>All installation operations have to be prefixed with | | 2124 | <listitem><para>All installation operations have to be prefixed with |
2124 | <filename>${DESTDIR}</filename>.</para></listitem> | | 2125 | <filename>${DESTDIR}</filename>.</para></listitem> |
2125 | | | 2126 | |
2126 | <listitem><para>automake gets this DESTDIR mostly right | | 2127 | <listitem><para>automake gets this DESTDIR mostly right |
2127 | automatically. Many manual rules and pre/post-install often are | | 2128 | automatically. Many manual rules and pre/post-install often are |
2128 | incorrect; fix them.</para></listitem> | | 2129 | incorrect; fix them.</para></listitem> |
2129 | | | 2130 | |
2130 | <listitem><para>If files are installed with special owner/group | | 2131 | <listitem><para>If files are installed with special owner/group |
2131 | use <varname>SPECIAL_PERMS</varname>.</para></listitem> | | 2132 | use <varname>SPECIAL_PERMS</varname>.</para></listitem> |
2132 | | | 2133 | |
2133 | <listitem><para>In general, packages should support | | 2134 | <listitem><para>In general, packages should support |
2134 | <varname>UNPRIVILEGED</varname> to be able to use | | 2135 | <varname>UNPRIVILEGED</varname> to be able to use |
2135 | DESTDIR.</para></listitem> | | 2136 | DESTDIR.</para></listitem> |
2136 | | | 2137 | |
2137 | </itemizedlist> | | 2138 | </itemizedlist> |
2138 | </sect2> | | 2139 | </sect2> |
2139 | | | 2140 | |
2140 | | | 2141 | |
2141 | <sect2 id="hardcoded-paths"> | | 2142 | <sect2 id="hardcoded-paths"> |
2142 | <title>Packages with hardcoded paths to other interpreters</title> | | 2143 | <title>Packages with hardcoded paths to other interpreters</title> |
2143 | | | 2144 | |
2144 | <para>Your package may also contain scripts with hardcoded paths to | | 2145 | <para>Your package may also contain scripts with hardcoded paths to |
2145 | other interpreters besides (or as well as) Perl. To correct the | | 2146 | other interpreters besides (or as well as) Perl. To correct the |
2146 | full pathname to the script interpreter, you need to set the | | 2147 | full pathname to the script interpreter, you need to set the |
2147 | following definitions in your <filename>Makefile</filename> (we | | 2148 | following definitions in your <filename>Makefile</filename> (we |
2148 | shall use <command>tclsh</command> in this example):</para> | | 2149 | shall use <command>tclsh</command> in this example):</para> |
2149 | | | 2150 | |
2150 | <programlisting> | | 2151 | <programlisting> |
2151 | REPLACE_INTERPRETER+= tcl | | 2152 | REPLACE_INTERPRETER+= tcl |
2152 | REPLACE.tcl.old= .*/bin/tclsh | | 2153 | REPLACE.tcl.old= .*/bin/tclsh |
2153 | REPLACE.tcl.new= ${PREFIX}/bin/tclsh | | 2154 | REPLACE.tcl.new= ${PREFIX}/bin/tclsh |
2154 | REPLACE_FILES.tcl= # list of tcl scripts which need to be fixed, | | 2155 | REPLACE_FILES.tcl= # list of tcl scripts which need to be fixed, |
2155 | # relative to ${WRKSRC}, just as in REPLACE_PERL | | 2156 | # relative to ${WRKSRC}, just as in REPLACE_PERL |
2156 | </programlisting> | | 2157 | </programlisting> |
2157 | | | 2158 | |
2158 | </sect2> | | 2159 | </sect2> |
2159 | | | 2160 | |
2160 | | | 2161 | |
2161 | <sect2 id="perl-modules"> | | 2162 | <sect2 id="perl-modules"> |
2162 | <title>Packages installing Perl modules</title> | | 2163 | <title>Packages installing Perl modules</title> |
2163 | | | 2164 | |
2164 | <para>Makefiles of packages providing perl5 modules should include | | 2165 | <para>Makefiles of packages providing perl5 modules should include |
2165 | the Makefile fragment | | 2166 | the Makefile fragment |
2166 | <filename>../../lang/perl5/module.mk</filename>. It provides a | | 2167 | <filename>../../lang/perl5/module.mk</filename>. It provides a |
2167 | <command>do-configure</command> target for the standard perl | | 2168 | <command>do-configure</command> target for the standard perl |
2168 | configuration for such modules as well as various hooks to tune | | 2169 | configuration for such modules as well as various hooks to tune |
2169 | this configuration. See comments in this file for | | 2170 | this configuration. See comments in this file for |
2170 | details.</para> | | 2171 | details.</para> |
2171 | | | 2172 | |
2172 | <para>Perl5 modules will install into different places depending | | 2173 | <para>Perl5 modules will install into different places depending |
2173 | on the version of perl used during the build process. To | | 2174 | on the version of perl used during the build process. To |
2174 | address this, pkgsrc will append lines to the | | 2175 | address this, pkgsrc will append lines to the |
2175 | <filename>PLIST</filename> corresponding to the files listed in | | 2176 | <filename>PLIST</filename> corresponding to the files listed in |
2176 | the installed <filename>.packlist</filename> file generated by | | 2177 | the installed <filename>.packlist</filename> file generated by |
2177 | most perl5 modules. This is invoked by defining | | 2178 | most perl5 modules. This is invoked by defining |
2178 | <varname>PERL5_PACKLIST</varname> to a space-separated list of | | 2179 | <varname>PERL5_PACKLIST</varname> to a space-separated list of |
2179 | packlist files relative to <varname>PERL5_PACKLIST_DIR</varname> | | 2180 | packlist files relative to <varname>PERL5_PACKLIST_DIR</varname> |
2180 | (<varname>PERL5_INSTALLVENDORARCH</varname> by default), | | 2181 | (<varname>PERL5_INSTALLVENDORARCH</varname> by default), |
2181 | e.g.:</para> | | 2182 | e.g.:</para> |
2182 | | | 2183 | |
2183 | <programlisting> | | 2184 | <programlisting> |
2184 | PERL5_PACKLIST= auto/Pg/.packlist | | 2185 | PERL5_PACKLIST= auto/Pg/.packlist |
2185 | </programlisting> | | 2186 | </programlisting> |
2186 | | | 2187 | |
2187 | <para>The perl5 config variables | | 2188 | <para>The perl5 config variables |
2188 | <varname>installarchlib</varname>, | | 2189 | <varname>installarchlib</varname>, |
2189 | <varname>installscript</varname>, | | 2190 | <varname>installscript</varname>, |
2190 | <varname>installvendorbin</varname>, | | 2191 | <varname>installvendorbin</varname>, |
2191 | <varname>installvendorscript</varname>, | | 2192 | <varname>installvendorscript</varname>, |
2192 | <varname>installvendorarch</varname>, | | 2193 | <varname>installvendorarch</varname>, |
2193 | <varname>installvendorlib</varname>, | | 2194 | <varname>installvendorlib</varname>, |
2194 | <varname>installvendorman1dir</varname>, and | | 2195 | <varname>installvendorman1dir</varname>, and |
2195 | <varname>installvendorman3dir</varname> represent those | | 2196 | <varname>installvendorman3dir</varname> represent those |
2196 | locations in which components of perl5 modules may be installed, | | 2197 | locations in which components of perl5 modules may be installed, |
2197 | provided as variable with uppercase and prefixed with | | 2198 | provided as variable with uppercase and prefixed with |
2198 | <varname>PERL5_</varname>, e.g. <varname>PERL5_INSTALLARCHLIB</varname> | | 2199 | <varname>PERL5_</varname>, e.g. <varname>PERL5_INSTALLARCHLIB</varname> |
2199 | and may be used by perl5 packages that don't have a packlist. | | 2200 | and may be used by perl5 packages that don't have a packlist. |
2200 | These variables are also substituted for in the | | 2201 | These variables are also substituted for in the |
2201 | <filename>PLIST</filename> as uppercase prefixed with | | 2202 | <filename>PLIST</filename> as uppercase prefixed with |
2202 | <varname>PERL5_SUB_</varname>.</para> | | 2203 | <varname>PERL5_SUB_</varname>.</para> |
2203 | </sect2> | | 2204 | </sect2> |
2204 | | | 2205 | |
2205 | | | 2206 | |
2206 | <sect2 id="faq.info-files"> | | 2207 | <sect2 id="faq.info-files"> |
2207 | <title>Packages installing info files</title> | | 2208 | <title>Packages installing info files</title> |
2208 | | | 2209 | |
2209 | <para>Some packages install info files or use the | | 2210 | <para>Some packages install info files or use the |
2210 | <quote>makeinfo</quote> or <quote>install-info</quote> | | 2211 | <quote>makeinfo</quote> or <quote>install-info</quote> |
2211 | commands. <varname>INFO_FILES</varname> should be defined in | | 2212 | commands. <varname>INFO_FILES</varname> should be defined in |
2212 | the package Makefile so that <filename>INSTALL</filename> and | | 2213 | the package Makefile so that <filename>INSTALL</filename> and |
2213 | <filename>DEINSTALL</filename> scripts will be generated to | | 2214 | <filename>DEINSTALL</filename> scripts will be generated to |
2214 | handle registration of the info files in the Info directory | | 2215 | handle registration of the info files in the Info directory |
2215 | file. The <quote>install-info</quote> command used for the info | | 2216 | file. The <quote>install-info</quote> command used for the info |
2216 | files registration is either provided by the system, or by a | | 2217 | files registration is either provided by the system, or by a |
2217 | special purpose package automatically added as dependency if | | 2218 | special purpose package automatically added as dependency if |
2218 | needed.</para> | | 2219 | needed.</para> |
2219 | | | 2220 | |
2220 | <para><varname>PKGINFODIR</varname> is the directory under | | 2221 | <para><varname>PKGINFODIR</varname> is the directory under |
2221 | <filename>${PREFIX}</filename> where info files are primarily | | 2222 | <filename>${PREFIX}</filename> where info files are primarily |
2222 | located. <varname>PKGINFODIR</varname> defaults to | | 2223 | located. <varname>PKGINFODIR</varname> defaults to |
2223 | <quote>info</quote> and can be overridden by the user.</para> | | 2224 | <quote>info</quote> and can be overridden by the user.</para> |
2224 | | | 2225 | |
2225 | <para>The info files for the package should be listed in the | | 2226 | <para>The info files for the package should be listed in the |
2226 | package <filename>PLIST</filename>; however any split info files | | 2227 | package <filename>PLIST</filename>; however any split info files |
2227 | need not be listed.</para> | | 2228 | need not be listed.</para> |
2228 | | | 2229 | |
2229 | <para>A package which needs the <quote>makeinfo</quote> command | | 2230 | <para>A package which needs the <quote>makeinfo</quote> command |
2230 | at build time must add <quote>makeinfo</quote> to | | 2231 | at build time must add <quote>makeinfo</quote> to |
2231 | <varname>USE_TOOLS</varname> in its Makefile. If a minimum | | 2232 | <varname>USE_TOOLS</varname> in its Makefile. If a minimum |
2232 | version of the <quote>makeinfo</quote> command is needed it | | 2233 | version of the <quote>makeinfo</quote> command is needed it |
2233 | should be noted with the <varname>TEXINFO_REQD</varname> | | 2234 | should be noted with the <varname>TEXINFO_REQD</varname> |
2234 | variable in the package <filename>Makefile</filename>. By | | 2235 | variable in the package <filename>Makefile</filename>. By |
2235 | default, a minimum version of 3.12 is required. If the system | | 2236 | default, a minimum version of 3.12 is required. If the system |
2236 | does not provide a <command>makeinfo</command> command or if it | | 2237 | does not provide a <command>makeinfo</command> command or if it |
2237 | does not match the required minimum, a build dependency on the | | 2238 | does not match the required minimum, a build dependency on the |
2238 | <filename role="pkg">devel/gtexinfo</filename> package will | | 2239 | <filename role="pkg">devel/gtexinfo</filename> package will |
2239 | be added automatically.</para> | | 2240 | be added automatically.</para> |
2240 | | | 2241 | |
2241 | <para>The build and installation process of the software provided | | 2242 | <para>The build and installation process of the software provided |
2242 | by the package should not use the | | 2243 | by the package should not use the |
2243 | <command>install-info</command> command as the registration of | | 2244 | <command>install-info</command> command as the registration of |
2244 | info files is the task of the package | | 2245 | info files is the task of the package |
2245 | <filename>INSTALL</filename> script, and it must use the | | 2246 | <filename>INSTALL</filename> script, and it must use the |
2246 | appropriate <command>makeinfo</command> command.</para> | | 2247 | appropriate <command>makeinfo</command> command.</para> |
2247 | | | 2248 | |
2248 | <para>To achieve this goal, the pkgsrc infrastructure creates | | 2249 | <para>To achieve this goal, the pkgsrc infrastructure creates |
2249 | overriding scripts for the <command>install-info</command> and | | 2250 | overriding scripts for the <command>install-info</command> and |
2250 | <command>makeinfo</command> commands in a directory listed early | | 2251 | <command>makeinfo</command> commands in a directory listed early |
2251 | in <varname>PATH</varname>.</para> | | 2252 | in <varname>PATH</varname>.</para> |
2252 | | | 2253 | |
2253 | <para>The script overriding <command>install-info</command> has | | 2254 | <para>The script overriding <command>install-info</command> has |
2254 | no effect except the logging of a message. The script overriding | | 2255 | no effect except the logging of a message. The script overriding |
2255 | <command>makeinfo</command> logs a message and according to the | | 2256 | <command>makeinfo</command> logs a message and according to the |
2256 | value of <varname>TEXINFO_REQD</varname> either runs the appropriate | | 2257 | value of <varname>TEXINFO_REQD</varname> either runs the appropriate |
2257 | <command>makeinfo</command> command or exit on error.</para> | | 2258 | <command>makeinfo</command> command or exit on error.</para> |
2258 | </sect2> | | 2259 | </sect2> |
2259 | | | 2260 | |
2260 | <sect2 id="manpages"> | | 2261 | <sect2 id="manpages"> |
2261 | <title>Packages installing man pages</title> | | 2262 | <title>Packages installing man pages</title> |
2262 | | | 2263 | |
2263 | <para>All packages that install manual pages should install them | | 2264 | <para>All packages that install manual pages should install them |
2264 | into the same directory, so that there is one common place to look | | 2265 | into the same directory, so that there is one common place to look |
2265 | for them. In pkgsrc, this place is | | 2266 | for them. In pkgsrc, this place is |
2266 | <literal>${PREFIX}/${PKGMANDIR}</literal>, and this expression | | 2267 | <literal>${PREFIX}/${PKGMANDIR}</literal>, and this expression |
2267 | should be used in packages. The default for | | 2268 | should be used in packages. The default for |
2268 | <varname>PKGMANDIR</varname> is | | 2269 | <varname>PKGMANDIR</varname> is |
2269 | <quote><filename>man</filename></quote>. Another often-used value | | 2270 | <quote><filename>man</filename></quote>. Another often-used value |
2270 | is <quote><filename>share/man</filename></quote>.</para> | | 2271 | is <quote><filename>share/man</filename></quote>.</para> |
2271 | | | 2272 | |
2272 | <note><para>The support for a custom <varname>PKGMANDIR</varname> | | 2273 | <note><para>The support for a custom <varname>PKGMANDIR</varname> |
2273 | is far from complete.</para></note> | | 2274 | is far from complete.</para></note> |
2274 | | | 2275 | |
2275 | <para>The <filename>PLIST</filename> files can just use | | 2276 | <para>The <filename>PLIST</filename> files can just use |
2276 | <filename>man/</filename> as the top level directory for the man | | 2277 | <filename>man/</filename> as the top level directory for the man |
2277 | page file entries, and the pkgsrc framework will convert as | | 2278 | page file entries, and the pkgsrc framework will convert as |
2278 | needed. In all other places, the correct | | 2279 | needed. In all other places, the correct |
2279 | <varname>PKGMANDIR</varname> must be used.</para> | | 2280 | <varname>PKGMANDIR</varname> must be used.</para> |
2280 | | | 2281 | |
2281 | <para>Packages that are | | 2282 | <para>Packages that are |
2282 | configured with <varname>GNU_CONFIGURE</varname> set as | | 2283 | configured with <varname>GNU_CONFIGURE</varname> set as |
2283 | <quote>yes</quote>, by default will use the | | 2284 | <quote>yes</quote>, by default will use the |
2284 | <filename>./configure</filename> | | 2285 | <filename>./configure</filename> |
2285 | --mandir switch to set where the man pages should be installed. | | 2286 | --mandir switch to set where the man pages should be installed. |
2286 | The path is <varname>GNU_CONFIGURE_MANDIR</varname> which defaults | | 2287 | The path is <varname>GNU_CONFIGURE_MANDIR</varname> which defaults |
2287 | to <varname>${PREFIX}/${PKGMANDIR}</varname>.</para> | | 2288 | to <varname>${PREFIX}/${PKGMANDIR}</varname>.</para> |
2288 | | | 2289 | |
2289 | <para>Packages that use <varname>GNU_CONFIGURE</varname> but do not | | 2290 | <para>Packages that use <varname>GNU_CONFIGURE</varname> but do not |
2290 | use --mandir, can set <varname>CONFIGURE_HAS_MANDIR</varname> | | 2291 | use --mandir, can set <varname>CONFIGURE_HAS_MANDIR</varname> |
2291 | to <quote>no</quote>. | | 2292 | to <quote>no</quote>. |
2292 | Or if the <filename>./configure</filename> script uses | | 2293 | Or if the <filename>./configure</filename> script uses |
2293 | a non-standard use of --mandir, you can set | | 2294 | a non-standard use of --mandir, you can set |
2294 | <varname>GNU_CONFIGURE_MANDIR</varname> as needed.</para> | | 2295 | <varname>GNU_CONFIGURE_MANDIR</varname> as needed.</para> |
2295 | | | 2296 | |
2296 | <para>See <xref linkend="manpage-compression"/> for | | 2297 | <para>See <xref linkend="manpage-compression"/> for |
2297 | information on installation of compressed manual pages.</para> | | 2298 | information on installation of compressed manual pages.</para> |
2298 | | | 2299 | |
2299 | </sect2> | | 2300 | </sect2> |
2300 | | | 2301 | |
2301 | <sect2 id="x11-fonts"> | | 2302 | <sect2 id="x11-fonts"> |
2302 | <title>Packages installing X11 fonts</title> | | 2303 | <title>Packages installing X11 fonts</title> |
2303 | | | 2304 | |
2304 | <para>If a package installs font files, you will need to rebuild | | 2305 | <para>If a package installs font files, you will need to rebuild |
2305 | the fonts database in the directory where they get installed at | | 2306 | the fonts database in the directory where they get installed at |
2306 | installation and deinstallation time. This can be automatically | | 2307 | installation and deinstallation time. This can be automatically |
2307 | done by using the pkginstall framework.</para> | | 2308 | done by using the pkginstall framework.</para> |
2308 | | | 2309 | |
2309 | <para>You can list the directories where fonts are installed in the | | 2310 | <para>You can list the directories where fonts are installed in the |
2310 | <varname>FONTS_DIRS.<replaceable>type</replaceable></varname> | | 2311 | <varname>FONTS_DIRS.<replaceable>type</replaceable></varname> |
2311 | variables, where <replaceable>type</replaceable> can be one of | | 2312 | variables, where <replaceable>type</replaceable> can be one of |
2312 | <quote>ttf</quote>, <quote>type1</quote> or <quote>x11</quote>. | | 2313 | <quote>ttf</quote>, <quote>type1</quote> or <quote>x11</quote>. |
2313 | Also make sure that the database file | | 2314 | Also make sure that the database file |
2314 | <filename>fonts.dir</filename> is not listed in the PLIST.</para> | | 2315 | <filename>fonts.dir</filename> is not listed in the PLIST.</para> |
2315 | | | 2316 | |
2316 | <para>Note that you should not create new directories for fonts; | | 2317 | <para>Note that you should not create new directories for fonts; |
2317 | instead use the standard ones to avoid that the user needs to | | 2318 | instead use the standard ones to avoid that the user needs to |
2318 | manually configure his X server to find them.</para> | | 2319 | manually configure his X server to find them.</para> |
2319 | </sect2> | | 2320 | </sect2> |
2320 | | | 2321 | |
2321 | <sect2 id="sgml-xml-data"> | | 2322 | <sect2 id="sgml-xml-data"> |
2322 | <title>Packages installing SGML or XML data</title> | | 2323 | <title>Packages installing SGML or XML data</title> |
2323 | | | 2324 | |
2324 | <para>If a package installs SGML or XML data files that need to be | | 2325 | <para>If a package installs SGML or XML data files that need to be |
2325 | registered in system-wide catalogs (like DTDs, sub-catalogs, | | 2326 | registered in system-wide catalogs (like DTDs, sub-catalogs, |
2326 | etc.), you need to take some extra steps:</para> | | 2327 | etc.), you need to take some extra steps:</para> |
2327 | | | 2328 | |
2328 | <orderedlist> | | 2329 | <orderedlist> |
2329 | <listitem> | | 2330 | <listitem> |
2330 | <para>Include | | 2331 | <para>Include |
2331 | <filename>../../textproc/xmlcatmgr/catalogs.mk</filename> in | | 2332 | <filename>../../textproc/xmlcatmgr/catalogs.mk</filename> in |
2332 | your <filename>Makefile</filename>, which takes care of | | 2333 | your <filename>Makefile</filename>, which takes care of |
2333 | registering those files in system-wide catalogs at | | 2334 | registering those files in system-wide catalogs at |
2334 | installation and deinstallation time.</para> | | 2335 | installation and deinstallation time.</para> |
2335 | </listitem> | | 2336 | </listitem> |
2336 | | | 2337 | |
2337 | <listitem> | | 2338 | <listitem> |
2338 | <para>Set <varname>SGML_CATALOGS</varname> to the full path of | | 2339 | <para>Set <varname>SGML_CATALOGS</varname> to the full path of |
2339 | any SGML catalogs installed by the package.</para> | | 2340 | any SGML catalogs installed by the package.</para> |
2340 | </listitem> | | 2341 | </listitem> |
2341 | | | 2342 | |
2342 | <listitem> | | 2343 | <listitem> |
2343 | <para>Set <varname>XML_CATALOGS</varname> to the full path of | | 2344 | <para>Set <varname>XML_CATALOGS</varname> to the full path of |
2344 | any XML catalogs installed by the package.</para> | | 2345 | any XML catalogs installed by the package.</para> |
2345 | </listitem> | | 2346 | </listitem> |
2346 | | | 2347 | |
2347 | <listitem> | | 2348 | <listitem> |
2348 | <para>Set <varname>SGML_ENTRIES</varname> to individual entries | | 2349 | <para>Set <varname>SGML_ENTRIES</varname> to individual entries |
2349 | to be added to the SGML catalog. These come in groups of | | 2350 | to be added to the SGML catalog. These come in groups of |
2350 | three strings; see xmlcatmgr(1) for more information | | 2351 | three strings; see xmlcatmgr(1) for more information |
2351 | (specifically, arguments recognized by the 'add' action). | | 2352 | (specifically, arguments recognized by the 'add' action). |
2352 | Note that you will normally not use this variable.</para> | | 2353 | Note that you will normally not use this variable.</para> |
2353 | </listitem> | | 2354 | </listitem> |
2354 | | | 2355 | |
2355 | <listitem> | | 2356 | <listitem> |
2356 | <para>Set <varname>XML_ENTRIES</varname> to individual entries | | 2357 | <para>Set <varname>XML_ENTRIES</varname> to individual entries |
2357 | to be added to the XML catalog. These come in groups of three | | 2358 | to be added to the XML catalog. These come in groups of three |
2358 | strings; see xmlcatmgr(1) for more information (specifically, | | 2359 | strings; see xmlcatmgr(1) for more information (specifically, |
2359 | arguments recognized by the 'add' action). Note that you will | | 2360 | arguments recognized by the 'add' action). Note that you will |
2360 | normally not use this variable.</para> | | 2361 | normally not use this variable.</para> |
2361 | </listitem> | | 2362 | </listitem> |
2362 | </orderedlist> | | 2363 | </orderedlist> |
2363 | </sect2> | | 2364 | </sect2> |
2364 | | | 2365 | |
2365 | | | 2366 | |
2366 | <sect2 id="mime-database"> | | 2367 | <sect2 id="mime-database"> |
2367 | <title>Packages installing extensions to the MIME database</title> | | 2368 | <title>Packages installing extensions to the MIME database</title> |
2368 | | | 2369 | |
2369 | <para>If a package provides extensions to the MIME database by | | 2370 | <para>If a package provides extensions to the MIME database by |
2370 | installing <filename>.xml</filename> files inside | | 2371 | installing <filename>.xml</filename> files inside |
2371 | <filename>${PREFIX}/share/mime/packages</filename>, you | | 2372 | <filename>${PREFIX}/share/mime/packages</filename>, you |
2372 | need to take some extra steps to ensure that the database is kept | | 2373 | need to take some extra steps to ensure that the database is kept |
2373 | consistent with respect to these new files:</para> | | 2374 | consistent with respect to these new files:</para> |
2374 | | | 2375 | |
2375 | <orderedlist> | | 2376 | <orderedlist> |
2376 | <listitem> | | 2377 | <listitem> |
2377 | <para>Include | | 2378 | <para>Include |
2378 | <filename>../../databases/shared-mime-info/mimedb.mk</filename> | | 2379 | <filename>../../databases/shared-mime-info/mimedb.mk</filename> |
2379 | (avoid using the <filename>buildlink3.mk</filename> file from | | 2380 | (avoid using the <filename>buildlink3.mk</filename> file from |
2380 | this same directory, which is reserved for inclusion from | | 2381 | this same directory, which is reserved for inclusion from |
2381 | other <filename>buildlink3.mk</filename> files). It takes | | 2382 | other <filename>buildlink3.mk</filename> files). It takes |
2382 | care of rebuilding the MIME database at installation and | | 2383 | care of rebuilding the MIME database at installation and |
2383 | deinstallation time, and disallows any access to it directly | | 2384 | deinstallation time, and disallows any access to it directly |
2384 | from the package.</para> | | 2385 | from the package.</para> |
2385 | </listitem> | | 2386 | </listitem> |
2386 | | | 2387 | |
2387 | <listitem> | | 2388 | <listitem> |
2388 | <para>Check the PLIST and remove any entries under the | | 2389 | <para>Check the PLIST and remove any entries under the |
2389 | <filename>share/mime</filename> directory, | | 2390 | <filename>share/mime</filename> directory, |
2390 | <emphasis>except</emphasis> for files saved under | | 2391 | <emphasis>except</emphasis> for files saved under |
2391 | <filename>share/mime/packages</filename>. The former are | | 2392 | <filename>share/mime/packages</filename>. The former are |
2392 | handled automatically by | | 2393 | handled automatically by |
2393 | the update-mime-database program, but the latter are | | 2394 | the update-mime-database program, but the latter are |
2394 | package-dependent and must be removed by the package that | | 2395 | package-dependent and must be removed by the package that |
2395 | installed them in the first place.</para> | | 2396 | installed them in the first place.</para> |
2396 | </listitem> | | 2397 | </listitem> |
2397 | | | 2398 | |
2398 | <listitem> | | 2399 | <listitem> |
2399 | <para>Remove any <filename>share/mime/*</filename> directories | | 2400 | <para>Remove any <filename>share/mime/*</filename> directories |
2400 | from the PLIST. They will be handled by the shared-mime-info | | 2401 | from the PLIST. They will be handled by the shared-mime-info |
2401 | package.</para> | | 2402 | package.</para> |
2402 | </listitem> | | 2403 | </listitem> |
2403 | </orderedlist> | | 2404 | </orderedlist> |
2404 | </sect2> | | 2405 | </sect2> |
2405 | | | 2406 | |
2406 | | | 2407 | |
2407 | <sect2 id="intltool"> | | 2408 | <sect2 id="intltool"> |
2408 | <title>Packages using intltool</title> | | 2409 | <title>Packages using intltool</title> |
2409 | | | 2410 | |
2410 | <para>If a package uses intltool during its build, add | | 2411 | <para>If a package uses intltool during its build, add |
2411 | <literal>intltool</literal> to the <varname>USE_TOOLS</varname>, | | 2412 | <literal>intltool</literal> to the <varname>USE_TOOLS</varname>, |
2412 | which forces it to use the intltool package provided by pkgsrc, | | 2413 | which forces it to use the intltool package provided by pkgsrc, |
2413 | instead of the one bundled with the distribution file.</para> | | 2414 | instead of the one bundled with the distribution file.</para> |
2414 | | | 2415 | |
2415 | <para>This tracks intltool's build-time dependencies and uses the | | 2416 | <para>This tracks intltool's build-time dependencies and uses the |
2416 | latest available version; this way, the package benefits of any | | 2417 | latest available version; this way, the package benefits of any |
2417 | bug fixes that may have appeared since it was released.</para> | | 2418 | bug fixes that may have appeared since it was released.</para> |
2418 | </sect2> | | 2419 | </sect2> |
2419 | | | 2420 | |
2420 | | | 2421 | |
2421 | <sect2 id="startup-scripts"> | | 2422 | <sect2 id="startup-scripts"> |
2422 | <title>Packages installing startup scripts</title> | | 2423 | <title>Packages installing startup scripts</title> |
2423 | <para>If a package contains a rc.d script, it won't be copied into | | 2424 | <para>If a package contains a rc.d script, it won't be copied into |
2424 | the startup directory by default, but you can enable it, by adding | | 2425 | the startup directory by default, but you can enable it, by adding |
2425 | the option <varname>PKG_RCD_SCRIPTS=YES</varname> in | | 2426 | the option <varname>PKG_RCD_SCRIPTS=YES</varname> in |
2426 | &mk.conf;. This option will copy the scripts | | 2427 | &mk.conf;. This option will copy the scripts |
2427 | into <filename>/etc/rc.d</filename> when a package is installed, and | | 2428 | into <filename>/etc/rc.d</filename> when a package is installed, and |
2428 | it will automatically remove the scripts when the package is | | 2429 | it will automatically remove the scripts when the package is |
2429 | deinstalled.</para> | | 2430 | deinstalled.</para> |
2430 | </sect2> | | 2431 | </sect2> |
2431 | | | 2432 | |
2432 | <sect2 id="tex-packages"> | | 2433 | <sect2 id="tex-packages"> |
2433 | <title>Packages installing TeX modules</title> | | 2434 | <title>Packages installing TeX modules</title> |
2434 | | | 2435 | |
2435 | <para>If a package installs TeX packages into the texmf tree, | | 2436 | <para>If a package installs TeX packages into the texmf tree, |
2436 | the <filename>ls-R</filename> database of the tree needs to be | | 2437 | the <filename>ls-R</filename> database of the tree needs to be |
2437 | updated.</para> | | 2438 | updated.</para> |
2438 | <note><para>Except the main TeX packages such as kpathsea, | | 2439 | <note><para>Except the main TeX packages such as kpathsea, |
2439 | packages should install files | | 2440 | packages should install files |
2440 | into <filename>${PREFIX}/share/texmf-dist</filename>, | | 2441 | into <filename>${PREFIX}/share/texmf-dist</filename>, |
2441 | not <filename>${PREFIX}/share/texmf</filename>.</para></note> | | 2442 | not <filename>${PREFIX}/share/texmf</filename>.</para></note> |
2442 | | | 2443 | |
2443 | <orderedlist> | | 2444 | <orderedlist> |
2444 | <listitem><para>Include | | 2445 | <listitem><para>Include |
2445 | <filename>../../print/kpathsea/texmf.mk</filename>. This | | 2446 | <filename>../../print/kpathsea/texmf.mk</filename>. This |
2446 | takes care of rebuilding the <filename>ls-R</filename> | | 2447 | takes care of rebuilding the <filename>ls-R</filename> |
2447 | database at installation and deinstallation time.</para> | | 2448 | database at installation and deinstallation time.</para> |
2448 | </listitem> | | 2449 | </listitem> |
2449 | | | 2450 | |
2450 | <listitem><para>If your package installs files into a texmf | | 2451 | <listitem><para>If your package installs files into a texmf |
2451 | tree other than the one | | 2452 | tree other than the one |
2452 | at <filename>${PREFIX}/share/texmf-dist</filename>, | | 2453 | at <filename>${PREFIX}/share/texmf-dist</filename>, |
2453 | set <varname>TEX_TEXMF_DIRS</varname> to the list of all texmf | | 2454 | set <varname>TEX_TEXMF_DIRS</varname> to the list of all texmf |
2454 | trees that need database update.</para> | | 2455 | trees that need database update.</para> |
2455 | <para>If your package also installs font map files that need | | 2456 | <para>If your package also installs font map files that need |
2456 | to be registered using <command>updmap</command>, | | 2457 | to be registered using <command>updmap</command>, |
2457 | include <filename>../../print/tex-tetex/map.mk</filename> and | | 2458 | include <filename>../../print/tex-tetex/map.mk</filename> and |
2458 | set <varname>TEX_MAP_FILES</varname> and/or | | 2459 | set <varname>TEX_MAP_FILES</varname> and/or |
2459 | <varname>TEX_MIXEDMAP_FILES</varname> to the list of all | | 2460 | <varname>TEX_MIXEDMAP_FILES</varname> to the list of all |
2460 | such font map files. Then <command>updmap</command> will | | 2461 | such font map files. Then <command>updmap</command> will |