SCM

SCM Repository

[ihelp] Annotation of /src/manual/R-exts-ko.po
ViewVC logotype

Annotation of /src/manual/R-exts-ko.po

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2642 - (view) (download)

1 : gnustats 2463 # Korean translation for translation.ko package
2 : gnustats 1648 # doc/manual/R-exts.texi
3 : gnustats 2463 #
4 : gnustats 1648 # Copyright (C) 2008-2015 Chel Hee Lee, and R Translation Teams
5 : gnustats 1749 #
6 : gnustats 1648 # This file is distributed under the same license as the R distribution.
7 :     # Chel Hee Lee <chl948@mail.usask.ca>, 2008-2015.
8 : gnustats 1336 #
9 : gnustats 2504 # Note that every single contributor listed on the Acknowledgement
10 :     # assigns his or her contribution to Chel Hee Lee.
11 : gnustats 2463 #
12 : gnustats 2504 # Note also that your name may not be found because of incomplete
13 :     # record keeping. If you were overlooked, please let the maintainer
14 :     # know and the list will be updated. Please also contact the mainter
15 :     # of this document in order to voluntarily participate in
16 :     # or offer your help with this work.
17 :     #
18 : gnustats 1336 msgid ""
19 :     msgstr ""
20 : gnustats 2469 "Project-Id-Version: translation.ko_0.0.1.4\n"
21 : gnustats 1336 "Report-Msgid-Bugs-To: chl948@mail.usask.ca\n"
22 : gnustats 2642 "POT-Creation-Date: 2015-09-29 17:38-0600\n"
23 :     "PO-Revision-Date: 2015-09-29 17:38-0600\n"
24 : gnustats 1336 "Last-Translator: Chel Hee Lee <chl948@mail.usask.ca>\n"
25 :     "Language-Team: Chel Hee Lee <chl948@mail.usask.ca>\n"
26 :     "Language: ko\n"
27 :     "MIME-Version: 1.0\n"
28 :     "Content-Type: text/plain; charset=UTF-8\n"
29 :     "Content-Transfer-Encoding: 8bit\n"
30 :     "Plural-Forms: nplurals=1; plural=0;\n"
31 : gnustats 1804
32 : gnustats 1578 #
33 : gnustats 1336 #. type: top
34 : gnustats 1804 #: R-exts.texi:4
35 :     #: R-exts.texi:34
36 :     #: R-exts.texi:52
37 : gnustats 1336 #, no-wrap
38 :     msgid "Writing R Extensions"
39 :     msgstr ""
40 : gnustats 1804
41 : gnustats 1578 #
42 : gnustats 1336 #. type: dircategory
43 : gnustats 1804 #: R-exts.texi:13
44 : gnustats 1336 #, no-wrap
45 :     msgid "Programming"
46 :     msgstr ""
47 : gnustats 1804
48 : gnustats 1578 #
49 : gnustats 1336 #. type: menuentry
50 : gnustats 1804 #: R-exts.texi:16
51 : gnustats 1336 msgid "R Extensions: (R-exts)"
52 :     msgstr ""
53 : gnustats 1804
54 : gnustats 1578 #
55 : gnustats 1336 #. type: menuentry
56 : gnustats 1804 #: R-exts.texi:16
57 : gnustats 1336 msgid "Writing R Extensions."
58 :     msgstr ""
59 : gnustats 1804
60 : gnustats 1578 #
61 : gnustats 1336 #. type: include
62 : gnustats 1804 #: R-exts.texi:20
63 : gnustats 1336 #, no-wrap
64 :     msgid "R-defs.texi"
65 :     msgstr ""
66 : gnustats 1804
67 : gnustats 1578 #
68 : gnustats 1336 #. type: include
69 : gnustats 1804 #: R-exts.texi:21
70 : gnustats 1336 #, no-wrap
71 :     msgid "version.texi"
72 :     msgstr ""
73 : gnustats 1804
74 : gnustats 1578 #
75 : gnustats 1336 #. type: copying
76 : gnustats 1804 #: R-exts.texi:25
77 : gnustats 1336 msgid "This manual is for R, version @value{VERSION}."
78 :     msgstr ""
79 : gnustats 1804
80 : gnustats 1578 #
81 : gnustats 1336 #. type: copying
82 : gnustats 1804 #: R-exts.texi:27
83 : gnustats 1336 msgid "@Rcopyright{1999}"
84 :     msgstr ""
85 : gnustats 1804
86 : gnustats 1578 #
87 : gnustats 1336 #. type: quotation
88 : gnustats 1804 #: R-exts.texi:30
89 : gnustats 1336 msgid "@permission{}"
90 :     msgstr ""
91 : gnustats 1804
92 : gnustats 1578 #
93 : gnustats 1336 #. type: subtitle
94 : gnustats 1804 #: R-exts.texi:35
95 : gnustats 1336 #, no-wrap
96 :     msgid "Version @value{VERSION}"
97 :     msgstr ""
98 : gnustats 1804
99 : gnustats 1578 #
100 : gnustats 1336 #. type: author
101 : gnustats 1804 #: R-exts.texi:36
102 : gnustats 1336 #, no-wrap
103 :     msgid "R Core Team"
104 :     msgstr ""
105 : gnustats 1804
106 : gnustats 1578 #
107 : gnustats 1336 #. type: node
108 : gnustats 1804 #: R-exts.texi:51
109 :     #: R-exts.texi:76
110 :     #: R-exts.texi:85
111 : gnustats 2642 #: R-exts.texi:4976
112 :     #: R-exts.texi:6498
113 :     #: R-exts.texi:7093
114 :     #: R-exts.texi:8349
115 :     #: R-exts.texi:11306
116 :     #: R-exts.texi:12888
117 :     #: R-exts.texi:13062
118 :     #: R-exts.texi:13984
119 :     #: R-exts.texi:13989
120 : gnustats 1336 #, no-wrap
121 :     msgid "Top"
122 :     msgstr ""
123 : gnustats 1804
124 : gnustats 1578 #
125 : gnustats 1336 #. type: node
126 : gnustats 1804 #: R-exts.texi:51
127 :     #: R-exts.texi:74
128 :     #: R-exts.texi:76
129 :     #: R-exts.texi:77
130 :     #: R-exts.texi:85
131 : gnustats 1336 #, no-wrap
132 :     msgid "Acknowledgements"
133 :     msgstr ""
134 : gnustats 1804
135 : gnustats 1578 #
136 : gnustats 1336 #. type: node
137 : gnustats 1804 #: R-exts.texi:51
138 : gnustats 1336 #, no-wrap
139 :     msgid "(dir)"
140 :     msgstr ""
141 : gnustats 1804
142 : gnustats 1578 #
143 : gnustats 1336 #. type: ifnottex
144 : gnustats 1804 #: R-exts.texi:57
145 :     msgid ""
146 :     "This is a guide to extending @R{}, describing the process of creating @R{} "
147 :     "add-on packages, writing @R{} documentation, @R{}'s system and foreign "
148 :     "language interfaces, and the @R{} @acronym{API}."
149 : gnustats 1336 msgstr ""
150 : gnustats 1804
151 : gnustats 1578 #
152 : gnustats 1336 #. type: node
153 : gnustats 1804 #: R-exts.texi:74
154 :     #: R-exts.texi:76
155 :     #: R-exts.texi:85
156 :     #: R-exts.texi:86
157 :     #: R-exts.texi:237
158 : gnustats 2642 #: R-exts.texi:1483
159 :     #: R-exts.texi:2496
160 :     #: R-exts.texi:3042
161 :     #: R-exts.texi:3330
162 :     #: R-exts.texi:3931
163 :     #: R-exts.texi:4592
164 :     #: R-exts.texi:4691
165 :     #: R-exts.texi:4856
166 :     #: R-exts.texi:4924
167 :     #: R-exts.texi:4953
168 :     #: R-exts.texi:4976
169 : gnustats 1336 #, no-wrap
170 :     msgid "Creating R packages"
171 :     msgstr ""
172 : gnustats 1804
173 : gnustats 1578 #
174 : gnustats 1336 #. type: node
175 : gnustats 1804 #: R-exts.texi:74
176 :     #: R-exts.texi:85
177 : gnustats 2642 #: R-exts.texi:4976
178 :     #: R-exts.texi:4977
179 :     #: R-exts.texi:4999
180 :     #: R-exts.texi:5626
181 :     #: R-exts.texi:5667
182 :     #: R-exts.texi:5815
183 :     #: R-exts.texi:5875
184 :     #: R-exts.texi:5927
185 :     #: R-exts.texi:5991
186 :     #: R-exts.texi:6033
187 :     #: R-exts.texi:6079
188 :     #: R-exts.texi:6115
189 :     #: R-exts.texi:6152
190 :     #: R-exts.texi:6186
191 :     #: R-exts.texi:6286
192 :     #: R-exts.texi:6371
193 :     #: R-exts.texi:6437
194 :     #: R-exts.texi:6474
195 :     #: R-exts.texi:6498
196 : gnustats 1336 #, no-wrap
197 :     msgid "Writing R documentation files"
198 :     msgstr ""
199 : gnustats 1804
200 : gnustats 1578 #
201 : gnustats 1336 #. type: node
202 : gnustats 1804 #: R-exts.texi:74
203 : gnustats 2642 #: R-exts.texi:4976
204 :     #: R-exts.texi:6498
205 :     #: R-exts.texi:6499
206 :     #: R-exts.texi:6513
207 :     #: R-exts.texi:6579
208 :     #: R-exts.texi:6693
209 :     #: R-exts.texi:6851
210 :     #: R-exts.texi:7093
211 : gnustats 1336 #, no-wrap
212 :     msgid "Tidying and profiling R code"
213 :     msgstr ""
214 : gnustats 1804
215 : gnustats 1578 #
216 : gnustats 1336 #. type: node
217 : gnustats 1804 #: R-exts.texi:74
218 : gnustats 2642 #: R-exts.texi:6498
219 :     #: R-exts.texi:7093
220 :     #: R-exts.texi:7094
221 :     #: R-exts.texi:7114
222 :     #: R-exts.texi:7193
223 :     #: R-exts.texi:7509
224 :     #: R-exts.texi:8049
225 :     #: R-exts.texi:8051
226 :     #: R-exts.texi:8349
227 : gnustats 1336 #, no-wrap
228 :     msgid "Debugging"
229 :     msgstr ""
230 : gnustats 1804
231 : gnustats 1578 #
232 : gnustats 1336 #. type: node
233 : gnustats 1804 #: R-exts.texi:74
234 : gnustats 2642 #: R-exts.texi:7093
235 :     #: R-exts.texi:8349
236 :     #: R-exts.texi:8350
237 :     #: R-exts.texi:8370
238 :     #: R-exts.texi:8394
239 :     #: R-exts.texi:8563
240 :     #: R-exts.texi:8693
241 :     #: R-exts.texi:8991
242 :     #: R-exts.texi:9108
243 :     #: R-exts.texi:9236
244 :     #: R-exts.texi:9254
245 :     #: R-exts.texi:9427
246 :     #: R-exts.texi:10257
247 :     #: R-exts.texi:10502
248 :     #: R-exts.texi:10939
249 :     #: R-exts.texi:11038
250 :     #: R-exts.texi:11213
251 :     #: R-exts.texi:11234
252 :     #: R-exts.texi:11306
253 : gnustats 1336 #, no-wrap
254 :     msgid "System and foreign language interfaces"
255 :     msgstr ""
256 : gnustats 1804
257 : gnustats 1578 #
258 : gnustats 1336 #. type: node
259 : gnustats 1804 #: R-exts.texi:74
260 : gnustats 2642 #: R-exts.texi:8349
261 :     #: R-exts.texi:11306
262 :     #: R-exts.texi:11398
263 :     #: R-exts.texi:11548
264 :     #: R-exts.texi:11607
265 :     #: R-exts.texi:11664
266 :     #: R-exts.texi:11709
267 :     #: R-exts.texi:11772
268 :     #: R-exts.texi:11845
269 :     #: R-exts.texi:12237
270 :     #: R-exts.texi:12324
271 :     #: R-exts.texi:12411
272 :     #: R-exts.texi:12549
273 :     #: R-exts.texi:12582
274 :     #: R-exts.texi:12611
275 :     #: R-exts.texi:12674
276 :     #: R-exts.texi:12702
277 :     #: R-exts.texi:12760
278 :     #: R-exts.texi:12811
279 :     #: R-exts.texi:12888
280 : gnustats 1336 #, no-wrap
281 :     msgid "The R API"
282 :     msgstr ""
283 : gnustats 1804
284 : gnustats 1578 #
285 : gnustats 1336 #. type: node
286 : gnustats 1804 #: R-exts.texi:74
287 : gnustats 2642 #: R-exts.texi:11306
288 :     #: R-exts.texi:12888
289 :     #: R-exts.texi:12889
290 :     #: R-exts.texi:13022
291 :     #: R-exts.texi:13062
292 : gnustats 1336 #, no-wrap
293 :     msgid "Generic functions and methods"
294 :     msgstr ""
295 : gnustats 1804
296 : gnustats 1578 #
297 : gnustats 1336 #. type: node
298 : gnustats 1804 #: R-exts.texi:74
299 : gnustats 2642 #: R-exts.texi:12888
300 :     #: R-exts.texi:13062
301 :     #: R-exts.texi:13063
302 :     #: R-exts.texi:13086
303 :     #: R-exts.texi:13669
304 :     #: R-exts.texi:13984
305 : gnustats 1336 #, no-wrap
306 :     msgid "Linking GUIs and other front-ends to R"
307 :     msgstr ""
308 : gnustats 1804
309 : gnustats 1578 #
310 : gnustats 1336 #. type: node
311 : gnustats 1804 #: R-exts.texi:74
312 : gnustats 2642 #: R-exts.texi:13062
313 :     #: R-exts.texi:13984
314 :     #: R-exts.texi:13985
315 :     #: R-exts.texi:13989
316 : gnustats 1336 #, no-wrap
317 :     msgid "Function and variable index"
318 :     msgstr ""
319 : gnustats 1804
320 : gnustats 1578 #
321 : gnustats 1336 #. type: unnumbered
322 : gnustats 1804 #: R-exts.texi:74
323 : gnustats 2642 #: R-exts.texi:13984
324 :     #: R-exts.texi:13989
325 :     #: R-exts.texi:13990
326 : gnustats 1336 #, no-wrap
327 :     msgid "Concept index"
328 :     msgstr ""
329 : gnustats 1804
330 : gnustats 1578 #
331 : gnustats 1336 #. type: Plain text
332 : gnustats 1804 #: R-exts.texi:84
333 :     msgid ""
334 :     "The contributions to early versions of this manual by Saikat DebRoy (who "
335 :     "wrote the first draft of a guide to using @code{.Call} and @code{.External}) "
336 :     "and Adrian Trapletti (who provided information on the C++ interface) are "
337 :     "gratefully acknowledged."
338 : gnustats 1336 msgstr ""
339 : gnustats 1804
340 : gnustats 1578 #
341 : gnustats 1336 #. type: cindex
342 : gnustats 1804 #: R-exts.texi:87
343 : gnustats 1336 #, no-wrap
344 :     msgid "Packages"
345 :     msgstr ""
346 : gnustats 1804
347 : gnustats 1578 #
348 : gnustats 1336 #. type: cindex
349 : gnustats 1804 #: R-exts.texi:88
350 : gnustats 1336 #, no-wrap
351 :     msgid "Creating packages"
352 :     msgstr ""
353 : gnustats 1804
354 : gnustats 1578 #
355 : gnustats 1336 #. type: Plain text
356 : gnustats 1804 #: R-exts.texi:93
357 :     msgid ""
358 :     "Packages provide a mechanism for loading optional code, data and "
359 :     "documentation as needed. The @R{} distribution itself includes about 30 "
360 :     "packages."
361 : gnustats 1336 msgstr ""
362 : gnustats 1804
363 : gnustats 1578 #
364 : gnustats 1336 #. type: Plain text
365 : gnustats 1804 #: R-exts.texi:98
366 :     msgid ""
367 :     "In the following, we assume that you know the @code{library()} command, "
368 :     "including its @code{lib.loc} argument, and we also assume basic knowledge of "
369 :     "the @command{R CMD INSTALL} utility. Otherwise, please look at @R{}'s help "
370 :     "pages on"
371 : gnustats 1336 msgstr ""
372 : gnustats 1804
373 : gnustats 1578 #
374 : gnustats 1336 #. type: example
375 : gnustats 1804 #: R-exts.texi:102
376 : gnustats 1336 #, no-wrap
377 :     msgid ""
378 :     "?library\n"
379 :     "?INSTALL\n"
380 :     msgstr ""
381 : gnustats 1804
382 : gnustats 1578 #
383 : gnustats 1336 #. type: Plain text
384 : gnustats 1804 #: R-exts.texi:106
385 : gnustats 1336 msgid "before reading on."
386 :     msgstr ""
387 : gnustats 1804
388 : gnustats 1578 #
389 : gnustats 1336 #. type: Plain text
390 : gnustats 1804 #: R-exts.texi:110
391 :     msgid ""
392 :     "For packages which contain code to be compiled, a computing environment "
393 :     "including a number of tools is assumed; the ``R Installation and "
394 :     "Administration'' manual describes what is needed for each OS."
395 : gnustats 1336 msgstr ""
396 : gnustats 1804
397 : gnustats 1578 #
398 : gnustats 1336 #. type: Plain text
399 : gnustats 1804 #: R-exts.texi:113
400 :     msgid ""
401 :     "Once a source package is created, it must be installed by the command "
402 :     "@code{R CMD INSTALL}."
403 : gnustats 1336 msgstr ""
404 : gnustats 1804
405 : gnustats 1578 #
406 : gnustats 1336 #. type: ifset
407 : gnustats 1804 #: R-exts.texi:116
408 :     msgid ""
409 :     "@xref{Add-on packages, , Add-on-packages, R-admin, R Installation and "
410 :     "Administration}."
411 : gnustats 1336 msgstr ""
412 : gnustats 1804
413 : gnustats 1578 #
414 : gnustats 1336 #. type: Plain text
415 : gnustats 1804 #: R-exts.texi:119
416 :     msgid ""
417 :     "Other types of extensions are supported (but rare): @xref{Package types}."
418 : gnustats 1336 msgstr ""
419 : gnustats 1804
420 : gnustats 1578 #
421 : gnustats 1336 #. type: Plain text
422 : gnustats 1804 #: R-exts.texi:123
423 :     msgid ""
424 :     "Some notes on terminology complete this introduction. These will help with "
425 :     "the reading of this manual, and also in describing concepts accurately when "
426 :     "asking for help."
427 : gnustats 1336 msgstr ""
428 : gnustats 1804
429 : gnustats 1578 #
430 : gnustats 1336 #. type: Plain text
431 : gnustats 1804 #: R-exts.texi:132
432 :     msgid ""
433 :     "A @emph{package} is a directory of files which extend @R{}, a @emph{source "
434 :     "package} (the master files of a package), or a tarball containing the files "
435 :     "of a source package, or an @emph{installed} package, the result of running "
436 :     "@command{R CMD INSTALL} on a source package. On some platforms (notably OS "
437 :     "X and Windows) there are also @emph{binary packages}, a zip file or tarball "
438 :     "containing the files of an installed package which can be unpacked rather "
439 :     "than installing from sources."
440 : gnustats 1336 msgstr ""
441 : gnustats 1804
442 : gnustats 1578 #
443 : gnustats 1336 #. type: Plain text
444 : gnustats 1804 #: R-exts.texi:138
445 :     msgid ""
446 :     "A package is @strong{not}@footnote{although this is a persistent mis-usage. "
447 :     "It seems to stem from S, whose analogues of @R{}'s packages were officially "
448 :     "known as @emph{library sections} and later as @emph{chapters}, but almost "
449 :     "always referred to as @emph{libraries}.} a @emph{library}. The latter is "
450 :     "used in two senses in @R{} documentation."
451 : gnustats 1336 msgstr ""
452 : gnustats 1804
453 : gnustats 1578 #
454 : gnustats 1336 #. type: itemize
455 : gnustats 1804 #: R-exts.texi:147
456 :     msgid ""
457 :     "A directory into which packages are installed, e.g.@: @file{/usr/lib/R/"
458 :     "library}: in that sense it is sometimes referred to as a @emph{library "
459 :     "directory} or @emph{library tree} (since the library is a directory which "
460 :     "contains packages as directories, which themselves contain directories)."
461 : gnustats 1336 msgstr ""
462 : gnustats 1804
463 : gnustats 1578 #
464 : gnustats 1336 #. type: itemize
465 : gnustats 1804 #: R-exts.texi:160
466 :     msgid ""
467 :     "That used by the operating system, as a shared, dynamic or static library or "
468 :     "(especially on Windows) a DLL, where the second L stands for `library'. "
469 :     "Installed packages may contain compiled code in what is known on Unix-alikes "
470 :     "as a @emph{shared object} and on Windows as a DLL. The concept of a "
471 :     "@emph{shared library} (@emph{dynamic library} on OS X) as a collection of "
472 :     "compiled code to which a package might link is also used, especially for "
473 :     "@R{} itself on some platforms. On most platforms these concepts are "
474 :     "interchangeable (shared objects and DLLs can both be loaded into the @R{} "
475 :     "process and be linked against), but OS X distinguishes between shared "
476 :     "objects (extension @file{.so}) and dynamic libraries (extension @file{."
477 :     "dylib})."
478 : gnustats 1336 msgstr ""
479 : gnustats 1804
480 : gnustats 1578 #
481 : gnustats 1336 #. type: Plain text
482 : gnustats 1804 #: R-exts.texi:164
483 : gnustats 1336 msgid "There are a number of well-defined operations on source packages."
484 :     msgstr ""
485 : gnustats 1804
486 : gnustats 1578 #
487 : gnustats 1336 #. type: itemize
488 : gnustats 1804 #: R-exts.texi:171
489 :     msgid ""
490 :     "The most common is @emph{installation} which takes a source package and "
491 :     "installs it in a library using @command{R CMD INSTALL} or @code{install."
492 :     "packages}."
493 : gnustats 1336 msgstr ""
494 : gnustats 1804
495 : gnustats 1578 #
496 : gnustats 1336 #. type: itemize
497 : gnustats 1804 #: R-exts.texi:180
498 :     msgid ""
499 :     "Source packages can be @emph{built}. This involves taking a source "
500 :     "directory and creating a tarball ready for distribution, including cleaning "
501 :     "it up and creating PDF documentation from any @emph{vignettes} it may "
502 :     "contain. Source packages (and most often tarballs) can be @emph{checked}, "
503 :     "when a test installation is done and tested (including running its "
504 :     "examples); also, the contents of the package are tested in various ways for "
505 :     "consistency and portability."
506 : gnustats 1336 msgstr ""
507 : gnustats 1804
508 : gnustats 1578 #
509 : gnustats 1336 #. type: itemize
510 : gnustats 1804 #: R-exts.texi:190
511 :     msgid ""
512 :     "@emph{Compilation} is not a correct term for a package. Installing a source "
513 :     "package which contains C, C++ or Fortran code will involve compiling that "
514 :     "code. There is also the possibility of `byte' compiling the @R{} code in a "
515 :     "package (using the facilities of package @pkg{compiler}): already base and "
516 :     "recommended packages are normally byte-compiled and this can be specified "
517 :     "for other packages. So @emph{compiling} a package may come to mean byte-"
518 :     "compiling its @R{} code."
519 : gnustats 1336 msgstr ""
520 : gnustats 1804
521 : gnustats 1578 #
522 : gnustats 1336 #. type: itemize
523 : gnustats 1804 #: R-exts.texi:200
524 :     msgid ""
525 :     "It used to be unambiguous to talk about @emph{loading} an installed package "
526 :     "using @code{library()}, but since the advent of package namespaces this has "
527 :     "been less clear: people now often talk about @emph{loading} the package's "
528 :     "namespace and then @emph{attaching} the package so it becomes visible on the "
529 :     "search path. Function @code{library} performs both steps, but a package's "
530 :     "namespace can be loaded without the package being attached (for example by "
531 :     "calls like @code{splines::ns})."
532 : gnustats 1336 msgstr ""
533 : gnustats 1804
534 : gnustats 1578 #
535 : gnustats 1336 #. type: Plain text
536 : gnustats 1804 #: R-exts.texi:210
537 :     msgid ""
538 :     "The concept of @emph{lazy loading} of code or data is mentioned at several "
539 :     "points. This is part of the installation, always selected for @R{} code but "
540 :     "optional for data. When used the @R{} objects of the package are created at "
541 :     "installation time and stored in a database in the @file{R} directory of the "
542 :     "installed package, being loaded into the session at first use. This makes "
543 :     "the @R{} session start up faster and use less (virtual) memory."
544 : gnustats 1336 msgstr ""
545 : gnustats 1804
546 : gnustats 1578 #
547 : gnustats 1336 #. type: ifset
548 : gnustats 1804 #: R-exts.texi:213
549 :     msgid ""
550 :     "(For technical details, @pxref{Lazy loading, , Lazy loading, R-ints, R "
551 :     "Internals}.)"
552 : gnustats 1336 msgstr ""
553 : gnustats 1804
554 : gnustats 1578 #
555 : gnustats 1336 #. type: cindex
556 : gnustats 1804 #: R-exts.texi:215
557 : gnustats 1336 #, no-wrap
558 :     msgid "CRAN"
559 :     msgstr ""
560 : gnustats 1804
561 : gnustats 1336 #. type: Plain text
562 : gnustats 1804 #: R-exts.texi:221
563 :     msgid ""
564 :     "@acronym{CRAN} is a network of WWW sites holding the @R{} distributions and "
565 :     "contributed code, especially @R{} packages. Users of @R{} are encouraged to "
566 :     "join in the collaborative project and to submit their own packages to "
567 : gnustats 2640 "@acronym{CRAN}: current instructions are linked from @uref{https://CRAN.R-"
568 : gnustats 1804 "project.org/@/banner.shtml#submitting}."
569 : gnustats 1336 msgstr ""
570 : gnustats 1804
571 : gnustats 1578 #
572 : gnustats 1336 #. type: node
573 : gnustats 1804 #: R-exts.texi:235
574 :     #: R-exts.texi:237
575 :     #: R-exts.texi:238
576 :     #: R-exts.texi:239
577 : gnustats 2180 #: R-exts.texi:335
578 :     #: R-exts.texi:680
579 :     #: R-exts.texi:798
580 :     #: R-exts.texi:1015
581 :     #: R-exts.texi:1034
582 :     #: R-exts.texi:1319
583 :     #: R-exts.texi:1398
584 : gnustats 2642 #: R-exts.texi:1456
585 :     #: R-exts.texi:1483
586 : gnustats 1336 #, no-wrap
587 :     msgid "Package structure"
588 :     msgstr ""
589 : gnustats 1804
590 : gnustats 1578 #
591 : gnustats 1336 #. type: node
592 : gnustats 1804 #: R-exts.texi:235
593 :     #: R-exts.texi:237
594 : gnustats 2642 #: R-exts.texi:1483
595 :     #: R-exts.texi:1484
596 :     #: R-exts.texi:1730
597 :     #: R-exts.texi:2204
598 :     #: R-exts.texi:2339
599 :     #: R-exts.texi:2392
600 :     #: R-exts.texi:2496
601 : gnustats 1336 #, no-wrap
602 :     msgid "Configure and cleanup"
603 :     msgstr ""
604 : gnustats 1804
605 : gnustats 1578 #
606 : gnustats 1336 #. type: node
607 : gnustats 1804 #: R-exts.texi:235
608 : gnustats 2642 #: R-exts.texi:1483
609 :     #: R-exts.texi:2496
610 :     #: R-exts.texi:2497
611 :     #: R-exts.texi:2544
612 :     #: R-exts.texi:2851
613 :     #: R-exts.texi:2975
614 :     #: R-exts.texi:3042
615 : gnustats 1336 #, no-wrap
616 :     msgid "Checking and building packages"
617 :     msgstr ""
618 : gnustats 1804
619 : gnustats 1578 #
620 : gnustats 1336 #. type: node
621 : gnustats 1804 #: R-exts.texi:235
622 : gnustats 2642 #: R-exts.texi:2496
623 :     #: R-exts.texi:3042
624 :     #: R-exts.texi:3043
625 :     #: R-exts.texi:3199
626 :     #: R-exts.texi:3272
627 :     #: R-exts.texi:3330
628 : gnustats 1336 #, no-wrap
629 :     msgid "Writing package vignettes"
630 :     msgstr ""
631 : gnustats 1804
632 : gnustats 1578 #
633 : gnustats 1336 #. type: node
634 : gnustats 1804 #: R-exts.texi:235
635 : gnustats 2642 #: R-exts.texi:3042
636 :     #: R-exts.texi:3330
637 :     #: R-exts.texi:3331
638 :     #: R-exts.texi:3388
639 :     #: R-exts.texi:3470
640 :     #: R-exts.texi:3509
641 :     #: R-exts.texi:3554
642 :     #: R-exts.texi:3737
643 :     #: R-exts.texi:3809
644 :     #: R-exts.texi:3931
645 : gnustats 1336 #, no-wrap
646 :     msgid "Package namespaces"
647 :     msgstr ""
648 : gnustats 1804
649 : gnustats 1578 #
650 : gnustats 1336 #. type: node
651 : gnustats 1804 #: R-exts.texi:235
652 : gnustats 2642 #: R-exts.texi:3330
653 :     #: R-exts.texi:3931
654 :     #: R-exts.texi:3932
655 :     #: R-exts.texi:4276
656 :     #: R-exts.texi:4334
657 :     #: R-exts.texi:4362
658 :     #: R-exts.texi:4429
659 :     #: R-exts.texi:4539
660 :     #: R-exts.texi:4592
661 : gnustats 1336 #, no-wrap
662 :     msgid "Writing portable packages"
663 :     msgstr ""
664 : gnustats 1804
665 : gnustats 1578 #
666 : gnustats 1336 #. type: node
667 : gnustats 1804 #: R-exts.texi:235
668 : gnustats 2642 #: R-exts.texi:3931
669 :     #: R-exts.texi:4592
670 :     #: R-exts.texi:4593
671 :     #: R-exts.texi:4691
672 : gnustats 1336 #, no-wrap
673 :     msgid "Diagnostic messages"
674 :     msgstr ""
675 : gnustats 1804
676 : gnustats 1578 #
677 : gnustats 1336 #. type: node
678 : gnustats 1804 #: R-exts.texi:235
679 : gnustats 2642 #: R-exts.texi:4592
680 :     #: R-exts.texi:4691
681 :     #: R-exts.texi:4692
682 :     #: R-exts.texi:4710
683 :     #: R-exts.texi:4768
684 :     #: R-exts.texi:4795
685 :     #: R-exts.texi:4856
686 : gnustats 1336 #, no-wrap
687 :     msgid "Internationalization"
688 :     msgstr ""
689 : gnustats 1804
690 : gnustats 1578 #
691 : gnustats 1336 #. type: node
692 : gnustats 1804 #: R-exts.texi:235
693 : gnustats 2642 #: R-exts.texi:4691
694 :     #: R-exts.texi:4856
695 :     #: R-exts.texi:4857
696 :     #: R-exts.texi:4924
697 : gnustats 1336 #, no-wrap
698 :     msgid "CITATION files"
699 :     msgstr ""
700 : gnustats 1804
701 : gnustats 1578 #
702 : gnustats 1336 #. type: node
703 : gnustats 1804 #: R-exts.texi:235
704 : gnustats 2642 #: R-exts.texi:4856
705 :     #: R-exts.texi:4924
706 :     #: R-exts.texi:4925
707 :     #: R-exts.texi:4936
708 :     #: R-exts.texi:4953
709 : gnustats 1336 #, no-wrap
710 :     msgid "Package types"
711 :     msgstr ""
712 : gnustats 1804
713 : gnustats 1578 #
714 : gnustats 1336 #. type: section
715 : gnustats 1804 #: R-exts.texi:235
716 : gnustats 2642 #: R-exts.texi:4924
717 :     #: R-exts.texi:4953
718 :     #: R-exts.texi:4954
719 : gnustats 1336 #, no-wrap
720 :     msgid "Services"
721 :     msgstr ""
722 : gnustats 1804
723 : gnustats 1578 #
724 : gnustats 1336 #. type: Plain text
725 : gnustats 1804 #: R-exts.texi:259
726 :     msgid ""
727 :     "The sources of an @R{} package consists of a subdirectory containing a files "
728 :     "@file{DESCRIPTION} and @file{NAMESPACE}, and the subdirectories @file{R}, "
729 :     "@file{data}, @file{demo}, @file{exec}, @file{inst}, @file{man}, @file{po}, "
730 :     "@file{src}, @file{tests}, @file{tools} and @file{vignettes} (some of which "
731 :     "can be missing, but which should not be empty). The package subdirectory "
732 :     "may also contain files @file{INDEX}, @file{configure}, @file{cleanup}, "
733 :     "@file{LICENSE}, @file{LICENCE} and @file{NEWS}. Other files such as "
734 :     "@file{INSTALL} (for non-standard installation instructions), @file{README}/"
735 :     "@file{README.md}@footnote{This seems to be commonly used for a file in "
736 :     "`markdown' format. Be aware that most users of @R{} will not know that, nor "
737 :     "know how to view such a file: platforms such as OS X and Windows do not have "
738 :     "a default viewer set in their file associations. The @acronym{CRAN} package "
739 :     "web pages render such files in @HTML{}: the converter used expects the file "
740 :     "to be encoded in UTF-8.}, or @file{ChangeLog} will be ignored by @R{}, but "
741 :     "may be useful to end users. The utility @command{R CMD build} may add files "
742 :     "in a @file{build} directory (but this should not be used for other purposes)."
743 : gnustats 1336 msgstr ""
744 : gnustats 1804
745 : gnustats 1578 #
746 : gnustats 1336 #. type: Plain text
747 : gnustats 1804 #: R-exts.texi:265
748 :     msgid ""
749 :     "Except where specifically mentioned,@footnote{currently, top-level files "
750 :     "@file{.Rbuildignore} and @file{.Rinstignore}, and @file{vignettes/."
751 :     "install_extras}.} packages should not contain Unix-style `hidden' files/"
752 :     "directories (that is, those whose name starts with a dot)."
753 : gnustats 1336 msgstr ""
754 : gnustats 1804
755 : gnustats 1578 #
756 : gnustats 1336 #. type: Plain text
757 : gnustats 1804 #: R-exts.texi:269
758 :     msgid ""
759 :     "The @file{DESCRIPTION} and @file{INDEX} files are described in the "
760 :     "subsections below. The @file{NAMESPACE} file is described in the section on "
761 :     "@ref{Package namespaces}."
762 : gnustats 1336 msgstr ""
763 : gnustats 1804
764 : gnustats 1578 #
765 : gnustats 1336 #. type: cindex
766 : gnustats 1804 #: R-exts.texi:270
767 : gnustats 1336 #, no-wrap
768 :     msgid "configure file"
769 :     msgstr ""
770 : gnustats 1804
771 : gnustats 1578 #
772 : gnustats 1336 #. type: cindex
773 : gnustats 1804 #: R-exts.texi:271
774 : gnustats 1336 #, no-wrap
775 :     msgid "cleanup file"
776 :     msgstr ""
777 : gnustats 1804
778 : gnustats 1578 #
779 : gnustats 1336 #. type: Plain text
780 : gnustats 1804 #: R-exts.texi:278
781 :     msgid ""
782 :     "The optional files @file{configure} and @file{cleanup} are (Bourne shell) "
783 :     "script files which are, respectively, executed before and (provided that "
784 :     "option @option{--clean} was given) after installation on Unix-alikes, see "
785 :     "@ref{Configure and cleanup}. The analogues on Windows are @file{configure."
786 :     "win} and @file{cleanup.win}."
787 : gnustats 1336 msgstr ""
788 : gnustats 1804
789 : gnustats 1336 #. type: Plain text
790 : gnustats 1804 #: R-exts.texi:282
791 :     msgid ""
792 :     "For the conventions for files @file{NEWS} and @file{ChangeLog} in the "
793 : gnustats 2640 "@acronym{GNU} project see @uref{https://www.gnu.org/@/prep/@/standards/@/"
794 : gnustats 1804 "standards.html#Documentation}."
795 : gnustats 1336 msgstr ""
796 : gnustats 1804
797 : gnustats 1578 #
798 : gnustats 1336 #. type: Plain text
799 : gnustats 1804 #: R-exts.texi:289
800 :     msgid ""
801 :     "The package subdirectory should be given the same name as the package. "
802 :     "Because some file systems (e.g., those on Windows and by default on OS X) "
803 :     "are not case-sensitive, to maintain portability it is strongly recommended "
804 :     "that case distinctions not be used to distinguish different packages. For "
805 :     "example, if you have a package named @file{foo}, do not also create a "
806 :     "package named @file{Foo}."
807 : gnustats 1336 msgstr ""
808 : gnustats 1804
809 : gnustats 1578 #
810 : gnustats 1336 #. type: Plain text
811 : gnustats 1804 #: R-exts.texi:311
812 :     msgid ""
813 :     "To ensure that file names are valid across file systems and supported "
814 :     "operating systems, the @acronym{ASCII} control characters as well as the "
815 :     "characters @samp{\"}, @samp{*}, @samp{:}, @samp{/}, @samp{<}, @samp{>}, "
816 :     "@samp{?}, @samp{\\}, and @samp{|} are not allowed in file names. In "
817 :     "addition, files with names @samp{con}, @samp{prn}, @samp{aux}, @samp{clock"
818 :     "$}, @samp{nul}, @samp{com1} to @samp{com9}, and @samp{lpt1} to @samp{lpt9} "
819 :     "after conversion to lower case and stripping possible ``extensions'' (e.g., "
820 :     "@samp{lpt5.foo.bar}), are disallowed. Also, file names in the same "
821 :     "directory must not differ only by case (see the previous paragraph). In "
822 :     "addition, the basenames of @samp{.Rd} files may be used in URLs and so must "
823 :     "be @acronym{ASCII} and not contain @code{%}. For maximal portability "
824 :     "filenames should only contain only @acronym{ASCII} characters not excluded "
825 :     "already (that is @code{A-Za-z0-9._!#$%&+,;=@@^()@{@}'[]} --- we exclude "
826 :     "space as many utilities do not accept spaces in file paths): non-English "
827 :     "alphabetic characters cannot be guaranteed to be supported in all locales. "
828 :     "It would be good practice to avoid the shell metacharacters "
829 :     "@code{()@{@}'[]$~}: @code{~} is also used as part of `8.3' filenames on "
830 :     "Windows. In addition, packages are normally distributed as tarballs, and "
831 :     "these have a limit on path lengths: for maximal portability 100 bytes."
832 : gnustats 1336 msgstr ""
833 : gnustats 1804
834 : gnustats 1578 #
835 : gnustats 1336 #. type: Plain text
836 : gnustats 1804 #: R-exts.texi:320
837 :     msgid ""
838 :     "A source package if possible should not contain binary executable files: "
839 :     "they are not portable, and a security risk if they are of the appropriate "
840 :     "architecture. @command{R CMD check} will warn about them@footnote{false "
841 :     "positives are possible, but only a handful have been seen so far.} unless "
842 :     "they are listed (one filepath per line) in a file @file{BinaryFiles} at the "
843 :     "top level of the package. Note that @acronym{CRAN} will not accept "
844 :     "submissions containing binary files even if they are listed."
845 : gnustats 1336 msgstr ""
846 : gnustats 1804
847 : gnustats 1578 #
848 : gnustats 1336 #. type: Plain text
849 : gnustats 1804 #: R-exts.texi:323
850 :     msgid ""
851 :     "The @R{} function @code{package.skeleton} can help to create the structure "
852 :     "for a new package: see its help page for details."
853 : gnustats 1336 msgstr ""
854 : gnustats 1804
855 : gnustats 1578 #
856 : gnustats 1336 #. type: node
857 : gnustats 2180 #: R-exts.texi:333
858 :     #: R-exts.texi:335
859 :     #: R-exts.texi:680
860 : gnustats 1336 #, no-wrap
861 :     msgid "The DESCRIPTION file"
862 :     msgstr ""
863 : gnustats 1804
864 : gnustats 1578 #
865 : gnustats 1336 #. type: node
866 : gnustats 2180 #: R-exts.texi:333
867 :     #: R-exts.texi:335
868 :     #: R-exts.texi:680
869 :     #: R-exts.texi:681
870 :     #: R-exts.texi:798
871 : gnustats 1336 #, no-wrap
872 :     msgid "Licensing"
873 :     msgstr ""
874 : gnustats 1804
875 : gnustats 1578 #
876 : gnustats 1336 #. type: node
877 : gnustats 2180 #: R-exts.texi:333
878 :     #: R-exts.texi:680
879 :     #: R-exts.texi:798
880 :     #: R-exts.texi:799
881 :     #: R-exts.texi:983
882 :     #: R-exts.texi:1015
883 : gnustats 1336 #, no-wrap
884 :     msgid "Package Dependencies"
885 :     msgstr ""
886 : gnustats 1804
887 : gnustats 1578 #
888 : gnustats 1336 #. type: node
889 : gnustats 2180 #: R-exts.texi:333
890 :     #: R-exts.texi:798
891 :     #: R-exts.texi:1015
892 :     #: R-exts.texi:1034
893 : gnustats 1336 #, no-wrap
894 :     msgid "The INDEX file"
895 :     msgstr ""
896 : gnustats 1804
897 : gnustats 1578 #
898 : gnustats 1336 #. type: node
899 : gnustats 2180 #: R-exts.texi:333
900 :     #: R-exts.texi:1015
901 : gnustats 2054 #: R-exts.texi:1034
902 : gnustats 2180 #: R-exts.texi:1035
903 :     #: R-exts.texi:1036
904 :     #: R-exts.texi:1319
905 : gnustats 1336 #, no-wrap
906 :     msgid "Package subdirectories"
907 :     msgstr ""
908 : gnustats 1804
909 : gnustats 1578 #
910 : gnustats 1336 #. type: node
911 : gnustats 2180 #: R-exts.texi:333
912 :     #: R-exts.texi:1034
913 :     #: R-exts.texi:1319
914 :     #: R-exts.texi:1320
915 :     #: R-exts.texi:1398
916 : gnustats 1336 #, no-wrap
917 :     msgid "Data in packages"
918 :     msgstr ""
919 : gnustats 1804
920 : gnustats 1578 #
921 : gnustats 2180 #. type: node
922 :     #: R-exts.texi:333
923 :     #: R-exts.texi:1319
924 :     #: R-exts.texi:1398
925 :     #: R-exts.texi:1399
926 : gnustats 2642 #: R-exts.texi:1456
927 : gnustats 1336 #, no-wrap
928 :     msgid "Non-R scripts in packages"
929 :     msgstr ""
930 : gnustats 1804
931 : gnustats 2180 #. type: subsection
932 :     #: R-exts.texi:333
933 :     #: R-exts.texi:1398
934 : gnustats 2642 #: R-exts.texi:1456
935 :     #: R-exts.texi:1457
936 : gnustats 2180 #, no-wrap
937 :     msgid "Specifying URLs"
938 :     msgstr ""
939 :    
940 : gnustats 1578 #
941 : gnustats 1336 #. type: subsection
942 : gnustats 2180 #: R-exts.texi:336
943 : gnustats 1336 #, no-wrap
944 :     msgid "The @file{DESCRIPTION} file"
945 :     msgstr ""
946 : gnustats 1804
947 : gnustats 1578 #
948 : gnustats 1336 #. type: cindex
949 : gnustats 2180 #: R-exts.texi:337
950 : gnustats 1336 #, no-wrap
951 :     msgid "DESCRIPTION file"
952 :     msgstr ""
953 : gnustats 1804
954 : gnustats 1578 #
955 : gnustats 1336 #. type: Plain text
956 : gnustats 2180 #: R-exts.texi:341
957 : gnustats 1804 msgid ""
958 :     "The @file{DESCRIPTION} file contains basic information about the package in "
959 :     "the following format:"
960 : gnustats 1336 msgstr ""
961 : gnustats 1804
962 : gnustats 1336 #. type: smallexample
963 : gnustats 2180 #: R-exts.texi:365
964 : gnustats 1336 #, no-wrap
965 :     msgid ""
966 :     "Package: pkgname\n"
967 :     "Version: 0.5-1\n"
968 :     "Date: 2015-01-01\n"
969 :     "Title: My First Collection of Functions\n"
970 :     "Authors@@R: c(person(\"Joe\", \"Developer\", role = c(\"aut\", \"cre\"),\n"
971 :     "\t\t email = \"Joe.Developer@@some.domain.net\"),\n"
972 :     "\t person(\"Pat\", \"Developer\", role = \"aut\"),\n"
973 :     "\t person(\"A.\", \"User\", role = \"ctb\",\n"
974 :     "\t\t email = \"A.User@@whereever.net\"))\n"
975 :     "Author: Joe Developer [aut, cre],\n"
976 :     " Pat Developer [aut],\n"
977 :     " A. User [ctb]\n"
978 :     "Maintainer: Joe Developer <Joe.Developer@@some.domain.net>\n"
979 :     "Depends: R (>= 3.1.0), nlme\n"
980 :     "Suggests: MASS\n"
981 :     "Description: A (one paragraph) description of what\n"
982 :     " the package does and why it may be useful.\n"
983 :     "License: GPL (>= 2)\n"
984 : gnustats 2642 "URL: https://www.r-project.org, http://www.another.url\n"
985 : gnustats 2640 "BugReports: https://pkgname.bugtracker.url\n"
986 : gnustats 1336 msgstr ""
987 : gnustats 1804
988 : gnustats 1336 #. type: Plain text
989 : gnustats 2180 #: R-exts.texi:379
990 : gnustats 1804 msgid ""
991 :     "The format is that of a version of a `Debian Control File' (see the help for "
992 : gnustats 2640 "@samp{read.dcf} and @uref{https://www.debian.org/@/doc/@/debian-policy/@/ch-"
993 : gnustats 1804 "controlfields.html}: @R{} does not require encoding in UTF-8 and does not "
994 :     "support comments starting with @samp{#}). Fields start with an "
995 :     "@acronym{ASCII} name immediately followed by a colon: the value starts after "
996 :     "the colon and a space. Continuation lines (for example, for descriptions "
997 :     "longer than one line) start with a space or tab. Field names are case-"
998 :     "sensitive: all those used by @R{} are capitalized."
999 : gnustats 1336 msgstr ""
1000 : gnustats 1804
1001 : gnustats 1578 #
1002 : gnustats 1336 #. type: Plain text
1003 : gnustats 2180 #: R-exts.texi:383
1004 : gnustats 1804 msgid ""
1005 :     "For maximal portability, the @file{DESCRIPTION} file should be written "
1006 :     "entirely in @acronym{ASCII} --- if this is not possible it must contain an "
1007 :     "@samp{Encoding} field (see below)."
1008 : gnustats 1336 msgstr ""
1009 : gnustats 1804
1010 : gnustats 1578 #
1011 : gnustats 1336 #. type: Plain text
1012 : gnustats 2180 #: R-exts.texi:387
1013 : gnustats 1804 msgid ""
1014 :     "Several optional fields take @emph{logical values}: these can be specified "
1015 :     "as @samp{yes}, @samp{true}, @samp{no} or @samp{false}: capitalized values "
1016 :     "are also accepted."
1017 : gnustats 1336 msgstr ""
1018 : gnustats 1804
1019 : gnustats 1578 #
1020 : gnustats 1336 #. type: Plain text
1021 : gnustats 2180 #: R-exts.texi:394
1022 : gnustats 1804 msgid ""
1023 :     "The @samp{Package}, @samp{Version}, @samp{License}, @samp{Description}, "
1024 :     "@samp{Title}, @samp{Author}, and @samp{Maintainer} fields are mandatory, all "
1025 :     "other fields are optional. Fields @samp{Author} and @samp{Maintainer} can "
1026 :     "be auto-generated from @samp{Authors@@R}, and may be omitted if the latter "
1027 :     "is provided: however if they are not @acronym{ASCII} we recommend that they "
1028 :     "are provided."
1029 : gnustats 1336 msgstr ""
1030 : gnustats 1804
1031 : gnustats 1578 #
1032 : gnustats 1336 #. type: Plain text
1033 : gnustats 2180 #: R-exts.texi:401
1034 : gnustats 1804 msgid ""
1035 :     "The mandatory @samp{Package} field gives the name of the package. This "
1036 :     "should contain only (@acronym{ASCII}) letters, numbers and dot, have at "
1037 :     "least two characters and start with a letter and not end in a dot. If it "
1038 :     "needs explaining, this should be done in the @samp{Description} field (and "
1039 :     "not the @samp{Title} field)."
1040 : gnustats 1336 msgstr ""
1041 : gnustats 1804
1042 : gnustats 1578 #
1043 : gnustats 1336 #. type: Plain text
1044 : gnustats 2180 #: R-exts.texi:410
1045 : gnustats 1804 msgid ""
1046 :     "The mandatory @samp{Version} field gives the version of the package. This "
1047 :     "is a sequence of at least @emph{two} (and usually three) non-negative "
1048 :     "integers separated by single @samp{.} or @samp{-} characters. The canonical "
1049 :     "form is as shown in the example, and a version such as @samp{0.01} or "
1050 :     "@samp{0.01.0} will be handled as if it were @samp{0.1-0}. It is "
1051 :     "@strong{not} a decimal number, so for example @code{0.9 < 0.75} since "
1052 :     "@code{9 < 75}."
1053 : gnustats 1336 msgstr ""
1054 : gnustats 1804
1055 : gnustats 1578 #
1056 : gnustats 1336 #. type: Plain text
1057 : gnustats 2180 #: R-exts.texi:412
1058 : gnustats 1336 msgid "The mandatory @samp{License} field is discussed in the next subsection."
1059 :     msgstr ""
1060 : gnustats 1804
1061 : gnustats 1336 #. type: Plain text
1062 : gnustats 2180 #: R-exts.texi:423
1063 : gnustats 1804 msgid ""
1064 :     "The mandatory @samp{Title} field should give a @emph{short} description of "
1065 :     "the package. Some package listings may truncate the title to 65 "
1066 :     "characters. It should use @emph{title case} (that is, use capitals for the "
1067 :     "principal words: @code{tools::toTitleCase} can help you with this), not use "
1068 :     "any markup, not have any continuation lines, and not end in a period (unless "
1069 :     "part of @dots{}). Do not repeat the package name: it is often used prefixed "
1070 : gnustats 1976 "by the name. Refer to other packages and external software in single "
1071 : gnustats 1815 "quotes, and to book titles (and similar) in double quotes."
1072 : gnustats 1336 msgstr ""
1073 : gnustats 1804
1074 : gnustats 1839 #. type: Plain text
1075 : gnustats 2180 #: R-exts.texi:437
1076 : gnustats 1839 msgid ""
1077 :     "The mandatory @samp{Description} field should give a @emph{comprehensive} "
1078 :     "description of what the package does. One can use several (complete) "
1079 :     "sentences, but only one paragraph. It should be intelligible to all the "
1080 :     "intended readership (e.g.@: for a @acronym{CRAN} package to all "
1081 : gnustats 1976 "@acronym{CRAN} users). It is good practice not to start with the package "
1082 :     "name, `This package' or similar. As with the @samp{Title} field, double "
1083 :     "quotes should be used for quotations (including titles of books and "
1084 :     "articles), and single quotes for non-English usage, including names of other "
1085 :     "packages and external software. This field should also be used for "
1086 : gnustats 2180 "explaining the package name if necessary. URLs should be enclosed in angle "
1087 : gnustats 2642 "brackets, e.g.@: @samp{<https://www.r-project.org>}: see also "
1088 :     "@ref{Specifying URLs}."
1089 : gnustats 1839 msgstr ""
1090 :    
1091 : gnustats 1578 #
1092 : gnustats 1336 #. type: Plain text
1093 : gnustats 2180 #: R-exts.texi:447
1094 : gnustats 1804 msgid ""
1095 :     "The mandatory @samp{Author} field describes who wrote @emph{the package}. "
1096 :     "It is a plain text field intended for human readers, but not for automatic "
1097 :     "processing (such as extracting the email addresses of all listed "
1098 :     "contributors: for that use @samp{Authors@@R}). Note that all significant "
1099 :     "contributors must be included: if you wrote an @R{} wrapper for the work of "
1100 :     "others included in the @file{src} directory, you are not the sole (and maybe "
1101 :     "not even the main) author."
1102 : gnustats 1336 msgstr ""
1103 : gnustats 1804
1104 : gnustats 1578 #
1105 : gnustats 1336 #. type: Plain text
1106 : gnustats 2180 #: R-exts.texi:456
1107 : gnustats 1804 msgid ""
1108 :     "The mandatory @samp{Maintainer} field should give a @emph{single} name "
1109 :     "followed by a @emph{valid} (RFC 2822) email address in angle brackets. It "
1110 :     "should not end in a period or comma. This field is what is reported by the "
1111 :     "@code{maintainer} function and used by @code{bug.report}. For a "
1112 :     "@acronym{CRAN} package it should be a @emph{person}, not a mailing list and "
1113 :     "not a corporate entity: do ensure that it is valid and will remain valid for "
1114 :     "the lifetime of the package."
1115 : gnustats 1336 msgstr ""
1116 : gnustats 1804
1117 : gnustats 1578 #
1118 : gnustats 1336 #. type: Plain text
1119 : gnustats 2180 #: R-exts.texi:461
1120 : gnustats 1804 msgid ""
1121 :     "Note that the @emph{display name} (the part before the address in angle "
1122 :     "brackets) should be enclosed in double quotes if it contains non-"
1123 :     "alphanumeric characters such as comma or period. (The current standard, RFC "
1124 :     "5322, allows periods but RFC 2822 did not.)"
1125 : gnustats 1336 msgstr ""
1126 : gnustats 1804
1127 : gnustats 1578 #
1128 : gnustats 1336 #. type: Plain text
1129 : gnustats 2180 #: R-exts.texi:478
1130 : gnustats 1804 msgid ""
1131 :     "Both @samp{Author} and @samp{Maintainer} fields can be omitted if a suitable "
1132 :     "@samp{Authors@@R} field is given. This field can be used to provide a "
1133 :     "refined and machine-readable description of the package ``authors'' (in "
1134 :     "particular specifying their precise @emph{roles}), via suitable @R{} code. "
1135 :     "It should create an object of class @code{\"person'}, by either a call to "
1136 :     "@code{person} or a series of calls (one per ``author'') concatenated by "
1137 :     "@code{c()}): see the example @file{DESCRIPTION} file above. The roles can "
1138 :     "include @samp{\"aut\"} (author) for full authors, @samp{\"cre\"} (creator) "
1139 :     "for the package maintainer, and @samp{\"ctb\"} (contributor) for other "
1140 :     "contributors, @samp{\"cph\"} (copyright holder), among others. See @code{?"
1141 :     "person} for more information. Note that no role is assumed by default. "
1142 :     "Auto-generated package citation information takes advantage of this "
1143 :     "specification. The @samp{Author} and @samp{Maintainer} fields are auto-"
1144 :     "generated from it if needed when building@footnote{at least if this is done "
1145 :     "in a locale which matches the package encoding.} or installing."
1146 : gnustats 1336 msgstr ""
1147 : gnustats 1804
1148 : gnustats 1578 #
1149 : gnustats 1336 #. type: findex
1150 : gnustats 2180 #: R-exts.texi:479
1151 :     #: R-exts.texi:1266
1152 : gnustats 1336 #, no-wrap
1153 :     msgid "COPYRIGHTS"
1154 :     msgstr ""
1155 : gnustats 1804
1156 : gnustats 1578 #
1157 : gnustats 1336 #. type: Plain text
1158 : gnustats 2180 #: R-exts.texi:484
1159 : gnustats 1804 msgid ""
1160 :     "An optional @samp{Copyright} field can be used where the copyright holder(s) "
1161 :     "are not the authors. If necessary, this can refer to an installed file: the "
1162 :     "convention is to use file @file{inst/COPYRIGHTS}."
1163 : gnustats 1336 msgstr ""
1164 : gnustats 1804
1165 : gnustats 1336 #. type: Plain text
1166 : gnustats 2180 #: R-exts.texi:491
1167 : gnustats 1804 msgid ""
1168 : gnustats 2054 "The optional @samp{Date} field gives the @emph{release date} of the current "
1169 :     "version of the package. It is strongly recommended@footnote{and required by "
1170 :     "@acronym{CRAN}, so checked by @command{R CMD check --as-cran}.} to use the "
1171 :     "@samp{yyyy-mm-dd} format conforming to the ISO 8601 standard."
1172 : gnustats 1336 msgstr ""
1173 : gnustats 1804
1174 : gnustats 1578 #
1175 : gnustats 1336 #. type: Plain text
1176 : gnustats 2180 #: R-exts.texi:495
1177 : gnustats 1804 msgid ""
1178 :     "The @samp{Depends}, @samp{Imports}, @samp{Suggests}, @samp{Enhances}, "
1179 :     "@samp{LinkingTo} and @samp{Additional_repositories} fields are discussed in "
1180 :     "a later subsection."
1181 : gnustats 1336 msgstr ""
1182 : gnustats 1804
1183 : gnustats 1578 #
1184 : gnustats 1336 #. type: Plain text
1185 : gnustats 2180 #: R-exts.texi:500
1186 : gnustats 1804 msgid ""
1187 :     "Dependencies external to the @R{} system should be listed in the "
1188 :     "@samp{SystemRequirements} field, possibly amplified in a separate "
1189 :     "@file{README} file."
1190 : gnustats 1336 msgstr ""
1191 : gnustats 1804
1192 : gnustats 1336 #. type: Plain text
1193 : gnustats 2180 #: R-exts.texi:507
1194 : gnustats 1804 msgid ""
1195 :     "The @samp{URL} field may give a list of @acronym{URL}s separated by commas "
1196 :     "or whitespace, for example the homepage of the author or a page where "
1197 :     "additional material describing the software can be found. These "
1198 :     "@acronym{URL}s are converted to active hyperlinks in @acronym{CRAN} package "
1199 : gnustats 2180 "listings. @xref{Specifying URLs}."
1200 : gnustats 1336 msgstr ""
1201 : gnustats 1804
1202 : gnustats 1578 #
1203 : gnustats 1336 #. type: Plain text
1204 : gnustats 2180 #: R-exts.texi:513
1205 : gnustats 1804 msgid ""
1206 :     "The @samp{BugReports} field may contain a single @acronym{URL} to which bug "
1207 :     "reports about the package should be submitted. This @acronym{URL} will be "
1208 :     "used by @code{bug.report} instead of sending an email to the maintainer."
1209 : gnustats 1336 msgstr ""
1210 : gnustats 1804
1211 : gnustats 1578 #
1212 : gnustats 1336 #. type: Plain text
1213 : gnustats 2180 #: R-exts.texi:520
1214 : gnustats 1804 msgid ""
1215 :     "Base and recommended packages (i.e., packages contained in the @R{} source "
1216 :     "distribution or available from @acronym{CRAN} and recommended to be included "
1217 :     "in every binary distribution of @R{}) have a @samp{Priority} field with "
1218 :     "value @samp{base} or @samp{recommended}, respectively. These priorities "
1219 :     "must not be used by other packages."
1220 : gnustats 1336 msgstr ""
1221 : gnustats 1804
1222 : gnustats 1578 #
1223 : gnustats 1336 #. type: Plain text
1224 : gnustats 2180 #: R-exts.texi:536
1225 : gnustats 1804 msgid ""
1226 :     "A @samp{Collate} field can be used for controlling the collation order for "
1227 :     "the @R{} code files in a package when these are processed for package "
1228 :     "installation. The default is to collate according to the @samp{C} locale. "
1229 :     "If present, the collate specification must list @emph{all} @R{} code files "
1230 :     "in the package (taking possible OS-specific subdirectories into account, see "
1231 :     "@ref{Package subdirectories}) as a whitespace separated list of file paths "
1232 :     "relative to the @file{R} subdirectory. Paths containing white space or "
1233 :     "quotes need to be quoted. An OS-specific collation field (@samp{Collate."
1234 :     "unix} or @samp{Collate.windows}) will be used in preference to "
1235 :     "@samp{Collate}."
1236 : gnustats 1336 msgstr ""
1237 : gnustats 1804
1238 : gnustats 1578 #
1239 : gnustats 1336 #. type: Plain text
1240 : gnustats 2180 #: R-exts.texi:542
1241 : gnustats 1804 msgid ""
1242 :     "The @samp{LazyData} logical field controls whether the @R{} datasets use "
1243 :     "lazy-loading. A @samp{LazyLoad} field was used in versions prior to 2.14.0, "
1244 :     "but now is ignored."
1245 : gnustats 1336 msgstr ""
1246 : gnustats 1804
1247 : gnustats 1578 #
1248 : gnustats 1336 #. type: Plain text
1249 : gnustats 2180 #: R-exts.texi:548
1250 : gnustats 1804 msgid ""
1251 :     "The @samp{KeepSource} logical field controls if the package code is sourced "
1252 :     "using @code{keep.source = TRUE} or @code{FALSE}: it might be needed "
1253 :     "exceptionally for a package designed to always be used with @code{keep."
1254 :     "source = TRUE}."
1255 : gnustats 1336 msgstr ""
1256 : gnustats 1804
1257 : gnustats 1578 #
1258 : gnustats 1336 #. type: Plain text
1259 : gnustats 2180 #: R-exts.texi:558
1260 : gnustats 1804 msgid ""
1261 :     "The @samp{ByteCompile} logical field controls if the package code is to be "
1262 :     "byte-compiled on installation: the default is currently not to, so this may "
1263 :     "be useful for a package known to benefit particularly from byte-compilation "
1264 :     "(which can take quite a long time and increases the installed size of the "
1265 :     "package). It is used for the recommended packages, as they are byte-"
1266 :     "compiled when @R{} is installed and for consistency should be byte-compiled "
1267 :     "when updated. This can be overridden by installing with flag @option{--no-"
1268 :     "byte-compile}."
1269 : gnustats 1336 msgstr ""
1270 : gnustats 1804
1271 : gnustats 1578 #
1272 : gnustats 1336 #. type: Plain text
1273 : gnustats 2180 #: R-exts.texi:563
1274 : gnustats 1804 msgid ""
1275 :     "The @samp{ZipData} logical field was used to control whether the automatic "
1276 :     "Windows build would zip up the data directory or not prior to @R{} 2.13.0: "
1277 :     "it is now ignored."
1278 : gnustats 1336 msgstr ""
1279 : gnustats 1804
1280 : gnustats 1578 #
1281 : gnustats 1336 #. type: Plain text
1282 : gnustats 2180 #: R-exts.texi:568
1283 : gnustats 1804 msgid ""
1284 :     "The @samp{Biarch} logical field is used on Windows to select the "
1285 :     "@command{INSTALL} option @option{--force-biarch} for this package. "
1286 :     "(Introduced in @R{} 3.0.0.)"
1287 : gnustats 1336 msgstr ""
1288 : gnustats 1804
1289 : gnustats 1578 #
1290 : gnustats 1336 #. type: Plain text
1291 : gnustats 2180 #: R-exts.texi:577
1292 : gnustats 1804 msgid ""
1293 :     "The @samp{BuildVignettes} logical field can be set to a false value to stop "
1294 :     "@command{R CMD build} from attempting to build the vignettes, as well as "
1295 :     "preventing@footnote{But it is checked for Open Source packages by @command{R "
1296 :     "CMD check --as-cran}.} @command{R CMD check} from testing this. This should "
1297 :     "only be used exceptionally, for example if the PDFs include large figures "
1298 :     "which are not part of the package sources (and hence only in packages which "
1299 :     "do not have an Open Source license)."
1300 : gnustats 1336 msgstr ""
1301 : gnustats 1804
1302 : gnustats 1578 #
1303 : gnustats 1336 #. type: Plain text
1304 : gnustats 2180 #: R-exts.texi:585
1305 : gnustats 1804 msgid ""
1306 :     "The @samp{VignetteBuilder} field names (in a comma-separated list) packages "
1307 :     "that provide an engine for building vignettes. These may include the "
1308 :     "current package, or ones listed in @samp{Depends}, @samp{Suggests} or "
1309 :     "@samp{Imports}. The @pkg{utils} package is always implicitly appended. See "
1310 :     "@ref{Non-Sweave vignettes} for details."
1311 : gnustats 1336 msgstr ""
1312 : gnustats 1804
1313 : gnustats 1578 #
1314 : gnustats 1336 #. type: Plain text
1315 : gnustats 2180 #: R-exts.texi:598
1316 : gnustats 1804 msgid ""
1317 :     "If the @file{DESCRIPTION} file is not entirely in @acronym{ASCII} it should "
1318 :     "contain an @samp{Encoding} field specifying an encoding. This is used as "
1319 :     "the encoding of the @file{DESCRIPTION} file itself and of the @file{R} and "
1320 :     "@file{NAMESPACE} files, and as the default encoding of @file{.Rd} files. "
1321 :     "The examples are assumed to be in this encoding when running @command{R CMD "
1322 :     "check}, and it is used for the encoding of the @code{CITATION} file. Only "
1323 :     "encoding names @code{latin1}, @code{latin2} and @code{UTF-8} are known to be "
1324 :     "portable. (Do not specify an encoding unless one is actually needed: doing "
1325 :     "so makes the package @emph{less} portable. If a package has a specified "
1326 :     "encoding, you should run @command{R CMD build} etc in a locale using that "
1327 :     "encoding.)"
1328 : gnustats 1336 msgstr ""
1329 : gnustats 1804
1330 : gnustats 1578 #
1331 : gnustats 1336 #. type: Plain text
1332 : gnustats 2180 #: R-exts.texi:608
1333 : gnustats 1804 msgid ""
1334 :     "The @samp{NeedsCompilation} field should be set to @code{\"yes\"} if the "
1335 :     "package contains code which to be compiled, otherwise @code{\"no\"} (when "
1336 :     "the package could be installed from source on any platform without "
1337 :     "additional tools). This is used by @code{install.packages(type = \"both\")} "
1338 :     "in @R{} >= 2.15.2 on platforms where binary packages are the norm: it is "
1339 :     "normally set by @command{R CMD build} or the repository assuming compilation "
1340 :     "is required if and only if the package has a @file{src} directory."
1341 : gnustats 1336 msgstr ""
1342 : gnustats 1804
1343 : gnustats 1578 #
1344 : gnustats 1336 #. type: Plain text
1345 : gnustats 2180 #: R-exts.texi:614
1346 : gnustats 1804 msgid ""
1347 :     "The @samp{OS_type} field specifies the OS(es) for which the package is "
1348 :     "intended. If present, it should be one of @code{unix} or @code{windows}, "
1349 :     "and indicates that the package can only be installed on a platform with "
1350 :     "@samp{.Platform$OS.type} having that value."
1351 : gnustats 1336 msgstr ""
1352 : gnustats 1804
1353 : gnustats 1578 #
1354 : gnustats 1336 #. type: Plain text
1355 : gnustats 2180 #: R-exts.texi:618
1356 : gnustats 1804 msgid ""
1357 :     "The @samp{Type} field specifies the type of the package: @pxref{Package "
1358 :     "types}."
1359 : gnustats 1336 msgstr ""
1360 : gnustats 1804
1361 : gnustats 1578 #
1362 : gnustats 1336 #. type: Plain text
1363 : gnustats 2180 #: R-exts.texi:637
1364 : gnustats 1804 msgid ""
1365 :     "One can add subject classifications for the content of the package using the "
1366 :     "fields @samp{Classification/ACM} or @samp{Classification/ACM-2012} (using "
1367 :     "the Computing Classification System of the Association for Computing "
1368 :     "Machinery, @uref{http://www.acm.org/class/}; the former refers to the 1998 "
1369 :     "version), @samp{Classification/JEL} (the Journal of Economic Literature "
1370 :     "Classification System, @uref{https://www.aeaweb.org/@/econlit/@/jelCodes."
1371 :     "php}, or @samp{Classification/MSC} or @samp{Classification/MSC-2010} (the "
1372 :     "Mathematics Subject Classification of the American Mathematical Society, "
1373 :     "@uref{http://www.ams.org/msc/}; the former refers to the 2000 version). The "
1374 :     "subject classifications should be comma-separated lists of the respective "
1375 :     "classification codes, e.g., @samp{Classification/ACM: G.4, H.2.8, I.5.1}."
1376 : gnustats 1336 msgstr ""
1377 : gnustats 1804
1378 : gnustats 1336 #. type: Plain text
1379 : gnustats 2180 #: R-exts.texi:649
1380 : gnustats 1804 msgid ""
1381 :     "A @samp{Language} field can be used to indicate if the package documentation "
1382 :     "is not in English: this should be a comma-separated list of standard (not "
1383 :     "private use or grandfathered) IETF language tags as currently defined by RFC "
1384 : gnustats 2640 "5646 (@uref{https://tools.ietf.org/@/html/@/rfc5646}, see also @uref{https://"
1385 : gnustats 1804 "en.wikipedia.org/@/wiki/@/IETF_language_tag}), i.e., use language subtags "
1386 : gnustats 2640 "which in essence are 2-letter ISO 639-1 (@uref{https://en.wikipedia.@/org/@/"
1387 :     "wiki/@/ISO_639-1}) or 3-letter ISO 639-3 (@uref{https://en.wikipedia.@/org/@/"
1388 : gnustats 1804 "wiki/@/ISO_639-3}) language codes."
1389 : gnustats 1336 msgstr ""
1390 : gnustats 1804
1391 : gnustats 1578 #
1392 : gnustats 1336 #. type: Plain text
1393 : gnustats 2180 #: R-exts.texi:660
1394 : gnustats 1804 msgid ""
1395 :     "As of @R{} 3.2.0, an @samp{RdMacros} field can be used to hold a comma-"
1396 :     "separated list of packages from which the current package will import Rd "
1397 :     "macro definitions. These will be imported after the system macros, in the "
1398 :     "order listed in the @samp{RdMacros} field, before any macro definitions in "
1399 :     "the current package are loaded. Macro definitions in individual @file{.Rd} "
1400 :     "files in the @file{man} directory are loaded last, and are local to later "
1401 :     "parts of that file. In case of any duplicates, the last loaded definition "
1402 :     "will be used@footnote{Duplicate definitions may trigger a warning: see "
1403 :     "@ref{User-defined macros}.}"
1404 : gnustats 1336 msgstr ""
1405 : gnustats 1804
1406 : gnustats 1578 #
1407 : gnustats 1336 #. type: quotation
1408 : gnustats 2180 #: R-exts.texi:663
1409 : gnustats 2642 #: R-exts.texi:2515
1410 :     #: R-exts.texi:11361
1411 : gnustats 1336 #, no-wrap
1412 :     msgid "Note"
1413 :     msgstr ""
1414 : gnustats 1804
1415 : gnustats 1578 #
1416 : gnustats 1336 #. type: quotation
1417 : gnustats 2180 #: R-exts.texi:666
1418 : gnustats 1804 msgid ""
1419 :     "There should be no @samp{Built} or @samp{Packaged} fields, as these are "
1420 :     "added by the package management tools."
1421 : gnustats 1336 msgstr ""
1422 : gnustats 1804
1423 : gnustats 1578 #
1424 : gnustats 1336 #. type: Plain text
1425 : gnustats 2180 #: R-exts.texi:677
1426 : gnustats 1804 msgid ""
1427 :     "There is no restriction on the use of other fields not mentioned here (but "
1428 :     "using other capitalizations of these field names would cause confusion). "
1429 :     "Fields @code{Note}, @code{Contact} (for contacting the authors/developers) "
1430 :     "and @code{MailingList} are in common use. Some repositories (including "
1431 :     "@acronym{CRAN} and R-forge) add their own fields."
1432 : gnustats 1336 msgstr ""
1433 : gnustats 1804
1434 : gnustats 1578 #
1435 : gnustats 1336 #. type: Plain text
1436 : gnustats 2180 #: R-exts.texi:685
1437 : gnustats 1804 msgid ""
1438 :     "Licensing for a package which might be distributed is an important but "
1439 :     "potentially complex subject."
1440 : gnustats 1336 msgstr ""
1441 : gnustats 1804
1442 : gnustats 1578 #
1443 : gnustats 1336 #. type: Plain text
1444 : gnustats 2180 #: R-exts.texi:689
1445 : gnustats 1804 msgid ""
1446 :     "It is very important that you include license information! Otherwise, it may "
1447 :     "not even be legally correct for others to distribute copies of the package, "
1448 :     "let alone use it."
1449 : gnustats 1336 msgstr ""
1450 : gnustats 1804
1451 : gnustats 1336 #. type: Plain text
1452 : gnustats 2180 #: R-exts.texi:698
1453 : gnustats 1804 msgid ""
1454 :     "The package management tools use the concept of `free or open source "
1455 : gnustats 2640 "software' (FOSS, e.g., @uref{https://en.wikipedia.org/@/wiki/@/FOSS}) "
1456 : gnustats 1804 "licenses: the idea being that some users of @R{} and its packages want to "
1457 :     "restrict themselves to such software. Others need to ensure that there are "
1458 :     "no restrictions stopping them using a package, e.g.@: forbidding commercial "
1459 :     "or military use. It is a central tenet of FOSS software that there are no "
1460 :     "restrictions on users nor usage."
1461 : gnustats 1336 msgstr ""
1462 : gnustats 1804
1463 : gnustats 1578 #
1464 : gnustats 1336 #. type: Plain text
1465 : gnustats 2180 #: R-exts.texi:701
1466 : gnustats 1804 msgid ""
1467 :     "Do not use the @samp{License} field for information on copyright holders: if "
1468 :     "needed, use a @samp{Copyright} field."
1469 : gnustats 1336 msgstr ""
1470 : gnustats 1804
1471 : gnustats 1578 #
1472 : gnustats 1336 #. type: Plain text
1473 : gnustats 2180 #: R-exts.texi:709
1474 : gnustats 1804 msgid ""
1475 :     "The mandatory @samp{License} field in the @file{DESCRIPTION} file should "
1476 :     "specify the license of the package in a standardized form. Alternatives are "
1477 :     "indicated @emph{via} vertical bars. Individual specifications must be one of"
1478 : gnustats 1336 msgstr ""
1479 : gnustats 1804
1480 : gnustats 1578 #
1481 : gnustats 1336 #. type: itemize
1482 : gnustats 2180 #: R-exts.texi:712
1483 : gnustats 1336 msgid "One of the ``standard'' short specifications"
1484 :     msgstr ""
1485 : gnustats 1804
1486 : gnustats 1578 #
1487 : gnustats 1336 #. type: example
1488 : gnustats 2180 #: R-exts.texi:715
1489 : gnustats 1336 #, no-wrap
1490 :     msgid ""
1491 :     "GPL-2 GPL-3 LGPL-2 LGPL-2.1 LGPL-3 AGPL-3 Artistic-2.0\n"
1492 :     "BSD_2_clause BSD_3_clause MIT\n"
1493 :     msgstr ""
1494 : gnustats 1804
1495 : gnustats 1336 #. type: itemize
1496 : gnustats 2180 #: R-exts.texi:719
1497 : gnustats 1804 msgid ""
1498 : gnustats 2640 "as made available @emph{via} @uref{https://www.R-project.org/@/Licenses/} "
1499 :     "and contained in subdirectory @file{share/licenses} of the @R{} source or "
1500 :     "home directory."
1501 : gnustats 1336 msgstr ""
1502 : gnustats 1804
1503 : gnustats 1578 #
1504 : gnustats 1336 #. type: itemize
1505 : gnustats 2180 #: R-exts.texi:730
1506 : gnustats 1804 msgid ""
1507 :     "The names or abbreviations of other licenses contained in the license data "
1508 :     "base in file @file{share/licenses/license.db} in the @R{} source or home "
1509 :     "directory, possibly (for versioned licenses) followed by a version "
1510 :     "restriction of the form @samp{(@var{op} @var{v})} with @samp{@var{op}} one "
1511 :     "of the comparison operators @samp{<}, @samp{<=}, @samp{>}, @samp{>=}, "
1512 :     "@samp{==}, or @samp{!=} and @samp{@var{v}} a numeric version specification "
1513 :     "(strings of non-negative integers separated by @samp{.}), possibly combined "
1514 :     "@emph{via} @samp{,} (see below for an example). For versioned licenses, one "
1515 :     "can also specify the name followed by the version, or combine an existing "
1516 :     "abbreviation and the version with a @samp{-}."
1517 : gnustats 1336 msgstr ""
1518 : gnustats 1804
1519 : gnustats 1578 #
1520 : gnustats 1336 #. type: itemize
1521 : gnustats 2180 #: R-exts.texi:733
1522 : gnustats 1804 msgid ""
1523 :     "Abbreviations @code{GPL} and @code{LGPL} are ambiguous and usually taken to "
1524 :     "mean any version of the license: but it is better not to use them."
1525 : gnustats 1336 msgstr ""
1526 : gnustats 1804
1527 : gnustats 1578 #
1528 : gnustats 1336 #. type: itemize
1529 : gnustats 2180 #: R-exts.texi:737
1530 : gnustats 1804 msgid ""
1531 :     "One of the strings @samp{file LICENSE} or @samp{file LICENCE} referring to a "
1532 :     "file named @file{LICENSE} or @file{LICENCE} in the package (source and "
1533 :     "installation) top-level directory."
1534 : gnustats 1336 msgstr ""
1535 : gnustats 1804
1536 : gnustats 1578 #
1537 : gnustats 1336 #. type: itemize
1538 : gnustats 2180 #: R-exts.texi:741
1539 : gnustats 1804 msgid ""
1540 :     "The string @samp{Unlimited}, meaning that there are no restrictions on "
1541 :     "distribution or use other than those imposed by relevant laws (including "
1542 :     "copyright laws)."
1543 : gnustats 1336 msgstr ""
1544 : gnustats 1804
1545 : gnustats 1578 #
1546 : gnustats 1336 #. type: Plain text
1547 : gnustats 2180 #: R-exts.texi:751
1548 : gnustats 1804 msgid ""
1549 :     "If a package license @emph{restricts} a base license (where permitted, e.g., "
1550 :     "using GPL-3 or AGPL-3 with an attribution clause), the additional terms "
1551 :     "should be placed in file @file{LICENSE} (or @file{LICENCE}), and the string "
1552 :     "@samp{+ file LICENSE} (or @samp{+ file LICENCE}, respectively) should be "
1553 :     "appended to the corresponding individual license specification. Note that "
1554 :     "several commonly used licenses do not permit restrictions: this includes "
1555 :     "GPL-2 and hence any specification which includes it."
1556 : gnustats 1336 msgstr ""
1557 : gnustats 1804
1558 : gnustats 1578 #
1559 : gnustats 1336 #. type: Plain text
1560 : gnustats 2180 #: R-exts.texi:753
1561 : gnustats 1336 msgid "Examples of standardized specifications include"
1562 :     msgstr ""
1563 : gnustats 1804
1564 : gnustats 1578 #
1565 : gnustats 1336 #. type: example
1566 : gnustats 2180 #: R-exts.texi:759
1567 : gnustats 1336 #, no-wrap
1568 :     msgid ""
1569 :     "License: GPL-2\n"
1570 :     "License: LGPL (>= 2.0, < 3) | Mozilla Public License\n"
1571 :     "License: GPL-2 | file LICENCE\n"
1572 :     "License: GPL (>= 2) | BSD_3_clause + file LICENSE\n"
1573 :     "License: Artistic-2.0 | AGPL-3 + file LICENSE\n"
1574 :     msgstr ""
1575 : gnustats 1804
1576 : gnustats 1578 #
1577 : gnustats 1336 #. type: Plain text
1578 : gnustats 2180 #: R-exts.texi:762
1579 : gnustats 1804 msgid ""
1580 :     "Please note in particular that ``Public domain'' is not a valid license, "
1581 :     "since it is not recognized in some jurisdictions."
1582 : gnustats 1336 msgstr ""
1583 : gnustats 1804
1584 : gnustats 1578 #
1585 : gnustats 1336 #. type: Plain text
1586 : gnustats 2180 #: R-exts.texi:767
1587 : gnustats 1804 msgid ""
1588 :     "Please ensure that the license you choose also covers any dependencies "
1589 :     "(including system dependencies) of your package: it is particularly "
1590 :     "important that any restrictions on the use of such dependencies are evident "
1591 :     "to people reading your @file{DESCRIPTION} file."
1592 : gnustats 1336 msgstr ""
1593 : gnustats 1804
1594 : gnustats 1578 #
1595 : gnustats 1336 #. type: Plain text
1596 : gnustats 2180 #: R-exts.texi:775
1597 : gnustats 1804 msgid ""
1598 :     "Fields @samp{License_is_FOSS} and @samp{License_restricts_use} may be added "
1599 :     "by repositories where information cannot be computed from the name of the "
1600 :     "license. @samp{License_is_FOSS: yes} is used for licenses which are known "
1601 :     "to be FOSS, and @samp{License_restricts_use} can have values @samp{yes} or "
1602 :     "@samp{no} if the @file{LICENSE} file is known to restrict users or usage, or "
1603 :     "known not to. These are used by, e.g.@:, the @code{available.packages} "
1604 :     "filters."
1605 : gnustats 1336 msgstr ""
1606 : gnustats 1804
1607 : gnustats 1578 #
1608 : gnustats 1336 #. type: cindex
1609 : gnustats 2180 #: R-exts.texi:777
1610 : gnustats 1336 #, no-wrap
1611 :     msgid "LICENSE file"
1612 :     msgstr ""
1613 : gnustats 1804
1614 : gnustats 1578 #
1615 : gnustats 1336 #. type: cindex
1616 : gnustats 2180 #: R-exts.texi:778
1617 : gnustats 1336 #, no-wrap
1618 :     msgid "LICENCE file"
1619 :     msgstr ""
1620 : gnustats 1804
1621 : gnustats 1578 #
1622 : gnustats 1336 #. type: Plain text
1623 : gnustats 2180 #: R-exts.texi:783
1624 : gnustats 1804 msgid ""
1625 :     "The optional file @file{LICENSE}/@file{LICENCE} contains a copy of the "
1626 :     "license of the package. To avoid any confusion only include such a file if "
1627 :     "it is referred to in the @samp{License} field of the @file{DESCRIPTION} file."
1628 : gnustats 1336 msgstr ""
1629 : gnustats 1804
1630 : gnustats 1336 #. type: Plain text
1631 : gnustats 2180 #: R-exts.texi:794
1632 : gnustats 1804 msgid ""
1633 :     "Whereas you should feel free to include a license file in your @emph{source} "
1634 :     "distribution, please do not arrange to @emph{install} yet another copy of "
1635 :     "the @acronym{GNU} @file{COPYING} or @file{COPYING.LIB} files but refer to "
1636 : gnustats 2640 "the copies on @uref{https://www.R-project.org/@/Licenses/} and included in "
1637 : gnustats 1804 "the @R{} distribution (in directory @file{share/licenses}). Since files "
1638 :     "named @file{LICENSE} or @file{LICENCE} @emph{will} be installed, do not use "
1639 :     "these names for standard license files. To include comments about the "
1640 :     "licensing rather than the body of a license, use a file named something like "
1641 :     "@file{LICENSE.note}."
1642 : gnustats 1336 msgstr ""
1643 : gnustats 1804
1644 : gnustats 1578 #
1645 : gnustats 1336 #. type: Plain text
1646 : gnustats 2180 #: R-exts.texi:797
1647 : gnustats 1804 msgid ""
1648 :     "A few ``standard'' licenses are rather license templates which need "
1649 :     "additional information to be completed @emph{via} @samp{+ file LICENSE}."
1650 : gnustats 1336 msgstr ""
1651 : gnustats 1804
1652 : gnustats 1578 #
1653 : gnustats 1336 #. type: Plain text
1654 : gnustats 2180 #: R-exts.texi:809
1655 : gnustats 1804 msgid ""
1656 :     "The @samp{Depends} field gives a comma-separated list of package names which "
1657 :     "this package depends on. Those packages will be attached before the current "
1658 :     "package when @code{library} or @code{require} is called. Each package name "
1659 :     "may be optionally followed by a comment in parentheses specifying a version "
1660 :     "requirement. The comment should contain a comparison operator, whitespace "
1661 :     "and a valid version number, e.g. @samp{MASS (>= 3.1-20)}."
1662 : gnustats 1336 msgstr ""
1663 : gnustats 1804
1664 : gnustats 1578 #
1665 : gnustats 1336 #. type: Plain text
1666 : gnustats 2180 #: R-exts.texi:817
1667 : gnustats 1804 msgid ""
1668 :     "The @samp{Depends} field can also specify a dependence on a certain version "
1669 :     "of @R{} --- e.g., if the package works only with @R{} version 3.0.0 or "
1670 :     "later, include @samp{R (>= 3.0.0)} in the @samp{Depends} field. You can "
1671 :     "also require a certain SVN revision for R-devel or R-patched, e.g.@: @samp{R "
1672 :     "(>= 2.14.0), R (>= r56550)} requires a version later than R-devel of late "
1673 :     "July 2011 (including released versions of 2.14.0)."
1674 : gnustats 1336 msgstr ""
1675 : gnustats 1804
1676 : gnustats 1578 #
1677 : gnustats 1336 #. type: Plain text
1678 : gnustats 2180 #: R-exts.texi:821
1679 : gnustats 1804 msgid ""
1680 :     "It makes no sense to declare a dependence on @code{R} without a version "
1681 :     "specification, nor on the package @pkg{base}: this is an @R{} package and "
1682 :     "package @pkg{base} is always available."
1683 : gnustats 1336 msgstr ""
1684 : gnustats 1804
1685 : gnustats 1578 #
1686 : gnustats 1336 #. type: Plain text
1687 : gnustats 2180 #: R-exts.texi:824
1688 : gnustats 1804 msgid ""
1689 :     "A package or @samp{R} can appear more than once in the @samp{Depends} field, "
1690 :     "for example to give upper and lower bounds on acceptable versions."
1691 : gnustats 1336 msgstr ""
1692 : gnustats 1804
1693 : gnustats 1578 #
1694 : gnustats 1336 #. type: Plain text
1695 : gnustats 2180 #: R-exts.texi:832
1696 : gnustats 1804 msgid ""
1697 :     "Both @code{library} and the @R{} package checking facilities use this field: "
1698 :     "hence it is an error to use improper syntax or misuse the @samp{Depends} "
1699 :     "field for comments on other software that might be needed. The @R{} "
1700 :     "@command{INSTALL} facilities check if the version of @R{} used is recent "
1701 :     "enough for the package being installed, and the list of packages which is "
1702 :     "specified will be attached (after checking version requirements) before the "
1703 :     "current package."
1704 : gnustats 1336 msgstr ""
1705 : gnustats 1804
1706 : gnustats 1578 #
1707 : gnustats 1336 #. type: Plain text
1708 : gnustats 2180 #: R-exts.texi:845
1709 : gnustats 1804 msgid ""
1710 :     "The @samp{Imports} field lists packages whose namespaces are imported from "
1711 :     "(as specified in the @file{NAMESPACE} file) but which do not need to be "
1712 :     "attached. Namespaces accessed by the @samp{::} and @samp{:::} operators "
1713 :     "must be listed here, or in @samp{Suggests} or @samp{Enhances} (see below). "
1714 :     "Ideally this field will include all the standard packages that are used, and "
1715 :     "it is important to include S4-using packages (as their class definitions can "
1716 :     "change and the @file{DESCRIPTION} file is used to decide which packages to "
1717 :     "re-install when this happens). Packages declared in the @samp{Depends} "
1718 :     "field should not also be in the @samp{Imports} field. Version requirements "
1719 :     "can be specified and are checked when the namespace is loaded (since @R{} >= "
1720 :     "3.0.0)."
1721 : gnustats 1336 msgstr ""
1722 : gnustats 1804
1723 : gnustats 1578 #
1724 : gnustats 1336 #. type: Plain text
1725 : gnustats 2180 #: R-exts.texi:857
1726 : gnustats 1804 msgid ""
1727 :     "The @samp{Suggests} field uses the same syntax as @samp{Depends} and lists "
1728 :     "packages that are not necessarily needed. This includes packages used only "
1729 :     "in examples, tests or vignettes (@pxref{Writing package vignettes}), and "
1730 :     "packages loaded in the body of functions. E.g., suppose an "
1731 :     "example@footnote{even one wrapped in @code{\\donttest}.} from package "
1732 :     "@pkg{foo} uses a dataset from package @pkg{bar}. Then it is not necessary to "
1733 :     "have @pkg{bar} use @pkg{foo} unless one wants to execute all the examples/"
1734 :     "tests/vignettes: it is useful to have @pkg{bar}, but not necessary. Version "
1735 :     "requirements can be specified, and will be used by @command{R CMD check}."
1736 : gnustats 1336 msgstr ""
1737 : gnustats 1804
1738 : gnustats 1578 #
1739 : gnustats 1336 #. type: Plain text
1740 : gnustats 2180 #: R-exts.texi:869
1741 : gnustats 1804 msgid ""
1742 :     "Finally, the @samp{Enhances} field lists packages ``enhanced'' by the "
1743 :     "package at hand, e.g., by providing methods for classes from these packages, "
1744 :     "or ways to handle objects from these packages (so several packages have "
1745 :     "@samp{Enhances: chron} because they can handle datetime objects from "
1746 :     "@CRANpkg{chron} even though they prefer @R{}'s native datetime functions). "
1747 :     "Version requirements can be specified, but are currently not used. Such "
1748 :     "packages cannot be required to check the package: any tests which use them "
1749 :     "must be conditional on the presence of the package. (If your tests use e.g."
1750 :     "@: a dataset from another package it should be in @samp{Suggests} and not "
1751 :     "@samp{Enhances}.)"
1752 : gnustats 1336 msgstr ""
1753 : gnustats 1804
1754 : gnustats 1578 #
1755 : gnustats 1336 #. type: Plain text
1756 : gnustats 2180 #: R-exts.texi:871
1757 : gnustats 1336 msgid "The general rules are"
1758 :     msgstr ""
1759 : gnustats 1804
1760 : gnustats 1578 #
1761 : gnustats 1336 #. type: itemize
1762 : gnustats 2180 #: R-exts.texi:875
1763 : gnustats 1336 msgid "A package should be listed in only one of these fields."
1764 :     msgstr ""
1765 : gnustats 1804
1766 : gnustats 1578 #
1767 : gnustats 1336 #. type: itemize
1768 : gnustats 2180 #: R-exts.texi:881
1769 : gnustats 1804 msgid ""
1770 :     "Packages whose namespace only is needed to load the package using "
1771 :     "@code{library(@var{pkgname})} should be listed in the @samp{Imports} field "
1772 :     "and not in the @samp{Depends} field. Packages listed in @code{imports} or "
1773 :     "@code{importFrom} directives in the @file{NAMESPACE} file should almost "
1774 :     "always be in @samp{Imports} and not @samp{Depends}."
1775 : gnustats 1336 msgstr ""
1776 : gnustats 1804
1777 : gnustats 1578 #
1778 : gnustats 1336 #. type: itemize
1779 : gnustats 2180 #: R-exts.texi:885
1780 : gnustats 1804 msgid ""
1781 :     "Packages that need to be attached to successfully load the package using "
1782 :     "@code{library(@var{pkgname})} must be listed in the @samp{Depends} field."
1783 : gnustats 1336 msgstr ""
1784 : gnustats 1804
1785 : gnustats 1578 #
1786 : gnustats 1336 #. type: itemize
1787 : gnustats 2180 #: R-exts.texi:901
1788 : gnustats 1804 msgid ""
1789 :     "All packages that are needed@footnote{This includes all packages directly "
1790 :     "called by @code{library} and @code{require} calls, as well as data obtained "
1791 :     "@emph{via} @code{data(theirdata, package = \"somepkg\")} calls: @command{R "
1792 :     "CMD check} will warn about all of these. But there are subtler uses which "
1793 :     "it will not detect: e.g.@: if package A uses package B and makes use of "
1794 :     "functionality in package B which uses package C which package B suggests or "
1795 :     "enhances, then package C needs to be in the @samp{Suggests} list for package "
1796 :     "A. Nor will undeclared uses in included files be reported, nor "
1797 :     "unconditional uses of packages listed under @samp{Enhances}.} to "
1798 :     "successfully run @code{R CMD check} on the package must be listed in one of "
1799 :     "@samp{Depends} or @samp{Suggests} or @samp{Imports}. Packages used to run "
1800 :     "examples or tests conditionally (e.g.@: @emph{via} "
1801 :     "@code{if(require(@var{pkgname}))}) should be listed in @samp{Suggests} or "
1802 :     "@samp{Enhances}. (This allows checkers to ensure that all the packages "
1803 :     "needed for a complete check are installed.)"
1804 : gnustats 1336 msgstr ""
1805 : gnustats 1804
1806 : gnustats 1578 #
1807 : gnustats 1336 #. type: Plain text
1808 : gnustats 2180 #: R-exts.texi:907
1809 : gnustats 1804 msgid ""
1810 :     "In particular, packages providing ``only'' data for examples or vignettes "
1811 :     "should be listed in @samp{Suggests} rather than @samp{Depends} in order to "
1812 :     "make lean installations possible."
1813 : gnustats 1336 msgstr ""
1814 : gnustats 1804
1815 : gnustats 1578 #
1816 : gnustats 1336 #. type: Plain text
1817 : gnustats 2180 #: R-exts.texi:913
1818 : gnustats 1804 msgid ""
1819 :     "Version dependencies in the @samp{Depends} and @samp{Imports} fields are "
1820 :     "used by @code{library} when it loads the package, and @code{install."
1821 :     "packages} checks versions for the @samp{Depends}, @samp{Imports} and (for "
1822 :     "@code{dependencies = TRUE}) @samp{Suggests} fields."
1823 : gnustats 1336 msgstr ""
1824 : gnustats 1804
1825 : gnustats 1578 #
1826 : gnustats 1336 #. type: Plain text
1827 : gnustats 2180 #: R-exts.texi:918
1828 : gnustats 1804 msgid ""
1829 :     "It is increasingly important that the information in these fields is "
1830 :     "complete and accurate: it is for example used to compute which packages "
1831 :     "depend on an updated package and which packages can safely be installed in "
1832 :     "parallel."
1833 : gnustats 1336 msgstr ""
1834 : gnustats 1804
1835 : gnustats 1578 #
1836 : gnustats 1336 #. type: Plain text
1837 : gnustats 2180 #: R-exts.texi:922
1838 : gnustats 1804 msgid ""
1839 :     "This scheme was developed before all packages had namespaces (@R{} 2.14.0 in "
1840 :     "October 2011), and good practice changed once that was in place."
1841 : gnustats 1336 msgstr ""
1842 : gnustats 1804
1843 : gnustats 1578 #
1844 : gnustats 1336 #. type: Plain text
1845 : gnustats 2180 #: R-exts.texi:928
1846 : gnustats 1804 msgid ""
1847 :     "Field @samp{Depends} should nowadays be used rarely, only for packages which "
1848 :     "are intended to be put on the search path to make their facilities available "
1849 :     "to the end user (and not to the package itself): for example it makes sense "
1850 :     "that a user of package @CRANpkg{latticeExtra} would want the functions of "
1851 :     "package @CRANpkg{lattice} made available."
1852 : gnustats 1336 msgstr ""
1853 : gnustats 1804
1854 : gnustats 1578 #
1855 : gnustats 1336 #. type: Plain text
1856 : gnustats 2180 #: R-exts.texi:933
1857 : gnustats 1804 msgid ""
1858 :     "Almost always packages mentioned in @samp{Depends} should also be imported "
1859 :     "from in the @file{NAMESPACE} file: this ensures that any needed parts of "
1860 :     "those packages are available when some other package imports the current "
1861 :     "package."
1862 : gnustats 1336 msgstr ""
1863 : gnustats 1804
1864 : gnustats 1578 #
1865 : gnustats 1336 #. type: Plain text
1866 : gnustats 2180 #: R-exts.texi:939
1867 : gnustats 1804 msgid ""
1868 :     "The @samp{Imports} field should not contain packages which are not imported "
1869 :     "from (@emph{via} the @file{NAMESPACE} file or @code{::} or @code{:::} "
1870 :     "operators), as all the packages listed in that field need to be installed "
1871 :     "for the current package to be installed. (This is checked by @command{R CMD "
1872 :     "check}.)"
1873 : gnustats 1336 msgstr ""
1874 : gnustats 1804
1875 : gnustats 1578 #
1876 : gnustats 1336 #. type: Plain text
1877 : gnustats 2180 #: R-exts.texi:947
1878 : gnustats 1804 msgid ""
1879 :     "@R{} code in the package should call @code{library} or @code{require} only "
1880 :     "exceptionally. Such calls are never needed for packages listed in "
1881 :     "@samp{Depends} as they will already be on the search path. It used to be "
1882 :     "common practice to use @code{require} calls for packages listed in "
1883 :     "@samp{Suggests} in functions which used their functionality, but nowadays it "
1884 :     "is better to access such functionality @emph{via} @code{::} calls."
1885 : gnustats 1336 msgstr ""
1886 : gnustats 1804
1887 : gnustats 1578 #
1888 : gnustats 1336 #. type: Plain text
1889 : gnustats 2180 #: R-exts.texi:952
1890 : gnustats 1804 msgid ""
1891 :     "A package that wishes to make use of header files in other packages needs to "
1892 :     "declare them as a comma-separated list in the field @samp{LinkingTo} in the "
1893 :     "@file{DESCRIPTION} file. For example"
1894 : gnustats 1336 msgstr ""
1895 : gnustats 1804
1896 : gnustats 1578 #
1897 : gnustats 1336 #. type: example
1898 : gnustats 2180 #: R-exts.texi:955
1899 : gnustats 1336 #, no-wrap
1900 :     msgid "LinkingTo: link1, link2\n"
1901 :     msgstr ""
1902 : gnustats 1804
1903 : gnustats 1578 #
1904 : gnustats 1336 #. type: Plain text
1905 : gnustats 2180 #: R-exts.texi:961
1906 : gnustats 1804 msgid ""
1907 :     "As from @R{} 3.0.2 the @samp{LinkingTo} field can have a version requirement "
1908 :     "which is checked at installation. (In earlier versions of @R{} it would "
1909 :     "cause the specification to be ignored.)"
1910 : gnustats 1336 msgstr ""
1911 : gnustats 1804
1912 : gnustats 1336 #. type: Plain text
1913 : gnustats 2180 #: R-exts.texi:968
1914 : gnustats 1804 msgid ""
1915 :     "Specifying a package in @samp{LinkingTo} suffices if these are C++ headers "
1916 :     "containing source code or static linking is done at installation: the "
1917 :     "packages do not need to be (and usually should not be) listed in the "
1918 : gnustats 2180 "@samp{Depends} or @samp{Imports} fields. This includes @acronym{CRAN} "
1919 :     "package @CRANpkg{BH} and almost all users of @CRANpkg{RcppArmadillo} and "
1920 : gnustats 1804 "@CRANpkg{RcppEigen}."
1921 : gnustats 1336 msgstr ""
1922 : gnustats 1804
1923 : gnustats 1578 #
1924 : gnustats 1336 #. type: Plain text
1925 : gnustats 2180 #: R-exts.texi:971
1926 : gnustats 1804 msgid ""
1927 :     "For another use of @samp{LinkingTo} see @ref{Linking to native routines in "
1928 :     "other packages}."
1929 : gnustats 1336 msgstr ""
1930 : gnustats 1804
1931 : gnustats 1578 #. type: Plain text
1932 : gnustats 2180 #: R-exts.texi:978
1933 : gnustats 1804 msgid ""
1934 : gnustats 2063 "The @samp{Additional_repositories} field is a comma-separated list of "
1935 : gnustats 1804 "repository URLs where the packages named in the other fields may be found. "
1936 :     "It is currently used by @command{R CMD check} to check that the packages can "
1937 :     "be found, at least as source packages (which can be installed on any "
1938 :     "platform)."
1939 : gnustats 1578 msgstr ""
1940 : gnustats 1804
1941 : gnustats 1578 #
1942 : gnustats 1336 #. type: subsubsection
1943 : gnustats 2054 #: R-exts.texi:981
1944 : gnustats 2180 #: R-exts.texi:983
1945 :     #: R-exts.texi:984
1946 : gnustats 1336 #, no-wrap
1947 :     msgid "Suggested packages"
1948 :     msgstr ""
1949 : gnustats 1804
1950 : gnustats 1578 #
1951 : gnustats 1336 #. type: Plain text
1952 : gnustats 2180 #: R-exts.texi:991
1953 : gnustats 1804 msgid ""
1954 :     "Note that someone wanting to run the examples/tests/vignettes may not have a "
1955 :     "suggested package available (and it may not even be possible to install it "
1956 :     "for that platform). The recommendation used to be to make their use "
1957 :     "conditional @emph{via} @code{if(require(\"@var{pkgname}\"))}): this is fine "
1958 :     "if that conditioning is done in examples/tests/vignettes."
1959 : gnustats 1336 msgstr ""
1960 : gnustats 1804
1961 : gnustats 1578 #
1962 : gnustats 1336 #. type: Plain text
1963 : gnustats 2180 #: R-exts.texi:997
1964 : gnustats 1804 msgid ""
1965 :     "However, using @code{require} for conditioning @emph{in package code} is not "
1966 :     "good practice as it alters the search path for the rest of the session and "
1967 :     "relies on functions in that package not being masked by other @code{require} "
1968 :     "or @code{library} calls. It is better practice to use code like"
1969 : gnustats 1336 msgstr ""
1970 : gnustats 1804
1971 : gnustats 1578 #
1972 : gnustats 1336 #. type: example
1973 : gnustats 2180 #: R-exts.texi:1003
1974 : gnustats 1336 #, no-wrap
1975 :     msgid ""
1976 :     " if (requireNamespace(\"rgl\", quietly = TRUE)) @{\n"
1977 :     " rgl::plot3d(...)\n"
1978 :     " @} else @{\n"
1979 :     " ## do something else not involving rgl.\n"
1980 :     " @}\n"
1981 :     msgstr ""
1982 : gnustats 1804
1983 : gnustats 1578 #
1984 : gnustats 1336 #. type: Plain text
1985 : gnustats 2180 #: R-exts.texi:1010
1986 : gnustats 1804 msgid ""
1987 :     "Note the use of @code{rgl::} as that object would not necessarily be visible "
1988 :     "(and if it is, it need not be the one from that namespace: @code{plot3d} "
1989 :     "occurs in several other packages). If the intention is to give an error if "
1990 :     "the suggested package is not available, simply use e.g.@: @code{rgl::plot3d}."
1991 : gnustats 1336 msgstr ""
1992 : gnustats 1804
1993 : gnustats 1578 #
1994 : gnustats 1336 #. type: Plain text
1995 : gnustats 2180 #: R-exts.texi:1014
1996 : gnustats 1804 msgid ""
1997 :     "As noted above, packages in @samp{Enhances} @emph{must} be used "
1998 :     "conditionally and hence objects within them should always be accessed "
1999 :     "@emph{via} @code{::}."
2000 : gnustats 1336 msgstr ""
2001 : gnustats 1804
2002 : gnustats 1578 #
2003 : gnustats 1336 #. type: subsection
2004 : gnustats 2180 #: R-exts.texi:1016
2005 : gnustats 1336 #, no-wrap
2006 :     msgid "The @file{INDEX} file"
2007 :     msgstr ""
2008 : gnustats 1804
2009 : gnustats 1578 #
2010 : gnustats 1336 #. type: cindex
2011 : gnustats 2180 #: R-exts.texi:1017
2012 : gnustats 1336 #, no-wrap
2013 :     msgid "INDEX file"
2014 :     msgstr ""
2015 : gnustats 1804
2016 : gnustats 1578 #
2017 : gnustats 1336 #. type: Plain text
2018 : gnustats 2180 #: R-exts.texi:1025
2019 : gnustats 1804 msgid ""
2020 :     "The optional file @file{INDEX} contains a line for each sufficiently "
2021 :     "interesting object in the package, giving its name and a description "
2022 :     "(functions such as print methods not usually called explicitly might not be "
2023 :     "included). Normally this file is missing and the corresponding information "
2024 :     "is automatically generated from the documentation sources (using "
2025 :     "@code{tools::Rdindex()}) when installing from source."
2026 : gnustats 1336 msgstr ""
2027 : gnustats 1804
2028 : gnustats 1578 #
2029 : gnustats 1336 #. type: Plain text
2030 : gnustats 2180 #: R-exts.texi:1028
2031 : gnustats 1804 msgid ""
2032 :     "The file is part of the information given by @code{library(help = "
2033 :     "@var{pkgname})}."
2034 : gnustats 1336 msgstr ""
2035 : gnustats 1804
2036 : gnustats 1578 #
2037 : gnustats 1336 #. type: Plain text
2038 : gnustats 2180 #: R-exts.texi:1033
2039 : gnustats 1804 msgid ""
2040 :     "Rather than editing this file, it is preferable to put customized "
2041 :     "information about the package into an overview help page (@pxref{Documenting "
2042 :     "packages}) and/or a vignette (@pxref{Writing package vignettes})."
2043 : gnustats 1336 msgstr ""
2044 : gnustats 1804
2045 : gnustats 1578 #
2046 : gnustats 1336 #. type: Plain text
2047 : gnustats 2180 #: R-exts.texi:1056
2048 : gnustats 1804 msgid ""
2049 :     "The @file{R} subdirectory contains @R{} code files, only. The code files to "
2050 :     "be installed must start with an @acronym{ASCII} (lower or upper case) letter "
2051 :     "or digit and have one of the extensions@footnote{Extensions @file{.S} and "
2052 :     "@file{.s} arise from code originally written for S(-PLUS), but are commonly "
2053 :     "used for assembler code. Extension @file{.q} was used for S, which at one "
2054 :     "time was tentatively called QPE.} @file{.R}, @file{.S}, @file{.q}, @file{."
2055 :     "r}, or @file{.s}. We recommend using @file{.R}, as this extension seems to "
2056 :     "be not used by any other software. It should be possible to read in the "
2057 :     "files using @code{source()}, so @R{} objects must be created by "
2058 :     "assignments. Note that there need be no connection between the name of the "
2059 :     "file and the @R{} objects created by it. Ideally, the @R{} code files "
2060 :     "should only directly assign @R{} objects and definitely should not call "
2061 :     "functions with side effects such as @code{require} and @code{options}. If "
2062 :     "computations are required to create objects these can use code `earlier' in "
2063 :     "the package (see the @samp{Collate} field) plus functions in the "
2064 :     "@samp{Depends} packages provided that the objects created do not depend on "
2065 :     "those packages except @emph{via} namespace imports."
2066 : gnustats 1336 msgstr ""
2067 : gnustats 1804
2068 : gnustats 1578 #
2069 : gnustats 1336 #. type: Plain text
2070 : gnustats 2180 #: R-exts.texi:1066
2071 : gnustats 1804 msgid ""
2072 :     "Two exceptions are allowed: if the @file{R} subdirectory contains a file "
2073 :     "@file{sysdata.rda} (a saved image of one or more @R{} objects: please use "
2074 :     "suitable compression as suggested by @code{tools::resaveRdaFiles}, and see "
2075 :     "also the @samp{SysDataCompression} @file{DESCRIPTION} field.) this will be "
2076 :     "lazy-loaded into the namespace environment -- this is intended for system "
2077 :     "datasets that are not intended to be user-accessible @emph{via} "
2078 :     "@code{data}. Also, files ending in @samp{.in} will be allowed in the "
2079 :     "@file{R} directory to allow a @file{configure} script to generate suitable "
2080 :     "files."
2081 : gnustats 1336 msgstr ""
2082 : gnustats 1804
2083 : gnustats 1336 #. type: Plain text
2084 : gnustats 2180 #: R-exts.texi:1079
2085 : gnustats 1804 msgid ""
2086 :     "Only @acronym{ASCII} characters (and the control characters tab, formfeed, "
2087 :     "LF and CR) should be used in code files. Other characters are accepted in "
2088 : gnustats 1874 "comments@footnote{but they should be in the encoding declared in the "
2089 :     "@file{DESCRIPTION} file.}, but then the comments may not be readable in e.g."
2090 :     "@: a UTF-8 locale. Non-@acronym{ASCII} characters in object names will "
2091 : gnustats 1804 "normally@footnote{This is true for OSes which implement the @samp{C} locale: "
2092 :     "Windows' idea of the @samp{C} locale uses the WinAnsi charset.} fail when "
2093 :     "the package is installed. Any byte will be allowed in a quoted character "
2094 :     "string but @code{\\uxxxx} escapes should be used for non-@acronym{ASCII} "
2095 :     "characters. However, non-@acronym{ASCII} character strings may not be "
2096 :     "usable in some locales and may display incorrectly in others."
2097 : gnustats 1336 msgstr ""
2098 : gnustats 1804
2099 : gnustats 1578 #
2100 : gnustats 1336 #. type: findex
2101 : gnustats 2180 #: R-exts.texi:1081
2102 : gnustats 2642 #: R-exts.texi:8597
2103 : gnustats 1336 #, no-wrap
2104 :     msgid "library.dynam"
2105 :     msgstr ""
2106 : gnustats 1804
2107 : gnustats 1578 #
2108 : gnustats 1336 #. type: Plain text
2109 : gnustats 2180 #: R-exts.texi:1084
2110 : gnustats 1804 msgid ""
2111 :     "Various @R{} functions in a package can be used to initialize and clean up. "
2112 :     "@xref{Load hooks}."
2113 : gnustats 1336 msgstr ""
2114 : gnustats 1804
2115 : gnustats 1578 #
2116 : gnustats 1336 #. type: Plain text
2117 : gnustats 2180 #: R-exts.texi:1103
2118 : gnustats 1804 msgid ""
2119 :     "The @file{man} subdirectory should contain (only) documentation files for "
2120 :     "the objects in the package in @dfn{R documentation} (Rd) format. The "
2121 :     "documentation filenames must start with an @acronym{ASCII} (lower or upper "
2122 :     "case) letter or digit and have the extension @file{.Rd} (the default) or "
2123 :     "@file{.rd}. Further, the names must be valid in @samp{file://} URLs, which "
2124 :     "means@footnote{More precisely, they can contain the English alphanumeric "
2125 :     "characters and the symbols @samp{$ - _ . + ! ' ( ) , ; @ = &}.} they must be "
2126 :     "entirely @acronym{ASCII} and not contain @samp{%}. @xref{Writing R "
2127 :     "documentation files}, for more information. Note that all user-level "
2128 :     "objects in a package should be documented; if a package @var{pkg} contains "
2129 :     "user-level objects which are for ``internal'' use only, it should provide a "
2130 :     "file @file{@var{pkg}-internal.Rd} which documents all such objects, and "
2131 :     "clearly states that these are not meant to be called by the user. See e.g."
2132 :     "@: the sources for package @pkg{grid} in the @R{} distribution. Note that "
2133 :     "packages which use internal objects extensively should not export those "
2134 :     "objects from their namespace, when they do not need to be documented "
2135 :     "(@pxref{Package namespaces})."
2136 : gnustats 1336 msgstr ""
2137 : gnustats 1804
2138 : gnustats 1578 #
2139 : gnustats 1336 #. type: Plain text
2140 : gnustats 2180 #: R-exts.texi:1106
2141 : gnustats 1804 msgid ""
2142 :     "Having a @file{man} directory containing no documentation files may give an "
2143 :     "installation error."
2144 : gnustats 1336 msgstr ""
2145 : gnustats 1804
2146 : gnustats 1578 #
2147 : gnustats 1336 #. type: Plain text
2148 : gnustats 2180 #: R-exts.texi:1111
2149 : gnustats 1804 msgid ""
2150 :     "The @file{man} subdirectory may contain a subdirectory named @file{macros}; "
2151 :     "this will contain source for user-defined Rd macros. (See @ref{User-defined "
2152 :     "macros}.) These use the Rd format, but may not contain anything but macro "
2153 :     "definitions, comments and whitespace."
2154 : gnustats 1336 msgstr ""
2155 : gnustats 1804
2156 : gnustats 1578 #
2157 : gnustats 1336 #. type: Plain text
2158 : gnustats 2180 #: R-exts.texi:1114
2159 : gnustats 1804 msgid ""
2160 :     "The @file{R} and @file{man} subdirectories may contain OS-specific "
2161 :     "subdirectories named @file{unix} or @file{windows}."
2162 : gnustats 1336 msgstr ""
2163 : gnustats 1804
2164 : gnustats 1578 #
2165 : gnustats 1336 #. type: Plain text
2166 : gnustats 2180 #: R-exts.texi:1137
2167 : gnustats 1804 msgid ""
2168 :     "The sources and headers for the compiled code are in @file{src}, plus "
2169 :     "optionally a file @file{Makevars} or @file{Makefile}. When a package is "
2170 :     "installed using @code{R CMD INSTALL}, @command{make} is used to control "
2171 :     "compilation and linking into a shared object for loading into @R{}. There "
2172 :     "are default @command{make} variables and rules for this (determined when "
2173 :     "@R{} is configured and recorded in @file{@var{R_HOME}/etc@var{R_ARCH}/"
2174 :     "Makeconf}), providing support for C, C++, FORTRAN 77, Fortran "
2175 :     "9x@footnote{Note that Ratfor is not supported. If you have Ratfor source "
2176 :     "code, you need to convert it to FORTRAN. Only FORTRAN 77 (which we write in "
2177 :     "upper case) is supported on all platforms, but most also support Fortran-95 "
2178 :     "(for which we use title case). If you want to ship Ratfor source files, "
2179 :     "please do so in a subdirectory of @file{src} and not in the main "
2180 :     "subdirectory.}, Objective C and Objective C++@footnote{either or both of "
2181 :     "which may not be supported on particular platforms} with associated "
2182 :     "extensions @file{.c}, @file{.cc} or @file{.cpp}, @file{.f}, @file{.f90} or "
2183 :     "@file{.f95}, @file{.m}, and @file{.mm}, respectively. We recommend using "
2184 :     "@file{.h} for headers, also for C++@footnote{Using @file{.hpp} is not "
2185 :     "guaranteed to be portable.} or Fortran 9x include files. (Use of extension "
2186 :     "@file{.C} for C++ is no longer supported.) Files in the @file{src} "
2187 :     "directory should not be hidden (start with a dot), and hidden files will "
2188 :     "under some versions of @R{} be ignored."
2189 : gnustats 1336 msgstr ""
2190 : gnustats 1804
2191 : gnustats 1578 #
2192 : gnustats 1336 #. type: Plain text
2193 : gnustats 2180 #: R-exts.texi:1142
2194 : gnustats 1804 msgid ""
2195 :     "It is not portable (and may not be possible at all) to mix all these "
2196 :     "languages in a single package, and we do not support using both C++ and "
2197 :     "Fortran 9x. Because @R{} itself uses it, we know that C and FORTRAN 77 can "
2198 :     "be used together and mixing C and C++ seems to be widely successful."
2199 : gnustats 1336 msgstr ""
2200 : gnustats 1804
2201 : gnustats 1578 #
2202 : gnustats 1336 #. type: Plain text
2203 : gnustats 2180 #: R-exts.texi:1150
2204 : gnustats 1804 msgid ""
2205 :     "If your code needs to depend on the platform there are certain defines which "
2206 :     "can used in C or C++. On all Windows builds (even 64-bit ones) "
2207 :     "@samp{_WIN32} will be defined: on 64-bit Windows builds also @samp{_WIN64}, "
2208 :     "and on OS X @samp{__APPLE__} is defined.@footnote{There is also "
2209 :     "@samp{__APPLE_CC__}, but that indicates a compiler with Apple-specific "
2210 :     "features, not the OS. It is used in @file{Rinlinedfuns.h}.}"
2211 : gnustats 1336 msgstr ""
2212 : gnustats 1804
2213 : gnustats 1578 #
2214 : gnustats 1336 #. type: Plain text
2215 : gnustats 2180 #: R-exts.texi:1165
2216 : gnustats 1804 msgid ""
2217 :     "The default rules can be tweaked by setting macros@footnote{the POSIX "
2218 :     "terminology, called `make variables' by GNU make.} in a file @file{src/"
2219 :     "Makevars} (@pxref{Using Makevars}). Note that this mechanism should be "
2220 :     "general enough to eliminate the need for a package-specific @file{src/"
2221 :     "Makefile}. If such a file is to be distributed, considerable care is needed "
2222 :     "to make it general enough to work on all @R{} platforms. If it has any "
2223 :     "targets at all, it should have an appropriate first target named @samp{all} "
2224 :     "and a (possibly empty) target @samp{clean} which removes all files generated "
2225 :     "by running @command{make} (to be used by @samp{R CMD INSTALL --clean} and "
2226 :     "@samp{R CMD INSTALL --preclean}). There are platform-specific file names on "
2227 :     "Windows: @file{src/Makevars.win} takes precedence over @file{src/Makevars} "
2228 :     "and @file{src/Makefile.win} must be used. Some @command{make} programs "
2229 :     "require makefiles to have a complete final line, including a newline."
2230 : gnustats 1336 msgstr ""
2231 : gnustats 1804
2232 : gnustats 1578 #
2233 : gnustats 1336 #. type: Plain text
2234 : gnustats 2180 #: R-exts.texi:1170
2235 : gnustats 1804 msgid ""
2236 :     "A few packages use the @file{src} directory for purposes other than making a "
2237 :     "shared object (e.g.@: to create executables). Such packages should have "
2238 :     "files @file{src/Makefile} and @file{src/Makefile.win} (unless intended for "
2239 :     "only Unix-alikes or only Windows)."
2240 : gnustats 1336 msgstr ""
2241 : gnustats 1804
2242 : gnustats 1578 #
2243 : gnustats 1336 #. type: Plain text
2244 : gnustats 2180 #: R-exts.texi:1188
2245 : gnustats 1804 msgid ""
2246 :     "In very special cases packages may create binary files other than the shared "
2247 :     "objects/DLLs in the @file{src} directory. Such files will not be installed "
2248 :     "in a multi-architecture setting since @code{R CMD INSTALL --libs-only} is "
2249 :     "used to merge multiple sub-architectures and it only copies shared objects/"
2250 :     "DLLs. If a package wants to install other binaries (for example executable "
2251 :     "programs), it should provide an @R{} script @file{src/install.libs.R} which "
2252 :     "will be run as part of the installation in the @code{src} build directory "
2253 :     "@emph{instead of} copying the shared objects/DLLs. The script is run in a "
2254 :     "separate @R{} environment containing the following variables: "
2255 :     "@code{R_PACKAGE_NAME} (the name of the package), @code{R_PACKAGE_SOURCE} "
2256 :     "(the path to the source directory of the package), @code{R_PACKAGE_DIR} (the "
2257 :     "path of the target installation directory of the package), @code{R_ARCH} "
2258 :     "(the arch-dependent part of the path, often empty), @code{SHLIB_EXT} (the "
2259 :     "extension of shared objects) and @code{WINDOWS} (@code{TRUE} on Windows, "
2260 :     "@code{FALSE} elsewhere). Something close to the default behavior could be "
2261 :     "replicated with the following @file{src/install.libs.R} file:"
2262 : gnustats 1336 msgstr ""
2263 : gnustats 1804
2264 : gnustats 1578 #
2265 : gnustats 1336 #. type: example
2266 : gnustats 2180 #: R-exts.texi:1196
2267 : gnustats 1336 #, no-wrap
2268 :     msgid ""
2269 :     "files <- Sys.glob(paste0(\"*\", SHLIB_EXT))\n"
2270 :     "dest <- file.path(R_PACKAGE_DIR, paste0('libs', R_ARCH))\n"
2271 :     "dir.create(dest, recursive = TRUE, showWarnings = FALSE)\n"
2272 :     "file.copy(files, dest, overwrite = TRUE)\n"
2273 :     "if(file.exists(\"symbols.rds\"))\n"
2274 :     " file.copy(\"symbols.rds\", dest, overwrite = TRUE)\n"
2275 :     msgstr ""
2276 : gnustats 1804
2277 : gnustats 1578 #
2278 : gnustats 1336 #. type: Plain text
2279 : gnustats 2180 #: R-exts.texi:1200
2280 : gnustats 1804 msgid ""
2281 :     "On the other hand, executable programs could be installed along the lines of"
2282 : gnustats 1336 msgstr ""
2283 : gnustats 1804
2284 : gnustats 1578 #
2285 : gnustats 1336 #. type: example
2286 : gnustats 2180 #: R-exts.texi:1208
2287 : gnustats 1336 #, no-wrap
2288 :     msgid ""
2289 :     "execs <- c(\"one\", \"two\", \"three\")\n"
2290 :     "if(WINDOWS) execs <- paste0(execs, \".exe\")\n"
2291 :     "if ( any(file.exists(execs)) ) @{\n"
2292 :     " dest <- file.path(R_PACKAGE_DIR, paste0('bin', R_ARCH)\n"
2293 :     " dir.create(dest, recursive = TRUE, showWarnings = FALSE)\n"
2294 :     " file.copy(execs, dest, overwrite = TRUE)\n"
2295 :     "@}\n"
2296 :     msgstr ""
2297 : gnustats 1804
2298 : gnustats 1578 #
2299 : gnustats 1336 #. type: Plain text
2300 : gnustats 2180 #: R-exts.texi:1213
2301 : gnustats 1804 msgid ""
2302 :     "Note the use of architecture-specific subdirectories of @file{bin} where "
2303 :     "needed."
2304 : gnustats 1336 msgstr ""
2305 : gnustats 1804
2306 : gnustats 1578 #
2307 : gnustats 1336 #. type: Plain text
2308 : gnustats 2180 #: R-exts.texi:1215
2309 : gnustats 1804 msgid ""
2310 :     "The @file{data} subdirectory is for data files: @xref{Data in packages}."
2311 : gnustats 1336 msgstr ""
2312 : gnustats 1804
2313 : gnustats 1578 #
2314 : gnustats 1336 #. type: Plain text
2315 : gnustats 2180 #: R-exts.texi:1229
2316 : gnustats 1804 msgid ""
2317 :     "The @file{demo} subdirectory is for @R{} scripts (for running @emph{via} "
2318 :     "@code{demo()}) that demonstrate some of the functionality of the package. "
2319 :     "Demos may be interactive and are not checked automatically, so if testing is "
2320 :     "desired use code in the @file{tests} directory to achieve this. The script "
2321 :     "files must start with a (lower or upper case) letter and have one of the "
2322 :     "extensions @file{.R} or @file{.r}. If present, the @file{demo} subdirectory "
2323 :     "should also have a @file{00Index} file with one line for each demo, giving "
2324 :     "its name and a description separated by a tab or at least three spaces. "
2325 :     "(This index file is not generated automatically.) Note that a demo does not "
2326 :     "have a specified encoding and so should be an @acronym{ASCII} file "
2327 :     "(@pxref{Encoding issues}). As from @R{} 3.0.0 @code{demo()} will use the "
2328 :     "package encoding if there is one, but this is mainly useful for non-"
2329 :     "@acronym{ASCII} comments."
2330 : gnustats 1336 msgstr ""
2331 : gnustats 1804
2332 : gnustats 1578 #
2333 : gnustats 1336 #. type: cindex
2334 : gnustats 2180 #: R-exts.texi:1230
2335 : gnustats 1336 #, no-wrap
2336 :     msgid ".Rinstignore file"
2337 :     msgstr ""
2338 : gnustats 1804
2339 : gnustats 1578 #
2340 : gnustats 1336 #. type: Plain text
2341 : gnustats 2180 #: R-exts.texi:1245
2342 : gnustats 1804 msgid ""
2343 :     "The contents of the @file{inst} subdirectory will be copied recursively to "
2344 :     "the installation directory. Subdirectories of @file{inst} should not "
2345 :     "interfere with those used by @R{} (currently, @file{R}, @file{data}, "
2346 :     "@file{demo}, @file{exec}, @file{libs}, @file{man}, @file{help}, @file{html} "
2347 :     "and @file{Meta}, and earlier versions used @file{latex}, @file{R-ex}). The "
2348 :     "copying of the @file{inst} happens after @file{src} is built so its "
2349 :     "@file{Makefile} can create files to be installed. To exclude files from "
2350 :     "being installed, one can specify a list of exclude patterns in file @file{."
2351 :     "Rinstignore} in the top-level source directory. These patterns should be "
2352 :     "Perl-like regular expressions (see the help for @code{regexp} in @R{} for "
2353 :     "the precise details), one per line, to be matched case-"
2354 :     "insensitively@footnote{on all platforms from @R{} 3.1.0} against the file "
2355 :     "and directory paths, e.g.@: @file{doc/.*[.]png$} will exclude all PNG files "
2356 :     "in @file{inst/doc} based on the extension."
2357 : gnustats 1336 msgstr ""
2358 : gnustats 1804
2359 : gnustats 1578 #
2360 : gnustats 1336 #. type: Plain text
2361 : gnustats 2180 #: R-exts.texi:1255
2362 : gnustats 1804 msgid ""
2363 :     "Note that with the exceptions of @file{INDEX}, @file{LICENSE}/@file{LICENCE} "
2364 :     "and @file{NEWS}, information files at the top level of the package will "
2365 :     "@emph{not} be installed and so not be known to users of Windows and OS X "
2366 :     "compiled packages (and not seen by those who use @command{R CMD INSTALL} or "
2367 :     "@command{install.packages} on the tarball). So any information files you "
2368 :     "wish an end user to see should be included in @file{inst}. Note that if the "
2369 :     "named exceptions also occur in @file{inst}, the version in @file{inst} will "
2370 :     "be that seen in the installed package."
2371 : gnustats 1336 msgstr ""
2372 : gnustats 1804
2373 : gnustats 1578 #
2374 : gnustats 1336 #. type: findex
2375 : gnustats 2180 #: R-exts.texi:1256
2376 : gnustats 2642 #: R-exts.texi:4854
2377 : gnustats 1336 #, no-wrap
2378 :     msgid "CITATION"
2379 :     msgstr ""
2380 : gnustats 1804
2381 : gnustats 1578 #
2382 : gnustats 1336 #. type: cindex
2383 : gnustats 2180 #: R-exts.texi:1257
2384 : gnustats 2642 #: R-exts.texi:4855
2385 : gnustats 1336 #, no-wrap
2386 :     msgid "citation"
2387 :     msgstr ""
2388 : gnustats 1804
2389 : gnustats 1578 #
2390 : gnustats 1336 #. type: findex
2391 : gnustats 2180 #: R-exts.texi:1258
2392 : gnustats 1336 #, no-wrap
2393 :     msgid "NEWS.Rd"
2394 :     msgstr ""
2395 : gnustats 1804
2396 : gnustats 1578 #
2397 : gnustats 1336 #. type: cindex
2398 : gnustats 2180 #: R-exts.texi:1259
2399 : gnustats 1336 #, no-wrap
2400 :     msgid "news"
2401 :     msgstr ""
2402 : gnustats 1804
2403 : gnustats 1336 #. type: Plain text
2404 : gnustats 2180 #: R-exts.texi:1264
2405 : gnustats 1804 msgid ""
2406 :     "Things you might like to add to @file{inst} are a @file{CITATION} file for "
2407 :     "use by the @code{citation} function, and a @file{NEWS.Rd} file for use by "
2408 : gnustats 2180 "the @code{news} function. See its help page for the specific format "
2409 :     "restrictions of the @file{NEWS.Rd} file."
2410 : gnustats 1336 msgstr ""
2411 : gnustats 1804
2412 : gnustats 1578 #
2413 : gnustats 1336 #. type: findex
2414 : gnustats 2180 #: R-exts.texi:1265
2415 : gnustats 1336 #, no-wrap
2416 :     msgid "AUTHORS"
2417 :     msgstr ""
2418 : gnustats 1804
2419 : gnustats 1578 #
2420 : gnustats 1336 #. type: Plain text
2421 : gnustats 2180 #: R-exts.texi:1270
2422 : gnustats 1804 msgid ""
2423 :     "Another file sometimes needed in @file{inst} is @file{AUTHORS} or "
2424 :     "@file{COPYRIGHTS} to specify the authors or copyright holders when this is "
2425 :     "too complex to put in the @file{DESCRIPTION} file."
2426 : gnustats 1336 msgstr ""
2427 : gnustats 1804
2428 : gnustats 1578 #
2429 : gnustats 1336 #. type: Plain text
2430 : gnustats 2180 #: R-exts.texi:1294
2431 : gnustats 1804 msgid ""
2432 :     "Subdirectory @file{tests} is for additional package-specific test code, "
2433 :     "similar to the specific tests that come with the @R{} distribution. Test "
2434 :     "code can either be provided directly in a @file{.R} file, or @emph{via} a "
2435 :     "@file{.Rin} file containing code which in turn creates the corresponding "
2436 :     "@file{.R} file (e.g., by collecting all function objects in the package and "
2437 :     "then calling them with the strangest arguments). The results of running a "
2438 :     "@file{.R} file are written to a @file{.Rout} file. If there is a "
2439 :     "corresponding@footnote{The best way to generate such a file is to copy the "
2440 :     "@file{.Rout} from a successful run of @command{R CMD check}. If you want to "
2441 :     "generate it separately, do run @R{} with options @option{--vanilla --slave} "
2442 :     "and with environment variable @env{LANGUAGE=en} set to get messages in "
2443 :     "English. Be careful not to use output with the option @option{--timings} "
2444 :     "(and note that @option{--as-cran} sets it).} @file{.Rout.save} file, these "
2445 :     "two are compared, with differences being reported but not causing an error. "
2446 :     "The directory @file{tests} is copied to the check area, and the tests are "
2447 :     "run with the copy as the working directory and with @code{R_LIBS} set to "
2448 :     "ensure that the copy of the package installed during testing will be found "
2449 :     "by @code{library(@var{pkg_name})}. Note that the package-specific tests are "
2450 :     "run in a vanilla @R{} session without setting the random-number seed, so "
2451 :     "tests which use random numbers will need to set the seed to obtain "
2452 :     "reproducible results (and it can be helpful to do so in all cases, to avoid "
2453 :     "occasional failures when tests are run)."
2454 : gnustats 1336 msgstr ""
2455 : gnustats 1804
2456 : gnustats 1578 #
2457 : gnustats 1336 #. type: Plain text
2458 : gnustats 2180 #: R-exts.texi:1300
2459 : gnustats 1804 msgid ""
2460 :     "If directory @file{tests} has a subdirectory @file{Examples} containing a "
2461 :     "file @code{@var{pkg}-Ex.Rout.save}, this is compared to the output file for "
2462 :     "running the examples when the latter are checked. Reference output should "
2463 :     "be produced without having the @option{--timings} option set (and note that "
2464 :     "@option{--as-cran} sets it)."
2465 : gnustats 1336 msgstr ""
2466 : gnustats 1804
2467 : gnustats 1578 #
2468 : gnustats 1336 #. type: Plain text
2469 : gnustats 2180 #: R-exts.texi:1310
2470 : gnustats 1804 msgid ""
2471 :     "Subdirectory @file{exec} could contain additional executable scripts the "
2472 :     "package needs, typically scripts for interpreters such as the shell, Perl, "
2473 :     "or Tcl. NB: only files (and not directories) under @file{exec} are "
2474 :     "installed (and those with names starting with a dot are ignored), and they "
2475 :     "are all marked as executable (mode @code{755}, moderated by @samp{umask}) on "
2476 :     "POSIX platforms. Note too that this is not suitable for executable "
2477 :     "@emph{programs} since some platforms (including Windows) support multiple "
2478 :     "architectures using the same installed package directory."
2479 : gnustats 1336 msgstr ""
2480 : gnustats 1804
2481 : gnustats 1578 #
2482 : gnustats 1336 #. type: Plain text
2483 : gnustats 2180 #: R-exts.texi:1313
2484 : gnustats 1804 msgid ""
2485 :     "Subdirectory @file{po} is used for files related to @emph{localization}: "
2486 :     "@pxref{Internationalization}."
2487 : gnustats 1336 msgstr ""
2488 : gnustats 1804
2489 : gnustats 1578 #
2490 : gnustats 1336 #. type: Plain text
2491 : gnustats 2180 #: R-exts.texi:1317
2492 : gnustats 1804 msgid ""
2493 :     "Subdirectory @file{tools} is the preferred place for auxiliary files needed "
2494 :     "during configuration, and also for sources need to re-create scripts (e.g.@: "
2495 :     "M4 files for @command{autoconf})."
2496 : gnustats 1336 msgstr ""
2497 : gnustats 1804
2498 : gnustats 1578 #
2499 : gnustats 1336 #. type: Plain text
2500 : gnustats 2180 #: R-exts.texi:1328
2501 : gnustats 1804 msgid ""
2502 :     "The @file{data} subdirectory is for data files, either to be made available "
2503 :     "@emph{via} lazy-loading or for loading using @code{data()}. (The choice is "
2504 :     "made by the @samp{LazyData} field in the @file{DESCRIPTION} file: the "
2505 :     "default is not to do so.) It should not be used for other data files needed "
2506 :     "by the package, and the convention has grown up to use directory @file{inst/"
2507 :     "extdata} for such files."
2508 : gnustats 1336 msgstr ""
2509 : gnustats 1804
2510 : gnustats 1336 #. type: Plain text
2511 : gnustats 2180 #: R-exts.texi:1339
2512 : gnustats 1804 msgid ""
2513 :     "Data files can have one of three types as indicated by their extension: "
2514 :     "plain @R{} code (@file{.R} or @file{.r}), tables (@file{.tab}, @file{.txt}, "
2515 :     "or @file{.csv}, see @code{?data} for the file formats, and note that @file{."
2516 : gnustats 2640 "csv} is @strong{not} the standard@footnote{e.g.@: @uref{https://tools.ietf."
2517 : gnustats 1804 "org/@/html/@/rfc4180}.} CSV format), or @code{save()} images (@file{.RData} "
2518 :     "or @file{.rda}). The files should not be hidden (have names starting with a "
2519 :     "dot). Note that @R{} code should be ``self-sufficient'' and not make use of "
2520 :     "extra functionality provided by the package, so that the data file can also "
2521 :     "be used without having to load the package or its namespace."
2522 : gnustats 1336 msgstr ""
2523 : gnustats 1804
2524 : gnustats 1578 #
2525 : gnustats 1336 #. type: Plain text
2526 : gnustats 2180 #: R-exts.texi:1350
2527 : gnustats 1804 msgid ""
2528 :     "Images (extensions @file{.RData}@footnote{People who have trouble with case "
2529 :     "are advised to use @file{.rda} as a common error is to refer to @file{abc."
2530 :     "RData} as @file{abc.Rdata}!} or @file{.rda}) can contain references to the "
2531 :     "namespaces of packages that were used to create them. Preferably there "
2532 :     "should be no such references in data files, and in any case they should only "
2533 :     "be to packages listed in the @code{Depends} and @code{Imports} fields, as "
2534 :     "otherwise it may be impossible to install the package. To check for such "
2535 :     "references, load all the images into a vanilla @R{} session, and look at the "
2536 :     "output of @code{loadedNamespaces()}."
2537 : gnustats 1336 msgstr ""
2538 : gnustats 1804
2539 : gnustats 1578 #
2540 : gnustats 1336 #. type: Plain text
2541 : gnustats 2180 #: R-exts.texi:1359
2542 : gnustats 1804 msgid ""
2543 :     "If your data files are large and you are not using @samp{LazyData} you can "
2544 :     "speed up installation by providing a file @file{datalist} in the @file{data} "
2545 :     "subdirectory. This should have one line per topic that @code{data()} will "
2546 :     "find, in the format @samp{foo} if @code{data(foo)} provides @samp{foo}, or "
2547 :     "@samp{foo: bar bah} if @code{data(foo)} provides @samp{bar} and @samp{bah}. "
2548 :     "@command{R CMD build} will automatically add a @file{datalist} file to "
2549 :     "@file{data} directories of over 1Mb, using the function @code{tools::"
2550 :     "add_datalist}."
2551 : gnustats 1336 msgstr ""
2552 : gnustats 1804
2553 : gnustats 1578 #
2554 : gnustats 1336 #. type: Plain text
2555 : gnustats 2180 #: R-exts.texi:1364
2556 : gnustats 1804 msgid ""
2557 :     "Tables (@file{.tab}, @file{.txt}, or @file{.csv} files) can be compressed by "
2558 :     "@command{gzip}, @command{bzip2} or @command{xz}, optionally with additional "
2559 :     "extension @file{.gz}, @file{.bz2} or @file{.xz}."
2560 : gnustats 1336 msgstr ""
2561 : gnustats 1804
2562 : gnustats 1578 #
2563 : gnustats 1336 #. type: Plain text
2564 : gnustats 2180 #: R-exts.texi:1373
2565 : gnustats 1804 msgid ""
2566 :     "If your package is to be distributed, do consider the resource implications "
2567 :     "of large datasets for your users: they can make packages very slow to "
2568 :     "download and use up unwelcome amounts of storage space, as well as taking "
2569 :     "many seconds to load. It is normally best to distribute large datasets as "
2570 :     "@file{.rda} images prepared by @code{save(, compress = TRUE)} (the "
2571 :     "default). Using @command{bzip2} or @command{xz} compression will usually "
2572 :     "reduce the size of both the package tarball and the installed package, in "
2573 :     "some cases by a factor of two or more."
2574 : gnustats 1336 msgstr ""
2575 : gnustats 1804
2576 : gnustats 1578 #
2577 : gnustats 1336 #. type: Plain text
2578 : gnustats 2180 #: R-exts.texi:1378
2579 : gnustats 1804 msgid ""
2580 :     "Package @pkg{tools} has a couple of functions to help with data images: "
2581 :     "@code{checkRdaFiles} reports on the way the image was saved, and "
2582 :     "@code{resaveRdaFiles} will re-save with a different type of compression, "
2583 :     "including choosing the best type for that particular image."
2584 : gnustats 1336 msgstr ""
2585 : gnustats 1804
2586 : gnustats 1578 #
2587 : gnustats 1336 #. type: Plain text
2588 : gnustats 2180 #: R-exts.texi:1388
2589 : gnustats 1804 msgid ""
2590 :     "Some packages using @samp{LazyData} will benefit from using a form of "
2591 :     "compression other than @command{gzip} in the installed lazy-loading "
2592 :     "database. This can be selected by the @option{--data-compress} option to "
2593 :     "@command{R CMD INSTALL} or by using the @samp{LazyDataCompression} field in "
2594 :     "the @file{DESCRIPTION} file. Useful values are @code{bzip2}, @code{xz} and "
2595 :     "the default, @code{gzip}. The only way to discover which is best is to try "
2596 :     "them all and look at the size of the @file{@var{pkgname}/data/Rdata.rdb} "
2597 :     "file."
2598 : gnustats 1336 msgstr ""
2599 : gnustats 1804
2600 : gnustats 1578 #
2601 : gnustats 1336 #. type: Plain text
2602 : gnustats 2180 #: R-exts.texi:1392
2603 : gnustats 1804 msgid ""
2604 :     "Lazy-loading is not supported for very large datasets (those which when "
2605 :     "serialized exceed 2GB, the limit for the format on 32-bit platforms and all "
2606 :     "platforms prior to @R{} 3.0.0)."
2607 : gnustats 1336 msgstr ""
2608 : gnustats 1804
2609 : gnustats 1578 #
2610 : gnustats 1336 #. type: Plain text
2611 : gnustats 2180 #: R-exts.texi:1397
2612 : gnustats 1804 msgid ""
2613 :     "The analogue for @file{sysdata.rda} is field @samp{SysDataCompression}: the "
2614 :     "default (since @R{} 2.12.2) is @code{xz} for files bigger than 1MB otherwise "
2615 :     "@code{gzip}."
2616 : gnustats 1336 msgstr ""
2617 : gnustats 1804
2618 : gnustats 1578 #
2619 : gnustats 1336 #. type: Plain text
2620 : gnustats 2180 #: R-exts.texi:1404
2621 : gnustats 1804 msgid ""
2622 :     "Code which needs to be compiled (C, C++, FORTRAN, Fortran 95 @dots{}) is "
2623 :     "included in the @file{src} subdirectory and discussed elsewhere in this "
2624 :     "document."
2625 : gnustats 1336 msgstr ""
2626 : gnustats 1804
2627 : gnustats 1578 #
2628 : gnustats 1336 #. type: Plain text
2629 : gnustats 2180 #: R-exts.texi:1412
2630 : gnustats 1804 msgid ""
2631 :     "Subdirectory @file{exec} could be used for scripts for interpreters such as "
2632 :     "the shell, BUGS, JavaScript, Matlab, Perl, php (@CRANpkg{amap}), Python or "
2633 :     "Tcl (@CRANpkg{Simile}), or even @R{}. However, it seems more common to use "
2634 :     "the @file{inst} directory, for example @file{WriteXLS/inst/Perl}, @file{NMF/"
2635 :     "inst/m-files}, @file{RnavGraph/inst/tcl}, @file{RProtoBuf/inst/python} and "
2636 :     "@file{emdbook/inst/BUGS} and @file{gridSVG/inst/js}."
2637 : gnustats 1336 msgstr ""
2638 : gnustats 1804
2639 : gnustats 1578 #
2640 : gnustats 1336 #. type: Plain text
2641 : gnustats 2180 #: R-exts.texi:1420
2642 : gnustats 1804 msgid ""
2643 :     "Java code is a special case: except for very small programs, @file{.java} "
2644 :     "files should be byte-compiled (to a @file{.class} file) and distributed as "
2645 :     "part of a @file{.jar} file: the conventional location for the @file{.jar} "
2646 :     "file(s) is @file{inst/java}. It is desirable (and required under an Open "
2647 :     "Source license) to make the Java source files available: this is best done "
2648 :     "in a top-level @file{java} directory in the package---the source files "
2649 :     "should not be installed."
2650 : gnustats 1336 msgstr ""
2651 : gnustats 1804
2652 : gnustats 1578 #
2653 : gnustats 1336 #. type: Plain text
2654 : gnustats 2180 #: R-exts.texi:1425
2655 : gnustats 1804 msgid ""
2656 :     "If your package requires one of these interpreters or an extension then this "
2657 :     "should be declared in the @samp{SystemRequirements} field of its "
2658 :     "@file{DESCRIPTION} file. (Users of Java most often do so @emph{via} "
2659 :     "@CRANpkg{rJava}, when depending on/importing that suffices.)"
2660 : gnustats 1336 msgstr ""
2661 : gnustats 1804
2662 : gnustats 1336 #. type: Plain text
2663 : gnustats 2642 #: R-exts.texi:1433
2664 : gnustats 1804 msgid ""
2665 :     "Windows and Mac users should be aware that the Tcl extensions @samp{BWidget} "
2666 :     "and @samp{Tktable} which are currently included with the @R{} for Windows "
2667 : gnustats 2642 "and in the OS X installers @emph{are} extensions and do need to be declared "
2668 :     "for users of other platforms (and that @samp{Tktable} is less widely "
2669 :     "available than it used to be, including not in the main repositories for "
2670 :     "major Linux distributions)."
2671 : gnustats 1336 msgstr ""
2672 : gnustats 1804
2673 : gnustats 1336 #. type: Plain text
2674 : gnustats 2642 #: R-exts.texi:1436
2675 : gnustats 1804 msgid ""
2676 : gnustats 2180 "@samp{BWidget} needs to be installed by the user on other OSes. This is "
2677 :     "fairly easy to do: first find the Tcl/Tk search path:"
2678 : gnustats 1336 msgstr ""
2679 : gnustats 1804
2680 : gnustats 1578 #
2681 : gnustats 1336 #. type: example
2682 : gnustats 2642 #: R-exts.texi:1440
2683 : gnustats 1336 #, no-wrap
2684 :     msgid ""
2685 :     "library(tcltk)\n"
2686 :     "strsplit(tclvalue('auto_path'), \" \")[[1]]\n"
2687 :     msgstr ""
2688 : gnustats 1804
2689 : gnustats 1336 #. type: Plain text
2690 : gnustats 2642 #: R-exts.texi:1446
2691 : gnustats 1804 msgid ""
2692 :     "then download the sources from @uref{http://sourceforge.net/@/projects/@/"
2693 : gnustats 2180 "tcllib/@/files/@/BWidget/} and at the command line run something like"
2694 : gnustats 1336 msgstr ""
2695 : gnustats 1804
2696 : gnustats 1336 #. type: example
2697 : gnustats 2642 #: R-exts.texi:1450
2698 : gnustats 1336 #, no-wrap
2699 :     msgid ""
2700 : gnustats 2180 "tar xf bwidget-1.9.8.tar.gz\n"
2701 :     "sudo mv bwidget-1.9.8 /usr/local/lib\n"
2702 : gnustats 1336 msgstr ""
2703 : gnustats 1804
2704 : gnustats 1578 #
2705 : gnustats 1336 #. type: Plain text
2706 : gnustats 2642 #: R-exts.texi:1455
2707 : gnustats 1804 msgid ""
2708 :     "substituting a location on the Tcl/Tk search path for @file{/usr/local/lib} "
2709 :     "if needed."
2710 : gnustats 1336 msgstr ""
2711 : gnustats 1804
2712 : gnustats 2180 #. type: Plain text
2713 : gnustats 2642 #: R-exts.texi:1462
2714 : gnustats 2180 msgid ""
2715 :     "URLs in many places in the package documentation will be converted to "
2716 :     "clickable hyperlinks in at least some of their renderings. So care is "
2717 :     "needed that their forms are correct and portable."
2718 :     msgstr ""
2719 :    
2720 :     #. type: Plain text
2721 : gnustats 2642 #: R-exts.texi:1465
2722 : gnustats 2180 msgid ""
2723 : gnustats 2642 "The full URL should be given, including the scheme (often @samp{http://} or "
2724 :     "@samp{https://}) and a final @samp{/} for references to directories."
2725 : gnustats 2180 msgstr ""
2726 :    
2727 :     #. type: Plain text
2728 : gnustats 2642 #: R-exts.texi:1470
2729 : gnustats 2180 msgid ""
2730 :     "Spaces in URLs are not portable and how they are handled does vary by HTTP "
2731 :     "server and by client. There should be no space in the host part of an "
2732 :     "@samp{http://} URL, and spaces in the remainder should be encoded, with each "
2733 :     "space replaced by @samp{%20}."
2734 :     msgstr ""
2735 :    
2736 :     #. type: Plain text
2737 : gnustats 2642 #: R-exts.texi:1473
2738 : gnustats 2180 msgid ""
2739 :     "Other characters may benefit from being encoded: see the help on "
2740 :     "@code{URLencode()}."
2741 :     msgstr ""
2742 :    
2743 :     #. type: Plain text
2744 : gnustats 2642 #: R-exts.texi:1475
2745 : gnustats 2180 msgid "The canonical URL for a @acronym{CRAN} package is"
2746 :     msgstr ""
2747 :    
2748 :     #. type: example
2749 : gnustats 2642 #: R-exts.texi:1477
2750 : gnustats 2180 #, no-wrap
2751 : gnustats 2640 msgid "https://cran.r-project.org/package=@var{pkgname}\n"
2752 : gnustats 2180 msgstr ""
2753 :    
2754 :     #. type: Plain text
2755 : gnustats 2642 #: R-exts.texi:1482
2756 : gnustats 2180 msgid ""
2757 :     "and not a version starting @samp{http://cran.r-project.org/web/packages/"
2758 :     "@var{pkgname}}."
2759 :     msgstr ""
2760 :    
2761 : gnustats 1578 #
2762 : gnustats 1336 #. type: Plain text
2763 : gnustats 2642 #: R-exts.texi:1488
2764 : gnustats 1804 msgid ""
2765 :     "Note that most of this section is specific to Unix-alikes: see the comments "
2766 :     "later on about the Windows port of @R{}."
2767 : gnustats 1336 msgstr ""
2768 : gnustats 1804
2769 : gnustats 1578 #
2770 : gnustats 1336 #. type: Plain text
2771 : gnustats 2642 #: R-exts.texi:1500
2772 : gnustats 1804 msgid ""
2773 :     "If your package needs some system-dependent configuration before "
2774 :     "installation you can include an executable (Bourne shell) script "
2775 :     "@file{configure} in your package which (if present) is executed by @code{R "
2776 :     "CMD INSTALL} before any other action is performed. This can be a script "
2777 :     "created by the Autoconf mechanism, but may also be a script written by "
2778 :     "yourself. Use this to detect if any nonstandard libraries are present such "
2779 :     "that corresponding code in the package can be disabled at install time "
2780 :     "rather than giving error messages when the package is compiled or used. To "
2781 :     "summarize, the full power of Autoconf is available for your extension "
2782 :     "package (including variable substitution, searching for libraries, etc.)."
2783 : gnustats 1336 msgstr ""
2784 : gnustats 1804
2785 : gnustats 1578 #
2786 : gnustats 1336 #. type: Plain text
2787 : gnustats 2642 #: R-exts.texi:1505
2788 : gnustats 1804 msgid ""
2789 :     "Under a Unix-alike only, an executable (Bourne shell) script @file{cleanup} "
2790 :     "is executed as the last thing by @code{R CMD INSTALL} if option @option{--"
2791 :     "clean} was given, and by @code{R CMD build} when preparing the package for "
2792 :     "building from its source."
2793 : gnustats 1336 msgstr ""
2794 : gnustats 1804
2795 : gnustats 1578 #
2796 : gnustats 1336 #. type: Plain text
2797 : gnustats 2642 #: R-exts.texi:1515
2798 : gnustats 1804 msgid ""
2799 :     "As an example consider we want to use functionality provided by a (C or "
2800 :     "FORTRAN) library @code{foo}. Using Autoconf, we can create a configure "
2801 :     "script which checks for the library, sets variable @code{HAVE_FOO} to "
2802 :     "@code{TRUE} if it was found and to @code{FALSE} otherwise, and then "
2803 :     "substitutes this value into output files (by replacing instances of "
2804 :     "@samp{@@HAVE_FOO@@} in input files with the value of @code{HAVE_FOO}). For "
2805 :     "example, if a function named @code{bar} is to be made available by linking "
2806 :     "against library @code{foo} (i.e., using @option{-lfoo}), one could use"
2807 : gnustats 1336 msgstr ""
2808 : gnustats 1804
2809 : gnustats 1578 #
2810 : gnustats 1336 #. type: group
2811 : gnustats 2642 #: R-exts.texi:1523
2812 : gnustats 1336 #, no-wrap
2813 :     msgid ""
2814 :     "AC_CHECK_LIB(foo, @var{fun}, [HAVE_FOO=TRUE], [HAVE_FOO=FALSE])\n"
2815 :     "AC_SUBST(HAVE_FOO)\n"
2816 :     "......\n"
2817 :     "AC_CONFIG_FILES([foo.R])\n"
2818 :     "AC_OUTPUT\n"
2819 :     msgstr ""
2820 : gnustats 1804
2821 : gnustats 1578 #
2822 : gnustats 1336 #. type: Plain text
2823 : gnustats 2642 #: R-exts.texi:1528
2824 : gnustats 1336 msgid "in @file{configure.ac} (assuming Autoconf 2.50 or later)."
2825 :     msgstr ""
2826 : gnustats 1804
2827 : gnustats 1578 #
2828 : gnustats 1336 #. type: Plain text
2829 : gnustats 2642 #: R-exts.texi:1530
2830 : gnustats 1804 msgid ""
2831 :     "The definition of the respective @R{} function in @file{foo.R.in} could be"
2832 : gnustats 1336 msgstr ""
2833 : gnustats 1804
2834 : gnustats 1578 #
2835 : gnustats 1336 #. type: group
2836 : gnustats 2642 #: R-exts.texi:1537
2837 : gnustats 1336 #, no-wrap
2838 :     msgid ""
2839 :     "foo <- function(x) @{\n"
2840 :     " if(!@@HAVE_FOO@@)\n"
2841 :     " stop(\"Sorry, library 'foo' is not available\"))\n"
2842 :     " ...\n"
2843 :     msgstr ""
2844 : gnustats 1804
2845 : gnustats 1578 #
2846 : gnustats 1336 #. type: Plain text
2847 : gnustats 2642 #: R-exts.texi:1543
2848 : gnustats 1804 msgid ""
2849 :     "From this file @command{configure} creates the actual @R{} source file "
2850 :     "@file{foo.R} looking like"
2851 : gnustats 1336 msgstr ""
2852 : gnustats 1804
2853 : gnustats 1578 #
2854 : gnustats 1336 #. type: group
2855 : gnustats 2642 #: R-exts.texi:1550
2856 : gnustats 1336 #, no-wrap
2857 :     msgid ""
2858 :     "foo <- function(x) @{\n"
2859 :     " if(!FALSE)\n"
2860 :     " stop(\"Sorry, library 'foo' is not available\"))\n"
2861 :     " ...\n"
2862 :     msgstr ""
2863 : gnustats 1804
2864 : gnustats 1578 #
2865 : gnustats 1336 #. type: Plain text
2866 : gnustats 2642 #: R-exts.texi:1556
2867 : gnustats 1804 msgid ""
2868 :     "if library @code{foo} was not found (with the desired functionality). In "
2869 :     "this case, the above @R{} code effectively disables the function."
2870 : gnustats 1336 msgstr ""
2871 : gnustats 1804
2872 : gnustats 1578 #
2873 : gnustats 1336 #. type: Plain text
2874 : gnustats 2642 #: R-exts.texi:1559
2875 : gnustats 1804 msgid ""
2876 :     "One could also use different file fragments for available and missing "
2877 :     "functionality, respectively."
2878 : gnustats 1336 msgstr ""
2879 : gnustats 1804
2880 : gnustats 1578 #
2881 : gnustats 1336 #. type: Plain text
2882 : gnustats 2642 #: R-exts.texi:1564
2883 : gnustats 1804 msgid ""
2884 :     "You will very likely need to ensure that the same C compiler and compiler "
2885 :     "flags are used in the @file{configure} tests as when compiling @R{} or your "
2886 :     "package. Under a Unix-alike, you can achieve this by including the "
2887 :     "following fragment early in @file{configure.ac}"
2888 : gnustats 1336 msgstr ""
2889 : gnustats 1804
2890 : gnustats 1578 #
2891 : gnustats 1336 #. type: group
2892 : gnustats 2642 #: R-exts.texi:1575
2893 : gnustats 1336 #, no-wrap
2894 :     msgid ""
2895 :     ": $@{R_HOME=`R RHOME`@}\n"
2896 :     "if test -z \"$@{R_HOME@}\"; then\n"
2897 :     " echo \"could not determine R_HOME\"\n"
2898 :     " exit 1\n"
2899 :     "fi\n"
2900 :     "CC=`\"$@{R_HOME@}/bin/R\" CMD config CC`\n"
2901 :     "CFLAGS=`\"$@{R_HOME@}/bin/R\" CMD config CFLAGS`\n"
2902 :     "CPPFLAGS=`\"$@{R_HOME@}/bin/R\" CMD config CPPFLAGS`\n"
2903 :     msgstr ""
2904 : gnustats 1804
2905 : gnustats 1578 #
2906 : gnustats 1336 #. type: Plain text
2907 : gnustats 2642 #: R-exts.texi:1583
2908 : gnustats 1804 msgid ""
2909 :     "(Using @samp{$@{R_HOME@}/bin/R} rather than just @samp{R} is necessary in "
2910 :     "order to use the correct version of @R{} when running the script as part of "
2911 :     "@code{R CMD INSTALL}, and the quotes since @samp{$@{R_HOME@}} might contain "
2912 :     "spaces.)"
2913 : gnustats 1336 msgstr ""
2914 : gnustats 1804
2915 : gnustats 1578 #
2916 : gnustats 1336 #. type: Plain text
2917 : gnustats 2642 #: R-exts.texi:1585
2918 : gnustats 1336 msgid "If your code does load checks then you may also need"
2919 :     msgstr ""
2920 : gnustats 1804
2921 : gnustats 1578 #
2922 : gnustats 1336 #. type: example
2923 : gnustats 2642 #: R-exts.texi:1587
2924 : gnustats 1336 #, no-wrap
2925 :     msgid "LDFLAGS=`\"$@{R_HOME@}/bin/R\" CMD config LDFLAGS`\n"
2926 :     msgstr ""
2927 : gnustats 1804
2928 : gnustats 1578 #
2929 : gnustats 1336 #. type: Plain text
2930 : gnustats 2642 #: R-exts.texi:1592
2931 : gnustats 1804 msgid ""
2932 :     "and packages written with C++ need to pick up the details for the C++ "
2933 :     "compiler and switch the current language to C++ by"
2934 : gnustats 1336 msgstr ""
2935 : gnustats 1804
2936 : gnustats 1578 #
2937 : gnustats 1336 #. type: example
2938 : gnustats 2642 #: R-exts.texi:1594
2939 : gnustats 1336 #, no-wrap
2940 :     msgid "AC_LANG(C++)\n"
2941 :     msgstr ""
2942 : gnustats 1804
2943 : gnustats 1578 #
2944 : gnustats 1336 #. type: Plain text
2945 : gnustats 2642 #: R-exts.texi:1599
2946 : gnustats 1804 msgid ""
2947 :     "The latter is important, as for example C headers may not be available to C+"
2948 :     "+ programs or may not be written to avoid C++ name-mangling."
2949 : gnustats 1336 msgstr ""
2950 : gnustats 1804
2951 : gnustats 1578 #
2952 : gnustats 1336 #. type: findex
2953 : gnustats 2642 #: R-exts.texi:1600
2954 : gnustats 1336 #, no-wrap
2955 :     msgid "R CMD config"
2956 :     msgstr ""
2957 : gnustats 1804
2958 : gnustats 1578 #
2959 : gnustats 1336 #. type: Plain text
2960 : gnustats 2642 #: R-exts.texi:1605
2961 : gnustats 1804 msgid ""
2962 :     "You can use @code{R CMD config} for getting the value of the basic "
2963 :     "configuration variables, and also the header and library flags necessary for "
2964 :     "linking a front-end executable program against @R{}, see @kbd{R CMD config --"
2965 :     "help} for details."
2966 : gnustats 1336 msgstr ""
2967 : gnustats 1804
2968 : gnustats 1578 #
2969 : gnustats 1336 #. type: Plain text
2970 : gnustats 2642 #: R-exts.texi:1608
2971 : gnustats 1804 msgid ""
2972 :     "To check for an external BLAS library using the @code{ACX_BLAS} macro from "
2973 :     "the official Autoconf Macro Archive, one can simply do"
2974 : gnustats 1336 msgstr ""
2975 : gnustats 1804
2976 : gnustats 1578 #
2977 : gnustats 1336 #. type: group
2978 : gnustats 2642 #: R-exts.texi:1615
2979 : gnustats 1336 #, no-wrap
2980 :     msgid ""
2981 :     "F77=`\"$@{R_HOME@}/bin/R\" CMD config F77`\n"
2982 :     "AC_PROG_F77\n"
2983 :     "FLIBS=`\"$@{R_HOME@}/bin/R\" CMD config FLIBS`\n"
2984 :     "ACX_BLAS([], AC_MSG_ERROR([could not find your BLAS library], 1))\n"
2985 :     msgstr ""
2986 : gnustats 1804
2987 : gnustats 1578 #
2988 : gnustats 1336 #. type: Plain text
2989 : gnustats 2642 #: R-exts.texi:1624
2990 : gnustats 1804 msgid ""
2991 :     "Note that @code{FLIBS} as determined by @R{} must be used to ensure that "
2992 :     "FORTRAN 77 code works on all @R{} platforms. Calls to the Autoconf macro "
2993 :     "@code{AC_F77_LIBRARY_LDFLAGS}, which would overwrite @code{FLIBS}, must not "
2994 :     "be used (and hence e.g.@: removed from @code{ACX_BLAS}). (Recent versions "
2995 :     "of Autoconf in fact allow an already set @code{FLIBS} to override the test "
2996 :     "for the FORTRAN linker flags.)"
2997 : gnustats 1336 msgstr ""
2998 : gnustats 1804
2999 : gnustats 1578 #
3000 : gnustats 1336 #. type: Plain text
3001 : gnustats 2642 #: R-exts.texi:1631
3002 : gnustats 1804 msgid ""
3003 :     "@strong{N.B.}: If the @command{configure} script creates files, e.g.@: "
3004 :     "@file{src/Makevars}, you do need a @command{cleanup} script to remove them. "
3005 :     "Otherwise if the package has vignettes, @command{R CMD build} will ship the "
3006 :     "files that are created. For example, package @CRANpkg{RODBC} has"
3007 : gnustats 1336 msgstr ""
3008 : gnustats 1804
3009 : gnustats 1578 #
3010 : gnustats 1336 #. type: example
3011 : gnustats 2642 #: R-exts.texi:1634
3012 : gnustats 1336 #, no-wrap
3013 :     msgid ""
3014 :     "#!/bin/sh\n"
3015 :     "\n"
3016 :     msgstr ""
3017 : gnustats 1804
3018 : gnustats 1578 #
3019 : gnustats 1336 #. type: example
3020 : gnustats 2642 #: R-exts.texi:1636
3021 : gnustats 1336 #, no-wrap
3022 :     msgid "rm -f config.* src/Makevars src/config.h\n"
3023 :     msgstr ""
3024 : gnustats 1804
3025 : gnustats 1578 #
3026 : gnustats 1336 #. type: Plain text
3027 : gnustats 2642 #: R-exts.texi:1641
3028 : gnustats 1804 msgid ""
3029 :     "As this example shows, @command{configure} often creates working files such "
3030 :     "as @file{config.log}."
3031 : gnustats 1336 msgstr ""
3032 : gnustats 1804
3033 : gnustats 1578 #
3034 : gnustats 1336 #. type: Plain text
3035 : gnustats 2642 #: R-exts.texi:1644
3036 : gnustats 1804 msgid ""
3037 :     "If your configure script needs auxiliary files, it is recommended that you "
3038 :     "ship them in a @file{tools} directory (as @R{} itself does)."
3039 : gnustats 1336 msgstr ""
3040 : gnustats 1804
3041 : gnustats 1578 #
3042 : gnustats 1336 #. type: Plain text
3043 : gnustats 2642 #: R-exts.texi:1659
3044 : gnustats 1804 msgid ""
3045 :     "You should bear in mind that the configure script will not be used on "
3046 :     "Windows systems. If your package is to be made publicly available, please "
3047 :     "give enough information for a user on a non-Unix-alike platform to configure "
3048 :     "it manually, or provide a @file{configure.win} script to be used on that "
3049 :     "platform. (Optionally, there can be a @file{cleanup.win} script. Both "
3050 :     "should be shell scripts to be executed by @command{ash}, which is a minimal "
3051 :     "version of Bourne-style @command{sh}.) When @file{configure.win} is run the "
3052 :     "environment variables @env{R_HOME} (which uses @samp{/} as the file "
3053 :     "separator), @env{R_ARCH} and Use @env{R_ARCH_BIN} will be set. Use "
3054 :     "@env{R_ARCH} to decide if this is a 64-bit build (its value there is @samp{/"
3055 :     "x64}) and to install DLLs to the correct place (@file{$@{R_HOME@}/libs"
3056 :     "$@{R_ARCH@}}). Use @env{R_ARCH_BIN} to find the correct place under the "
3057 :     "@file{bin} directory, e.g.@: @file{$@{R_HOME@}/bin$@{R_ARCH_BIN@}/Rscript."
3058 :     "exe}."
3059 : gnustats 1336 msgstr ""
3060 : gnustats 1804
3061 : gnustats 1578 #
3062 : gnustats 1336 #. type: Plain text
3063 : gnustats 2642 #: R-exts.texi:1673
3064 : gnustats 1804 msgid ""
3065 :     "In some rare circumstances, the configuration and cleanup scripts need to "
3066 :     "know the location into which the package is being installed. An example of "
3067 :     "this is a package that uses C code and creates two shared object/DLLs. "
3068 :     "Usually, the object that is dynamically loaded by @R{} is linked against the "
3069 :     "second, dependent, object. On some systems, we can add the location of this "
3070 :     "dependent object to the object that is dynamically loaded by @R{}. This "
3071 :     "means that each user does not have to set the value of the "
3072 :     "@env{LD_LIBRARY_PATH} (or equivalent) environment variable, but that the "
3073 :     "secondary object is automatically resolved. Another example is when a "
3074 :     "package installs support files that are required at run time, and their "
3075 :     "location is substituted into an @R{} data structure at installation time. "
3076 :     "(This happens with the Java Archive files in the Omegahat @pkg{SJava} "
3077 :     "package.)"
3078 : gnustats 1336 msgstr ""
3079 : gnustats 1804
3080 : gnustats 1578 #
3081 : gnustats 1336 #. type: vindex
3082 : gnustats 2642 #: R-exts.texi:1673
3083 : gnustats 1336 #, no-wrap
3084 :     msgid "R_LIBRARY_DIR"
3085 :     msgstr ""
3086 : gnustats 1804
3087 : gnustats 1578 #
3088 : gnustats 1336 #. type: vindex
3089 : gnustats 2642 #: R-exts.texi:1674
3090 : gnustats 1336 #, no-wrap
3091 :     msgid "R_PACKAGE_DIR"
3092 :     msgstr ""
3093 : gnustats 1804
3094 : gnustats 1578 #
3095 : gnustats 1336 #. type: vindex
3096 : gnustats 2642 #: R-exts.texi:1675
3097 : gnustats 1336 #, no-wrap
3098 :     msgid "R_PACKAGE_NAME"
3099 :     msgstr ""
3100 : gnustats 1804
3101 : gnustats 1578 #
3102 : gnustats 1336 #. type: Plain text
3103 : gnustats 2642 #: R-exts.texi:1689
3104 : gnustats 1804 msgid ""
3105 :     "The names of the top-level library directory (i.e., specifiable @emph{via} "
3106 :     "the @samp{-l} argument) and the directory of the package itself are made "
3107 :     "available to the installation scripts @emph{via} the two shell/environment "
3108 :     "variables @env{R_LIBRARY_DIR} and @env{R_PACKAGE_DIR}. Additionally, the "
3109 :     "name of the package (e.g.@: @samp{survival} or @samp{MASS}) being installed "
3110 :     "is available from the environment variable @env{R_PACKAGE_NAME}. (Currently "
3111 :     "the value of @env{R_PACKAGE_DIR} is always @code{$@{R_LIBRARY_DIR@}/"
3112 :     "$@{R_PACKAGE_NAME@}}, but this used not to be the case when versioned "
3113 :     "installs were allowed. Its main use is in @file{configure.win} scripts for "
3114 :     "the installation path of external software's DLLs.) Note that the value of "
3115 :     "@env{R_PACKAGE_DIR} may contain spaces and other shell-unfriendly "
3116 :     "characters, and so should be quoted in makefiles and configure scripts."
3117 : gnustats 1336 msgstr ""
3118 : gnustats 1804
3119 : gnustats 1578 #
3120 : gnustats 1336 #. type: Plain text
3121 : gnustats 2642 #: R-exts.texi:1698
3122 : gnustats 1804 msgid ""
3123 :     "One of the more tricky tasks can be to find the headers and libraries of "
3124 :     "external software. One tool which is increasingly available on Unix-alikes "
3125 :     "(but not by default on OS X) to do this is @command{pkg-config}. The "
3126 :     "@file{configure} script will need to test for the presence of the command "
3127 :     "itself (see for example package @CRANpkg{Cairo}), and if present it can be "
3128 :     "asked if the software is installed, of a suitable version and for "
3129 :     "compilation/linking flags by e.g.@:"
3130 : gnustats 1336 msgstr ""
3131 : gnustats 1804
3132 : gnustats 1578 #
3133 : gnustats 1336 #. type: example
3134 : gnustats 2642 #: R-exts.texi:1707
3135 : gnustats 1336 #, no-wrap
3136 :     msgid ""
3137 :     "$ pkg-config --exists 'QtCore >= 4.0.0' # check the status\n"
3138 :     "$ pkg-config --modversion QtCore\n"
3139 :     "4.7.1\n"
3140 :     "$ pkg-config --cflags QtCore\n"
3141 :     "-DQT_SHARED -I/usr/include/QtCore\n"
3142 :     "$ pkg-config --libs QtCore\n"
3143 :     "-lQtCore\n"
3144 :     msgstr ""
3145 : gnustats 1804
3146 : gnustats 1578 #
3147 : gnustats 1336 #. type: Plain text
3148 : gnustats 2642 #: R-exts.texi:1714
3149 : gnustats 1804 msgid ""
3150 :     "Note that @command{pkg-config --libs} gives the information required to link "
3151 :     "against the default version of that library (usually the dynamic one), and "
3152 :     "@command{pkg-config --static} is needed if the static library is to be used."
3153 : gnustats 1336 msgstr ""
3154 : gnustats 1804
3155 : gnustats 1578 #
3156 : gnustats 1336 #. type: Plain text
3157 : gnustats 2642 #: R-exts.texi:1718
3158 : gnustats 1804 msgid ""
3159 :     "Sometimes the name by which the software is known to @command{pkg-config} is "
3160 :     "not what one might expect (e.g.@: @samp{gtk+-2.0} even for 2.22). To get a "
3161 :     "complete list use"
3162 : gnustats 1336 msgstr ""
3163 : gnustats 1804
3164 : gnustats 1578 #
3165 : gnustats 1336 #. type: example
3166 : gnustats 2642 #: R-exts.texi:1721
3167 : gnustats 1336 #, no-wrap
3168 :     msgid "pkg-config --list-all | sort\n"
3169 :     msgstr ""
3170 : gnustats 1804
3171 : gnustats 1578 #
3172 : gnustats 1336 #. type: node
3173 : gnustats 2642 #: R-exts.texi:1728
3174 :     #: R-exts.texi:1730
3175 :     #: R-exts.texi:1993
3176 :     #: R-exts.texi:2094
3177 :     #: R-exts.texi:2146
3178 :     #: R-exts.texi:2204
3179 : gnustats 1336 #, no-wrap
3180 :     msgid "Using Makevars"
3181 :     msgstr ""
3182 : gnustats 1804
3183 : gnustats 1578 #
3184 : gnustats 1336 #. type: node
3185 : gnustats 2642 #: R-exts.texi:1728
3186 :     #: R-exts.texi:1730
3187 :     #: R-exts.texi:2204
3188 :     #: R-exts.texi:2205
3189 :     #: R-exts.texi:2339
3190 : gnustats 1336 #, no-wrap
3191 :     msgid "Configure example"
3192 :     msgstr ""
3193 : gnustats 1804
3194 : gnustats 1578 #
3195 : gnustats 1336 #. type: node
3196 : gnustats 2642 #: R-exts.texi:1728
3197 :     #: R-exts.texi:2204
3198 :     #: R-exts.texi:2339
3199 :     #: R-exts.texi:2340
3200 :     #: R-exts.texi:2392
3201 : gnustats 1336 #, no-wrap
3202 :     msgid "Using F95 code"
3203 :     msgstr ""
3204 : gnustats 1804
3205 : gnustats 1578 #
3206 : gnustats 1336 #. type: subsection
3207 : gnustats 2642 #: R-exts.texi:1728
3208 :     #: R-exts.texi:2339
3209 :     #: R-exts.texi:2392
3210 :     #: R-exts.texi:2393
3211 : gnustats 1336 #, no-wrap
3212 :     msgid "Using C++11 code"
3213 :     msgstr ""
3214 : gnustats 1804
3215 : gnustats 1578 #
3216 : gnustats 1336 #. type: subsection
3217 : gnustats 2642 #: R-exts.texi:1731
3218 : gnustats 1336 #, no-wrap
3219 :     msgid "Using @file{Makevars}"
3220 :     msgstr ""
3221 : gnustats 1804
3222 : gnustats 1578 #
3223 : gnustats 1336 #. type: node
3224 : gnustats 2642 #: R-exts.texi:1737
3225 :     #: R-exts.texi:1993
3226 :     #: R-exts.texi:1994
3227 :     #: R-exts.texi:2094
3228 : gnustats 1336 #, no-wrap
3229 :     msgid "OpenMP support"
3230 :     msgstr ""
3231 : gnustats 1804
3232 : gnustats 1578 #
3233 : gnustats 1336 #. type: node
3234 : gnustats 2642 #: R-exts.texi:1737
3235 :     #: R-exts.texi:1993
3236 :     #: R-exts.texi:2094
3237 :     #: R-exts.texi:2095
3238 :     #: R-exts.texi:2146
3239 : gnustats 1336 #, no-wrap
3240 :     msgid "Using pthreads"
3241 :     msgstr ""
3242 : gnustats 1804
3243 : gnustats 1578 #
3244 : gnustats 1336 #. type: subsubsection
3245 : gnustats 2642 #: R-exts.texi:1737
3246 :     #: R-exts.texi:2094
3247 :     #: R-exts.texi:2146
3248 :     #: R-exts.texi:2147
3249 : gnustats 1336 #, no-wrap
3250 :     msgid "Compiling in sub-directories"
3251 :     msgstr ""
3252 : gnustats 1804
3253 : gnustats 1578 #
3254 : gnustats 1336 #. type: Plain text
3255 : gnustats 2642 #: R-exts.texi:1743
3256 : gnustats 1804 msgid ""
3257 :     "Sometimes writing your own @file{configure} script can be avoided by "
3258 :     "supplying a file @file{Makevars}: also one of the most common uses of a "
3259 :     "@file{configure} script is to make @file{Makevars} from @file{Makevars.in}."
3260 : gnustats 1336 msgstr ""
3261 : gnustats 1804
3262 : gnustats 1578 #
3263 : gnustats 1336 #. type: Plain text
3264 : gnustats 2642 #: R-exts.texi:1749
3265 : gnustats 1804 msgid ""
3266 :     "A @file{Makevars} file is a makefile and is used as one of several makefiles "
3267 :     "by @command{R CMD SHLIB} (which is called by @command{R CMD INSTALL} to "
3268 :     "compile code in the @file{src} directory). It should be written if at all "
3269 :     "possible in a portable style, in particular (except for @file{Makevars.win}) "
3270 :     "without the use of GNU extensions."
3271 : gnustats 1336 msgstr ""
3272 : gnustats 1804
3273 : gnustats 1578 #
3274 : gnustats 1336 #. type: Plain text
3275 : gnustats 2642 #: R-exts.texi:1756
3276 : gnustats 1804 msgid ""
3277 :     "The most common use of a @file{Makevars} file is to set additional "
3278 :     "preprocessor options (for example include paths) for C/C++ files @emph{via} "
3279 :     "@code{PKG_CPPFLAGS}, and additional compiler flags by setting "
3280 :     "@code{PKG_CFLAGS}, @code{PKG_CXXFLAGS}, @code{PKG_FFLAGS} or "
3281 :     "@code{PKG_FCFLAGS}, for C, C++, FORTRAN or Fortran 9x respectively "
3282 :     "(@pxref{Creating shared objects})."
3283 : gnustats 1336 msgstr ""
3284 : gnustats 1804
3285 : gnustats 1578 #
3286 : gnustats 1336 #. type: Plain text
3287 : gnustats 2642 #: R-exts.texi:1761
3288 : gnustats 1804 msgid ""
3289 :     "@strong{N.B.}: Include paths are preprocessor options, not compiler options, "
3290 :     "and @strong{must} be set in @code{PKG_CPPFLAGS} as otherwise platform-"
3291 :     "specific paths (e.g.@: @samp{-I/usr/local/include}) will take precedence."
3292 : gnustats 1336 msgstr ""
3293 : gnustats 1804
3294 : gnustats 1578 #
3295 : gnustats 1336 #. type: Plain text
3296 : gnustats 2642 #: R-exts.texi:1764
3297 : gnustats 1804 msgid ""
3298 :     "@file{Makevars} can also be used to set flags for the linker, for example "
3299 :     "@samp{-L} and @samp{-l} options, @emph{via} @code{PKG_LIBS}."
3300 : gnustats 1336 msgstr ""
3301 : gnustats 1804
3302 : gnustats 1578 #
3303 : gnustats 1336 #. type: Plain text
3304 : gnustats 2642 #: R-exts.texi:1770
3305 : gnustats 1804 msgid ""
3306 :     "When writing a @file{Makevars} file for a package you intend to distribute, "
3307 :     "take care to ensure that it is not specific to your compiler: flags such as "
3308 :     "@option{-O2 -Wall -pedantic} (and all other @option{-W} flags: for the "
3309 :     "Solaris compiler these are used to pass arguments to compiler phases) are "
3310 :     "all specific to GCC."
3311 : gnustats 1336 msgstr ""
3312 : gnustats 1804
3313 : gnustats 1578 #
3314 : gnustats 1336 #. type: Plain text
3315 : gnustats 2642 #: R-exts.texi:1774
3316 : gnustats 1804 msgid ""
3317 :     "Also, do not set variables such as @code{CPPFLAGS}, @code{CFLAGS} etc.: "
3318 :     "these should be settable by users (sites) through appropriate personal (site-"
3319 :     "wide) @file{Makevars} files."
3320 : gnustats 1336 msgstr ""
3321 : gnustats 1804
3322 : gnustats 1578 #
3323 : gnustats 1336 #. type: ifset
3324 : gnustats 2642 #: R-exts.texi:1777
3325 :     #: R-exts.texi:4054
3326 :     #: R-exts.texi:9048
3327 : gnustats 1804 msgid ""
3328 :     "@xref{Customizing package compilation, , Customizing package compilation, R-"
3329 :     "admin, R Installation and Administration},"
3330 : gnustats 1336 msgstr ""
3331 : gnustats 1804
3332 : gnustats 1578 #
3333 : gnustats 1336 #. type: Plain text
3334 : gnustats 2642 #: R-exts.texi:1786
3335 : gnustats 1804 msgid ""
3336 :     "There are some macros@footnote{in POSIX parlance: GNU @command{make} calls "
3337 :     "these `make variables'.} which are set whilst configuring the building of "
3338 :     "@R{} itself and are stored in @file{@var{R_HOME}/etc@var{R_ARCH}/Makeconf}. "
3339 :     "That makefile is included as a @file{Makefile} @emph{after} @file{Makevars[."
3340 :     "win]}, and the macros it defines can be used in macro assignments and make "
3341 :     "command lines in the latter. These include"
3342 : gnustats 1336 msgstr ""
3343 : gnustats 1804
3344 : gnustats 1578 #
3345 : gnustats 1336 #. type: vindex
3346 : gnustats 2642 #: R-exts.texi:1788
3347 :     #: R-exts.texi:1789
3348 : gnustats 1336 #, no-wrap
3349 :     msgid "FLIBS"
3350 :     msgstr ""
3351 : gnustats 1804
3352 : gnustats 1578 #
3353 : gnustats 1336 #. type: table
3354 : gnustats 2642 #: R-exts.texi:1793
3355 : gnustats 1804 msgid ""
3356 :     "A macro containing the set of libraries need to link FORTRAN code. This may "
3357 :     "need to be included in @code{PKG_LIBS}: it will normally be included "
3358 :     "automatically if the package contains FORTRAN source files."
3359 : gnustats 1336 msgstr ""
3360 : gnustats 1804
3361 : gnustats 1578 #
3362 : gnustats 1336 #. type: vindex
3363 : gnustats 2642 #: R-exts.texi:1794
3364 :     #: R-exts.texi:1795
3365 : gnustats 1336 #, no-wrap
3366 :     msgid "BLAS_LIBS"
3367 :     msgstr ""
3368 : gnustats 1804
3369 : gnustats 1578 #
3370 : gnustats 1336 #. type: table
3371 : gnustats 2642 #: R-exts.texi:1805
3372 : gnustats 1804 msgid ""
3373 :     "A macro containing the BLAS libraries used when building @R{}. This may "
3374 :     "need to be included in @code{PKG_LIBS}. Beware that if it is empty then the "
3375 :     "@R{} executable will contain all the double-precision and double-complex "
3376 :     "BLAS routines, but no single-precision nor complex routines. If "
3377 :     "@code{BLAS_LIBS} is included, then @code{FLIBS} also needs to be@footnote{at "
3378 :     "least on Unix-alikes: the Windows build currently resolves such dependencies "
3379 :     "to a static FORTRAN library when @file{Rblas.dll} is built.} included "
3380 :     "following it, as most BLAS libraries are written at least partially in "
3381 :     "FORTRAN."
3382 : gnustats 1336 msgstr ""
3383 : gnustats 1804
3384 : gnustats 1578 #
3385 : gnustats 1336 #. type: vindex
3386 : gnustats 2642 #: R-exts.texi:1806
3387 :     #: R-exts.texi:1807
3388 : gnustats 1336 #, no-wrap
3389 :     msgid "LAPACK_LIBS"
3390 :     msgstr ""
3391 : gnustats 1804
3392 : gnustats 1578 #
3393 : gnustats 1336 #. type: table
3394 : gnustats 2642 #: R-exts.texi:1815
3395 : gnustats 1804 msgid ""
3396 :     "A macro containing the LAPACK libraries (and paths where appropriate) used "
3397 :     "when building @R{}. This may need to be included in @code{PKG_LIBS}. It "
3398 :     "may point to a dynamic library @code{libRlapack} which contains the main "
3399 :     "double-precision LAPACK routines as well as those double-complex LAPACK "
3400 :     "routines needed to build @R{}, or it may point to an external LAPACK "
3401 :     "library, or may be empty if an external BLAS library also contains LAPACK."
3402 : gnustats 1336 msgstr ""
3403 : gnustats 1804
3404 : gnustats 1578 #
3405 : gnustats 1336 #. type: table
3406 : gnustats 2642 #: R-exts.texi:1819
3407 : gnustats 1804 msgid ""
3408 :     "[@code{libRlapack} includes all the double-precision LAPACK routines current "
3409 :     "in 2003: a list of which routines are included is in file @file{src/modules/"
3410 :     "lapack/README}.]"
3411 : gnustats 1336 msgstr ""
3412 : gnustats 1804
3413 : gnustats 1578 #
3414 : gnustats 1336 #. type: table
3415 : gnustats 2642 #: R-exts.texi:1822
3416 : gnustats 1804 msgid ""
3417 :     "For portability, the macros @code{BLAS_LIBS} and @code{FLIBS} should always "
3418 :     "be included @emph{after} @code{LAPACK_LIBS} (and in that order)."
3419 : gnustats 1336 msgstr ""
3420 : gnustats 1804
3421 : gnustats 1578 #
3422 : gnustats 1336 #. type: vindex
3423 : gnustats 2642 #: R-exts.texi:1823
3424 :     #: R-exts.texi:1824
3425 : gnustats 1336 #, no-wrap
3426 :     msgid "SAFE_FFLAGS"
3427 :     msgstr ""
3428 : gnustats 1804
3429 : gnustats 1578 #
3430 : gnustats 1336 #. type: table
3431 : gnustats 2642 #: R-exts.texi:1833
3432 : gnustats 1804 msgid ""
3433 :     "A macro containing flags which are needed to circumvent over-optimization of "
3434 :     "FORTRAN code: it is typically @samp{-g -O2 -ffloat-store} on @cputype{ix86} "
3435 :     "platforms using @command{gfortran}. Note that this is @strong{not} an "
3436 :     "additional flag to be used as part of @code{PKG_FFLAGS}, but a replacement "
3437 :     "for @code{FFLAGS}, and that it is intended for the FORTRAN 77 compiler "
3438 :     "@samp{F77} and not necessarily for the Fortran 90/95 compiler @samp{FC}. "
3439 :     "See the example later in this section."
3440 : gnustats 1336 msgstr ""
3441 : gnustats 1804
3442 : gnustats 1578 #
3443 : gnustats 1336 #. type: vindex
3444 : gnustats 2642 #: R-exts.texi:1835
3445 :     #: R-exts.texi:9028
3446 : gnustats 1336 #, no-wrap
3447 :     msgid "OBJECTS"
3448 :     msgstr ""
3449 : gnustats 1804
3450 : gnustats 1578 #
3451 : gnustats 1336 #. type: Plain text
3452 : gnustats 2642 #: R-exts.texi:1844
3453 : gnustats 1804 msgid ""
3454 :     "Setting certain macros in @file{Makevars} will prevent @command{R CMD SHLIB} "
3455 :     "setting them: in particular if @file{Makevars} sets @samp{OBJECTS} it will "
3456 :     "not be set on the @command{make} command line. This can be useful in "
3457 :     "conjunction with implicit rules to allow other types of source code to be "
3458 :     "compiled and included in the shared object. It can also be used to control "
3459 :     "the set of files which are compiled, either by excluding some files in "
3460 :     "@file{src} or including some files in subdirectories. For example"
3461 : gnustats 1336 msgstr ""
3462 : gnustats 1804
3463 : gnustats 1578 #
3464 : gnustats 1336 #. type: example
3465 : gnustats 2642 #: R-exts.texi:1847
3466 : gnustats 1336 #, no-wrap
3467 :     msgid "OBJECTS = 4dfp/endianio.o 4dfp/Getifh.o R4dfp-object.o\n"
3468 :     msgstr ""
3469 : gnustats 1804
3470 : gnustats 1578 #
3471 : gnustats 1336 #. type: Plain text
3472 : gnustats 2642 #: R-exts.texi:1856
3473 : gnustats 1804 msgid ""
3474 :     "Note that @file{Makevars} should not normally contain targets, as it is "
3475 :     "included before the default makefile and @command{make} will call the first "
3476 :     "target, intended to be @code{all} in the default makefile. If you really "
3477 :     "need to circumvent that, use a suitable (phony) target @code{all} before any "
3478 :     "actual targets in @file{Makevars.[win]}: for example package "
3479 :     "@CRANpkg{fastICA} used to have"
3480 : gnustats 1336 msgstr ""
3481 : gnustats 1804
3482 : gnustats 1578 #
3483 : gnustats 1336 #. type: example
3484 : gnustats 2642 #: R-exts.texi:1859
3485 : gnustats 1336 #, no-wrap
3486 :     msgid ""
3487 :     "PKG_LIBS = @@BLAS_LIBS@@\n"
3488 :     "\n"
3489 :     msgstr ""
3490 : gnustats 1804
3491 : gnustats 1578 #
3492 : gnustats 1336 #. type: example
3493 : gnustats 2642 #: R-exts.texi:1861
3494 : gnustats 1336 #, no-wrap
3495 :     msgid ""
3496 :     "SLAMC_FFLAGS=$(R_XTRA_FFLAGS) $(FPICFLAGS) $(SHLIB_FFLAGS) $(SAFE_FFLAGS)\n"
3497 :     "\n"
3498 :     msgstr ""
3499 : gnustats 1804
3500 : gnustats 1578 #
3501 : gnustats 1336 #. type: example
3502 : gnustats 2642 #: R-exts.texi:1863
3503 :     #: R-exts.texi:1874
3504 : gnustats 1336 #, no-wrap
3505 :     msgid ""
3506 :     "all: $(SHLIB)\n"
3507 :     "\n"
3508 :     msgstr ""
3509 : gnustats 1804
3510 : gnustats 1578 #
3511 : gnustats 1336 #. type: example
3512 : gnustats 2642 #: R-exts.texi:1866
3513 : gnustats 1336 #, no-wrap
3514 :     msgid ""
3515 :     "slamc.o: slamc.f\n"
3516 :     "\t$(F77) $(SLAMC_FFLAGS) -c -o slamc.o slamc.f\n"
3517 :     msgstr ""
3518 : gnustats 1804
3519 : gnustats 1578 #
3520 : gnustats 1336 #. type: Plain text
3521 : gnustats 2642 #: R-exts.texi:1871
3522 : gnustats 1804 msgid ""
3523 :     "needed to ensure that the LAPACK routines find some constants without "
3524 :     "infinite looping. The Windows equivalent was"
3525 : gnustats 1336 msgstr ""
3526 : gnustats 1804
3527 : gnustats 1578 #
3528 : gnustats 1336 #. type: example
3529 : gnustats 2642 #: R-exts.texi:1877
3530 : gnustats 1336 #, no-wrap
3531 :     msgid ""
3532 :     "slamc.o: slamc.f\n"
3533 :     "\t$(F77) $(SAFE_FFLAGS) -c -o slamc.o slamc.f\n"
3534 :     msgstr ""
3535 : gnustats 1804
3536 : gnustats 1578 #
3537 : gnustats 1336 #. type: Plain text
3538 : gnustats 2642 #: R-exts.texi:1884
3539 : gnustats 1804 msgid ""
3540 :     "(since the other macros are all empty on that platform, and @R{}'s internal "
3541 :     "BLAS was not used). Note that the first target in @file{Makevars} will be "
3542 :     "called, but for back-compatibility it is best named @code{all}."
3543 : gnustats 1336 msgstr ""
3544 : gnustats 1804
3545 : gnustats 1578 #
3546 : gnustats 1336 #. type: Plain text
3547 : gnustats 2642 #: R-exts.texi:1887
3548 : gnustats 1804 msgid ""
3549 :     "If you want to create and then link to a library, say using code in a "
3550 :     "subdirectory, use something like"
3551 : gnustats 1336 msgstr ""
3552 : gnustats 1804
3553 : gnustats 1578 #
3554 : gnustats 1336 #. type: example
3555 : gnustats 2642 #: R-exts.texi:1890
3556 : gnustats 1336 #, no-wrap
3557 :     msgid ""
3558 :     ".PHONY: all mylibs\n"
3559 :     "\n"
3560 :     msgstr ""
3561 : gnustats 1804
3562 : gnustats 1578 #
3563 : gnustats 1336 #. type: example
3564 : gnustats 2642 #: R-exts.texi:1893
3565 : gnustats 1336 #, no-wrap
3566 :     msgid ""
3567 :     "all: $(SHLIB)\n"
3568 :     "$(SHLIB): mylibs\n"
3569 :     "\n"
3570 :     msgstr ""
3571 : gnustats 1804
3572 : gnustats 1578 #
3573 : gnustats 1336 #. type: example
3574 : gnustats 2642 #: R-exts.texi:1896
3575 : gnustats 1336 #, no-wrap
3576 :     msgid ""
3577 :     "mylibs:\n"
3578 :     "\t(cd subdir; make)\n"
3579 :     msgstr ""
3580 : gnustats 1804
3581 : gnustats 1578 #
3582 : gnustats 1336 #. type: Plain text
3583 : gnustats 2642 #: R-exts.texi:1903
3584 : gnustats 1804 msgid ""
3585 :     "Be careful to create all the necessary dependencies, as there is a no "
3586 :     "guarantee that the dependencies of @code{all} will be run in a particular "
3587 :     "order (and some of the @acronym{CRAN} build machines use multiple CPUs and "
3588 :     "parallel makes)."
3589 : gnustats 1336 msgstr ""
3590 : gnustats 1804
3591 : gnustats 1578 #
3592 : gnustats 1336 #. type: Plain text
3593 : gnustats 2642 #: R-exts.texi:1909
3594 : gnustats 1804 msgid ""
3595 :     "Note that on Windows it is required that @file{Makevars[.win]} does create a "
3596 :     "DLL: this is needed as it is the only reliable way to ensure that building a "
3597 :     "DLL succeeded. If you want to use the @file{src} directory for some purpose "
3598 :     "other than building a DLL, use a @file{Makefile.win} file."
3599 : gnustats 1336 msgstr ""
3600 : gnustats 1804
3601 : gnustats 1578 #
3602 : gnustats 1336 #. type: Plain text
3603 : gnustats 2642 #: R-exts.texi:1918
3604 : gnustats 1804 msgid ""
3605 :     "It is sometimes useful to have a target @samp{clean} in @file{Makevars} or "
3606 :     "@file{Makevars.win}: this will be used by @command{R CMD build} to clean up "
3607 :     "(a copy of) the package sources. When it is run by @command{build} it will "
3608 :     "have fewer macros set, in particular not @code{$(SHLIB)}, nor "
3609 :     "@code{$(OBJECTS)} unless set in the file itself. It would also be possible "
3610 :     "to add tasks to the target @samp{shlib-clean} which is run by @command{R CMD "
3611 :     "INSTALL} and @command{R CMD SHLIB} with options @option{--clean} and "
3612 :     "@option{--preclean}."
3613 : gnustats 1336 msgstr ""
3614 : gnustats 1804
3615 : gnustats 1578 #
3616 : gnustats 1336 #. type: Plain text
3617 : gnustats 2642 #: R-exts.texi:1924
3618 : gnustats 1804 msgid ""
3619 :     "If you want to run @R{} code in @file{Makevars}, e.g.@: to find "
3620 :     "configuration information, please do ensure that you use the correct copy of "
3621 :     "@code{R} or @code{Rscript}: there might not be one in the path at all, or it "
3622 :     "might be the wrong version or architecture. The correct way to do this is "
3623 :     "@emph{via}"
3624 : gnustats 1336 msgstr ""
3625 : gnustats 1804
3626 : gnustats 1578 #
3627 : gnustats 1336 #. type: example
3628 : gnustats 2642 #: R-exts.texi:1928
3629 : gnustats 1336 #, no-wrap
3630 :     msgid ""
3631 :     "\"$(R_HOME)/bin$(R_ARCH_BIN)/Rscript\" @var{filename}\n"
3632 :     "\"$(R_HOME)/bin$(R_ARCH_BIN)/Rscript\" -e '@var{R expression}'\n"
3633 :     msgstr ""
3634 : gnustats 1804
3635 : gnustats 1578 #
3636 : gnustats 1336 #. type: Plain text
3637 : gnustats 2642 #: R-exts.texi:1932
3638 : gnustats 1336 msgid "where @code{$(R_ARCH_BIN)} is only needed currently on Windows."
3639 :     msgstr ""
3640 : gnustats 1804
3641 : gnustats 1578 #
3642 : gnustats 1336 #. type: Plain text
3643 : gnustats 2642 #: R-exts.texi:1936
3644 : gnustats 1804 msgid ""
3645 :     "Environment or make variables can be used to select different macros for 32- "
3646 :     "and 64-bit code, for example (GNU @command{make} syntax, allowed on Windows)"
3647 : gnustats 1336 msgstr ""
3648 : gnustats 1804
3649 : gnustats 1578 #
3650 : gnustats 1336 #. type: example
3651 : gnustats 2642 #: R-exts.texi:1943
3652 : gnustats 1336 #, no-wrap
3653 :     msgid ""
3654 :     "ifeq \"$(WIN)\" \"64\"\n"
3655 :     "PKG_LIBS = @var{value for 64-bit Windows}\n"
3656 :     "else\n"
3657 :     "PKG_LIBS = @var{value for 32-bit Windows}\n"
3658 :     "endif\n"
3659 :     msgstr ""
3660 : gnustats 1804
3661 : gnustats 1578 #
3662 : gnustats 1336 #. type: Plain text
3663 : gnustats 2642 #: R-exts.texi:1950
3664 : gnustats 1804 msgid ""
3665 :     "On Windows there is normally a choice between linking to an import library "
3666 :     "or directly to a DLL. Where possible, the latter is much more reliable: "
3667 :     "import libraries are tied to a specific toolchain, and in particular on 64-"
3668 :     "bit Windows two different conventions have been commonly used. So for "
3669 :     "example instead of"
3670 : gnustats 1336 msgstr ""
3671 : gnustats 1804
3672 : gnustats 1578 #
3673 : gnustats 1336 #. type: example
3674 : gnustats 2642 #: R-exts.texi:1953
3675 : gnustats 1336 #, no-wrap
3676 :     msgid "PKG_LIBS = -L$(XML_DIR)/lib -lxml2\n"
3677 :     msgstr ""
3678 : gnustats 1804
3679 : gnustats 1578 #
3680 : gnustats 1336 #. type: Plain text
3681 : gnustats 2642 #: R-exts.texi:1957
3682 : gnustats 1336 msgid "one can use"
3683 :     msgstr ""
3684 : gnustats 1804
3685 : gnustats 1578 #
3686 : gnustats 1336 #. type: example
3687 : gnustats 2642 #: R-exts.texi:1960
3688 : gnustats 1336 #, no-wrap
3689 :     msgid "PKG_LIBS = -L$(XML_DIR)/bin -lxml2\n"
3690 :     msgstr ""
3691 : gnustats 1804
3692 : gnustats 1578 #
3693 : gnustats 1336 #. type: Plain text
3694 : gnustats 2642 #: R-exts.texi:1964
3695 : gnustats 1336 msgid "since on Windows @code{-lxxx} will look in turn for"
3696 :     msgstr ""
3697 : gnustats 1804
3698 : gnustats 1578 #
3699 : gnustats 1336 #. type: example
3700 : gnustats 2642 #: R-exts.texi:1972
3701 : gnustats 1336 #, no-wrap
3702 :     msgid ""
3703 :     "libxxx.dll.a\n"
3704 :     "xxx.dll.a\n"
3705 :     "libxxx.a\n"
3706 :     "xxx.lib\n"
3707 :     "libxxx.dll\n"
3708 :     "xxx.dll\n"
3709 :     msgstr ""
3710 : gnustats 1804
3711 : gnustats 1336 #. type: Plain text
3712 : gnustats 2642 #: R-exts.texi:1979
3713 : gnustats 1804 msgid ""
3714 :     "where the first and second are conventionally import libraries, the third "
3715 :     "and fourth often static libraries (with @code{.lib} intended for Visual C+"
3716 : gnustats 2640 "+), but might be import libraries. See for example @uref{https://sourceware."
3717 : gnustats 1804 "org/@/binutils/@/docs-2.20/@/ld/@/WIN32.html#WIN32}."
3718 : gnustats 1336 msgstr ""
3719 : gnustats 1804
3720 : gnustats 1578 #
3721 : gnustats 1336 #. type: Plain text
3722 : gnustats 2642 #: R-exts.texi:1985
3723 : gnustats 1804 msgid ""
3724 :     "The fly in the ointment is that the DLL might not be named @file{libxxx."
3725 :     "dll}, and in fact on 32-bit Windows there is a @file{libxml2.dll} whereas on "
3726 :     "one build for 64-bit Windows the DLL is called @file{libxml2-2.dll}. Using "
3727 :     "import libraries can cover over these differences but can cause equal "
3728 :     "difficulties."
3729 : gnustats 1336 msgstr ""
3730 : gnustats 1804
3731 : gnustats 1578 #
3732 : gnustats 1336 #. type: Plain text
3733 : gnustats 2642 #: R-exts.texi:1992
3734 : gnustats 1804 msgid ""
3735 :     "If static libraries are available they can save a lot of problems with run-"
3736 :     "time finding of DLLs, especially when binary packages are to be distributed "
3737 :     "and even more when these support both architectures. Where using DLLs is "
3738 :     "unavoidable we normally arrange (@emph{via} @file{configure.win}) to ship "
3739 :     "them in the same directory as the package DLL."
3740 : gnustats 1336 msgstr ""
3741 : gnustats 1804
3742 : gnustats 1578 #
3743 : gnustats 1336 #. type: cindex
3744 : gnustats 2642 #: R-exts.texi:1996
3745 :     #: R-exts.texi:12614
3746 : gnustats 1336 #, no-wrap
3747 :     msgid "OpenMP"
3748 :     msgstr ""
3749 : gnustats 1804
3750 : gnustats 1336 #. type: Plain text
3751 : gnustats 2642 #: R-exts.texi:2003
3752 : gnustats 1804 msgid ""
3753 :     "There is some support for packages which wish to use "
3754 : gnustats 2640 "OpenMP@footnote{@uref{http://www.openmp.org/}, @uref{https://en.wikipedia."
3755 :     "org/@/wiki/@/OpenMP}, @uref{https://computing.llnl.gov/@/tutorials/@/"
3756 :     "openMP/}}. The @command{make} macros"
3757 : gnustats 1336 msgstr ""
3758 : gnustats 1804
3759 : gnustats 1336 #. type: example
3760 : gnustats 2642 #: R-exts.texi:2009
3761 : gnustats 1336 #, no-wrap
3762 :     msgid ""
3763 :     "SHLIB_OPENMP_CFLAGS\n"
3764 :     "SHLIB_OPENMP_CXXFLAGS\n"
3765 : gnustats 2642 "SHLIB_OPENMP_FCFLAGS\n"
3766 : gnustats 1336 "SHLIB_OPENMP_FFLAGS\n"
3767 :     msgstr ""
3768 : gnustats 1804
3769 : gnustats 1336 #. type: Plain text
3770 : gnustats 2642 #: R-exts.texi:2020
3771 : gnustats 1804 msgid ""
3772 :     "are available for use in @file{src/Makevars} or @file{src/Makevars.win}. "
3773 :     "Include the appropriate macro in @code{PKG_CFLAGS}, @code{PKG_CPPFLAGS} and "
3774 :     "so on, and also in @code{PKG_LIBS}. C/C++ code that needs to be conditioned "
3775 : gnustats 2642 "on the use of OpenMP can be used inside @code{#ifdef _OPENMP}: note that "
3776 :     "some toolchains used for @R{} (including most of those using @command{clang}"
3777 :     "@footnote{Some builds of @command{clang} 3.7 have support for OpenMP 3.1}) "
3778 :     "have no OpenMP support at all, not even @file{omp.h}."
3779 : gnustats 1336 msgstr ""
3780 : gnustats 1804
3781 : gnustats 1578 #
3782 : gnustats 1336 #. type: Plain text
3783 : gnustats 2642 #: R-exts.texi:2023
3784 : gnustats 1804 msgid ""
3785 :     "For example, a package with C code written for OpenMP should have in "
3786 :     "@file{src/Makevars} the lines"
3787 : gnustats 1336 msgstr ""
3788 : gnustats 1804
3789 : gnustats 1578 #
3790 : gnustats 1336 #. type: example
3791 : gnustats 2642 #: R-exts.texi:2027
3792 : gnustats 1336 #, no-wrap
3793 :     msgid ""
3794 :     "PKG_CFLAGS = $(SHLIB_OPENMP_CFLAGS)\n"
3795 :     "PKG_LIBS = $(SHLIB_OPENMP_CFLAGS)\n"
3796 :     msgstr ""
3797 : gnustats 1804
3798 : gnustats 1578 #
3799 : gnustats 1336 #. type: Plain text
3800 : gnustats 2642 #: R-exts.texi:2032
3801 : gnustats 1804 msgid ""
3802 :     "Note that the macro @code{SHLIB_OPENMP_CXXFLAGS} applies to the C++98 "
3803 :     "compiler and not necessarily to the C++11 compiler: users of the latter "
3804 :     "should do their own @command{configure} checks."
3805 : gnustats 1336 msgstr ""
3806 : gnustats 1804
3807 : gnustats 1336 #. type: Plain text
3808 : gnustats 2642 #: R-exts.texi:2038
3809 : gnustats 1804 msgid ""
3810 : gnustats 2642 "Some care is needed when compilers are from different families which may use "
3811 :     "different OpenMP runtimes (e.g.@: @command{clang} @emph{vs} GCC including "
3812 :     "@command{gfortran}, although it is currently possible to use the "
3813 :     "@command{clang} runtime with GCC but not @emph{vice versa}). For a package "
3814 :     "with Fortran 77 code using OpenMP the appropriate lines are"
3815 :     msgstr ""
3816 :    
3817 :     #. type: example
3818 :     #: R-exts.texi:2042
3819 :     #, no-wrap
3820 :     msgid ""
3821 :     "PKG_FFLAGS = $(SHLIB_OPENMP_FFLAGS)\n"
3822 :     "PKG_LIBS = $(SHLIB_OPENMP_CFLAGS)\n"
3823 :     msgstr ""
3824 :    
3825 :     #. type: Plain text
3826 :     #: R-exts.texi:2047
3827 :     msgid ""
3828 :     "as the C compiler will be used to link the package code (and there is no "
3829 :     "guarantee that this will work everywhere)."
3830 :     msgstr ""
3831 :    
3832 :     #. type: Plain text
3833 :     #: R-exts.texi:2054
3834 :     msgid ""
3835 : gnustats 1804 "There is nothing to say what version of OpenMP is supported: version 3.0 "
3836 :     "(May 2008) is supported by recent versions of the Linux, Windows and Solaris "
3837 :     "platforms, but portable packages cannot assume that end users have recent "
3838 : gnustats 2642 "versions. OS X currently uses Apple builds of @command{clang} with no "
3839 :     "OpenMP support."
3840 : gnustats 1336 msgstr ""
3841 : gnustats 1804
3842 : gnustats 1336 #. type: Plain text
3843 : gnustats 2642 #: R-exts.texi:2064
3844 : gnustats 1804 msgid ""
3845 :     "The performance of OpenMP varies substantially between platforms. Both the "
3846 : gnustats 2180 "Windows and earlier Apple OS X implementations have substantial overheads "
3847 :     "and are only beneficial if quite substantial tasks are run in parallel. "
3848 : gnustats 2642 "Also, on Windows new threads are started with the default@footnote{Windows "
3849 :     "default, not MinGW-w64 default.} FPU control word, so computations done on "
3850 :     "OpenMP threads will not make use of extended-precision arithmetic which is "
3851 :     "the default for the main process."
3852 : gnustats 1336 msgstr ""
3853 : gnustats 1804
3854 : gnustats 1578 #
3855 : gnustats 1336 #. type: Plain text
3856 : gnustats 2642 #: R-exts.texi:2069
3857 : gnustats 1804 msgid ""
3858 :     "Calling any of the @R{} API from threaded code is `for experts only': they "
3859 :     "will need to read the source code to determine if it is thread-safe. In "
3860 :     "particular, code which makes use of the stack-checking mechanism must not be "
3861 :     "called from threaded code."
3862 : gnustats 1336 msgstr ""
3863 : gnustats 1804
3864 : gnustats 1336 #. type: Plain text
3865 : gnustats 2642 #: R-exts.texi:2088
3866 : gnustats 1804 msgid ""
3867 :     "Packages are not standard-alone programs, and an @R{} process could contain "
3868 :     "more than one OpenMP-enabled package as well as other components (for "
3869 :     "example, an optimized BLAS) making use of OpenMP. So careful consideration "
3870 :     "needs to be given to resource usage. OpenMP works with parallel regions, "
3871 :     "and for most implementations the default is to use as many threads as `CPUs' "
3872 :     "for such regions. Parallel regions can be nested, although it is common to "
3873 :     "use only a single thread below the first level. The correctness of the "
3874 :     "detected number of `CPUs' and the assumption that the @R{} process is "
3875 :     "entitled to use them all are both dubious assumptions. The best way to "
3876 :     "limit resources is to limit the overall number of threads available to "
3877 :     "OpenMP in the @R{} process: this can be done via environment variable "
3878 :     "@env{OMP_THREAD_LIMIT}, where implemented.@footnote{Which it was at the time "
3879 : gnustats 2642 "of writing with GCC, Solaris Studio, Intel and Clang 3.7.x compilers.} "
3880 :     "Alternatively, the number of threads per region can be limited by the "
3881 :     "environment variable @env{OMP_NUM_THREADS} or API call "
3882 :     "@code{omp_set_num_threads}, or, better, for the regions in your code as part "
3883 :     "of their specification. E.g.@: @R{} uses"
3884 : gnustats 1336 msgstr ""
3885 : gnustats 1804
3886 : gnustats 1578 #
3887 : gnustats 1336 #. type: example
3888 : gnustats 2642 #: R-exts.texi:2090
3889 : gnustats 1336 #, no-wrap
3890 :     msgid "#pragma omp parallel for num_threads(nthreads) @dots{}\n"
3891 :     msgstr ""
3892 : gnustats 1804
3893 : gnustats 1578 #
3894 : gnustats 1336 #. type: Plain text
3895 : gnustats 2642 #: R-exts.texi:2093
3896 : gnustats 1804 msgid ""
3897 :     "That way you only control your own code and not that of other OpenMP users."
3898 : gnustats 1336 msgstr ""
3899 : gnustats 1804
3900 : gnustats 1578 #
3901 : gnustats 1336 #. type: Plain text
3902 : gnustats 2642 #: R-exts.texi:2101
3903 : gnustats 1804 msgid ""
3904 :     "There is no direct support for the POSIX threads (more commonly known as "
3905 :     "@code{pthreads}): by the time we considered adding it several packages were "
3906 :     "using it unconditionally so it seems that nowadays it is universally "
3907 :     "available on POSIX operating systems (hence not Windows)."
3908 : gnustats 1336 msgstr ""
3909 : gnustats 1804
3910 : gnustats 1578 #
3911 : gnustats 1336 #. type: Plain text
3912 : gnustats 2642 #: R-exts.texi:2104
3913 : gnustats 1804 msgid ""
3914 :     "For reasonably recent versions of @command{gcc} and @command{clang} the "
3915 :     "correct specification is"
3916 : gnustats 1336 msgstr ""
3917 : gnustats 1804
3918 : gnustats 1578 #
3919 : gnustats 1336 #. type: example
3920 : gnustats 2642 #: R-exts.texi:2108
3921 : gnustats 1336 #, no-wrap
3922 :     msgid ""
3923 :     "PKG_CPPFLAGS = -pthread\n"
3924 :     "PKG_LIBS = -pthread\n"
3925 :     msgstr ""
3926 : gnustats 1804
3927 : gnustats 1578 #