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 1337 - (view) (download)

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