SCM Repository
| [ihelp] / src / manual / R-exts-ko.po |
View of /src/manual/R-exts-ko.po
Parent Directory
| 
Revision Log
Revision 2642 -
(download)
(annotate)
Tue Sep 29 23:39:30 2015 UTC (2 years ago) by gnustats
File size: 734497 byte(s)
Tue Sep 29 23:39:30 2015 UTC (2 years ago) by gnustats
File size: 734497 byte(s)
is teaked.
# Korean translation for translation.ko package # doc/manual/R-exts.texi # # Copyright (C) 2008-2015 Chel Hee Lee, and R Translation Teams # # This file is distributed under the same license as the R distribution. # Chel Hee Lee <chl948@mail.usask.ca>, 2008-2015. # # Note that every single contributor listed on the Acknowledgement # assigns his or her contribution to Chel Hee Lee. # # Note also that your name may not be found because of incomplete # record keeping. If you were overlooked, please let the maintainer # know and the list will be updated. Please also contact the mainter # of this document in order to voluntarily participate in # or offer your help with this work. # msgid "" msgstr "" "Project-Id-Version: translation.ko_0.0.1.4\n" "Report-Msgid-Bugs-To: chl948@mail.usask.ca\n" "POT-Creation-Date: 2015-09-29 17:38-0600\n" "PO-Revision-Date: 2015-09-29 17:38-0600\n" "Last-Translator: Chel Hee Lee <chl948@mail.usask.ca>\n" "Language-Team: Chel Hee Lee <chl948@mail.usask.ca>\n" "Language: ko\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=1; plural=0;\n" # #. type: top #: R-exts.texi:4 #: R-exts.texi:34 #: R-exts.texi:52 #, no-wrap msgid "Writing R Extensions" msgstr "" # #. type: dircategory #: R-exts.texi:13 #, no-wrap msgid "Programming" msgstr "" # #. type: menuentry #: R-exts.texi:16 msgid "R Extensions: (R-exts)" msgstr "" # #. type: menuentry #: R-exts.texi:16 msgid "Writing R Extensions." msgstr "" # #. type: include #: R-exts.texi:20 #, no-wrap msgid "R-defs.texi" msgstr "" # #. type: include #: R-exts.texi:21 #, no-wrap msgid "version.texi" msgstr "" # #. type: copying #: R-exts.texi:25 msgid "This manual is for R, version @value{VERSION}." msgstr "" # #. type: copying #: R-exts.texi:27 msgid "@Rcopyright{1999}" msgstr "" # #. type: quotation #: R-exts.texi:30 msgid "@permission{}" msgstr "" # #. type: subtitle #: R-exts.texi:35 #, no-wrap msgid "Version @value{VERSION}" msgstr "" # #. type: author #: R-exts.texi:36 #, no-wrap msgid "R Core Team" msgstr "" # #. type: node #: R-exts.texi:51 #: R-exts.texi:76 #: R-exts.texi:85 #: R-exts.texi:4976 #: R-exts.texi:6498 #: R-exts.texi:7093 #: R-exts.texi:8349 #: R-exts.texi:11306 #: R-exts.texi:12888 #: R-exts.texi:13062 #: R-exts.texi:13984 #: R-exts.texi:13989 #, no-wrap msgid "Top" msgstr "" # #. type: node #: R-exts.texi:51 #: R-exts.texi:74 #: R-exts.texi:76 #: R-exts.texi:77 #: R-exts.texi:85 #, no-wrap msgid "Acknowledgements" msgstr "" # #. type: node #: R-exts.texi:51 #, no-wrap msgid "(dir)" msgstr "" # #. type: ifnottex #: R-exts.texi:57 msgid "" "This is a guide to extending @R{}, describing the process of creating @R{} " "add-on packages, writing @R{} documentation, @R{}'s system and foreign " "language interfaces, and the @R{} @acronym{API}." msgstr "" # #. type: node #: R-exts.texi:74 #: R-exts.texi:76 #: R-exts.texi:85 #: R-exts.texi:86 #: R-exts.texi:237 #: R-exts.texi:1483 #: R-exts.texi:2496 #: R-exts.texi:3042 #: R-exts.texi:3330 #: R-exts.texi:3931 #: R-exts.texi:4592 #: R-exts.texi:4691 #: R-exts.texi:4856 #: R-exts.texi:4924 #: R-exts.texi:4953 #: R-exts.texi:4976 #, no-wrap msgid "Creating R packages" msgstr "" # #. type: node #: R-exts.texi:74 #: R-exts.texi:85 #: R-exts.texi:4976 #: R-exts.texi:4977 #: R-exts.texi:4999 #: R-exts.texi:5626 #: R-exts.texi:5667 #: R-exts.texi:5815 #: R-exts.texi:5875 #: R-exts.texi:5927 #: R-exts.texi:5991 #: R-exts.texi:6033 #: R-exts.texi:6079 #: R-exts.texi:6115 #: R-exts.texi:6152 #: R-exts.texi:6186 #: R-exts.texi:6286 #: R-exts.texi:6371 #: R-exts.texi:6437 #: R-exts.texi:6474 #: R-exts.texi:6498 #, no-wrap msgid "Writing R documentation files" msgstr "" # #. type: node #: R-exts.texi:74 #: R-exts.texi:4976 #: R-exts.texi:6498 #: R-exts.texi:6499 #: R-exts.texi:6513 #: R-exts.texi:6579 #: R-exts.texi:6693 #: R-exts.texi:6851 #: R-exts.texi:7093 #, no-wrap msgid "Tidying and profiling R code" msgstr "" # #. type: node #: R-exts.texi:74 #: R-exts.texi:6498 #: R-exts.texi:7093 #: R-exts.texi:7094 #: R-exts.texi:7114 #: R-exts.texi:7193 #: R-exts.texi:7509 #: R-exts.texi:8049 #: R-exts.texi:8051 #: R-exts.texi:8349 #, no-wrap msgid "Debugging" msgstr "" # #. type: node #: R-exts.texi:74 #: R-exts.texi:7093 #: R-exts.texi:8349 #: R-exts.texi:8350 #: R-exts.texi:8370 #: R-exts.texi:8394 #: R-exts.texi:8563 #: R-exts.texi:8693 #: R-exts.texi:8991 #: R-exts.texi:9108 #: R-exts.texi:9236 #: R-exts.texi:9254 #: R-exts.texi:9427 #: R-exts.texi:10257 #: R-exts.texi:10502 #: R-exts.texi:10939 #: R-exts.texi:11038 #: R-exts.texi:11213 #: R-exts.texi:11234 #: R-exts.texi:11306 #, no-wrap msgid "System and foreign language interfaces" msgstr "" # #. type: node #: R-exts.texi:74 #: R-exts.texi:8349 #: R-exts.texi:11306 #: R-exts.texi:11398 #: R-exts.texi:11548 #: R-exts.texi:11607 #: R-exts.texi:11664 #: R-exts.texi:11709 #: R-exts.texi:11772 #: R-exts.texi:11845 #: R-exts.texi:12237 #: R-exts.texi:12324 #: R-exts.texi:12411 #: R-exts.texi:12549 #: R-exts.texi:12582 #: R-exts.texi:12611 #: R-exts.texi:12674 #: R-exts.texi:12702 #: R-exts.texi:12760 #: R-exts.texi:12811 #: R-exts.texi:12888 #, no-wrap msgid "The R API" msgstr "" # #. type: node #: R-exts.texi:74 #: R-exts.texi:11306 #: R-exts.texi:12888 #: R-exts.texi:12889 #: R-exts.texi:13022 #: R-exts.texi:13062 #, no-wrap msgid "Generic functions and methods" msgstr "" # #. type: node #: R-exts.texi:74 #: R-exts.texi:12888 #: R-exts.texi:13062 #: R-exts.texi:13063 #: R-exts.texi:13086 #: R-exts.texi:13669 #: R-exts.texi:13984 #, no-wrap msgid "Linking GUIs and other front-ends to R" msgstr "" # #. type: node #: R-exts.texi:74 #: R-exts.texi:13062 #: R-exts.texi:13984 #: R-exts.texi:13985 #: R-exts.texi:13989 #, no-wrap msgid "Function and variable index" msgstr "" # #. type: unnumbered #: R-exts.texi:74 #: R-exts.texi:13984 #: R-exts.texi:13989 #: R-exts.texi:13990 #, no-wrap msgid "Concept index" msgstr "" # #. type: Plain text #: R-exts.texi:84 msgid "" "The contributions to early versions of this manual by Saikat DebRoy (who " "wrote the first draft of a guide to using @code{.Call} and @code{.External}) " "and Adrian Trapletti (who provided information on the C++ interface) are " "gratefully acknowledged." msgstr "" # #. type: cindex #: R-exts.texi:87 #, no-wrap msgid "Packages" msgstr "" # #. type: cindex #: R-exts.texi:88 #, no-wrap msgid "Creating packages" msgstr "" # #. type: Plain text #: R-exts.texi:93 msgid "" "Packages provide a mechanism for loading optional code, data and " "documentation as needed. The @R{} distribution itself includes about 30 " "packages." msgstr "" # #. type: Plain text #: R-exts.texi:98 msgid "" "In the following, we assume that you know the @code{library()} command, " "including its @code{lib.loc} argument, and we also assume basic knowledge of " "the @command{R CMD INSTALL} utility. Otherwise, please look at @R{}'s help " "pages on" msgstr "" # #. type: example #: R-exts.texi:102 #, no-wrap msgid "" "?library\n" "?INSTALL\n" msgstr "" # #. type: Plain text #: R-exts.texi:106 msgid "before reading on." msgstr "" # #. type: Plain text #: R-exts.texi:110 msgid "" "For packages which contain code to be compiled, a computing environment " "including a number of tools is assumed; the ``R Installation and " "Administration'' manual describes what is needed for each OS." msgstr "" # #. type: Plain text #: R-exts.texi:113 msgid "" "Once a source package is created, it must be installed by the command " "@code{R CMD INSTALL}." msgstr "" # #. type: ifset #: R-exts.texi:116 msgid "" "@xref{Add-on packages, , Add-on-packages, R-admin, R Installation and " "Administration}." msgstr "" # #. type: Plain text #: R-exts.texi:119 msgid "" "Other types of extensions are supported (but rare): @xref{Package types}." msgstr "" # #. type: Plain text #: R-exts.texi:123 msgid "" "Some notes on terminology complete this introduction. These will help with " "the reading of this manual, and also in describing concepts accurately when " "asking for help." msgstr "" # #. type: Plain text #: R-exts.texi:132 msgid "" "A @emph{package} is a directory of files which extend @R{}, a @emph{source " "package} (the master files of a package), or a tarball containing the files " "of a source package, or an @emph{installed} package, the result of running " "@command{R CMD INSTALL} on a source package. On some platforms (notably OS " "X and Windows) there are also @emph{binary packages}, a zip file or tarball " "containing the files of an installed package which can be unpacked rather " "than installing from sources." msgstr "" # #. type: Plain text #: R-exts.texi:138 msgid "" "A package is @strong{not}@footnote{although this is a persistent mis-usage. " "It seems to stem from S, whose analogues of @R{}'s packages were officially " "known as @emph{library sections} and later as @emph{chapters}, but almost " "always referred to as @emph{libraries}.} a @emph{library}. The latter is " "used in two senses in @R{} documentation." msgstr "" # #. type: itemize #: R-exts.texi:147 msgid "" "A directory into which packages are installed, e.g.@: @file{/usr/lib/R/" "library}: in that sense it is sometimes referred to as a @emph{library " "directory} or @emph{library tree} (since the library is a directory which " "contains packages as directories, which themselves contain directories)." msgstr "" # #. type: itemize #: R-exts.texi:160 msgid "" "That used by the operating system, as a shared, dynamic or static library or " "(especially on Windows) a DLL, where the second L stands for `library'. " "Installed packages may contain compiled code in what is known on Unix-alikes " "as a @emph{shared object} and on Windows as a DLL. The concept of a " "@emph{shared library} (@emph{dynamic library} on OS X) as a collection of " "compiled code to which a package might link is also used, especially for " "@R{} itself on some platforms. On most platforms these concepts are " "interchangeable (shared objects and DLLs can both be loaded into the @R{} " "process and be linked against), but OS X distinguishes between shared " "objects (extension @file{.so}) and dynamic libraries (extension @file{." "dylib})." msgstr "" # #. type: Plain text #: R-exts.texi:164 msgid "There are a number of well-defined operations on source packages." msgstr "" # #. type: itemize #: R-exts.texi:171 msgid "" "The most common is @emph{installation} which takes a source package and " "installs it in a library using @command{R CMD INSTALL} or @code{install." "packages}." msgstr "" # #. type: itemize #: R-exts.texi:180 msgid "" "Source packages can be @emph{built}. This involves taking a source " "directory and creating a tarball ready for distribution, including cleaning " "it up and creating PDF documentation from any @emph{vignettes} it may " "contain. Source packages (and most often tarballs) can be @emph{checked}, " "when a test installation is done and tested (including running its " "examples); also, the contents of the package are tested in various ways for " "consistency and portability." msgstr "" # #. type: itemize #: R-exts.texi:190 msgid "" "@emph{Compilation} is not a correct term for a package. Installing a source " "package which contains C, C++ or Fortran code will involve compiling that " "code. There is also the possibility of `byte' compiling the @R{} code in a " "package (using the facilities of package @pkg{compiler}): already base and " "recommended packages are normally byte-compiled and this can be specified " "for other packages. So @emph{compiling} a package may come to mean byte-" "compiling its @R{} code." msgstr "" # #. type: itemize #: R-exts.texi:200 msgid "" "It used to be unambiguous to talk about @emph{loading} an installed package " "using @code{library()}, but since the advent of package namespaces this has " "been less clear: people now often talk about @emph{loading} the package's " "namespace and then @emph{attaching} the package so it becomes visible on the " "search path. Function @code{library} performs both steps, but a package's " "namespace can be loaded without the package being attached (for example by " "calls like @code{splines::ns})." msgstr "" # #. type: Plain text #: R-exts.texi:210 msgid "" "The concept of @emph{lazy loading} of code or data is mentioned at several " "points. This is part of the installation, always selected for @R{} code but " "optional for data. When used the @R{} objects of the package are created at " "installation time and stored in a database in the @file{R} directory of the " "installed package, being loaded into the session at first use. This makes " "the @R{} session start up faster and use less (virtual) memory." msgstr "" # #. type: ifset #: R-exts.texi:213 msgid "" "(For technical details, @pxref{Lazy loading, , Lazy loading, R-ints, R " "Internals}.)" msgstr "" # #. type: cindex #: R-exts.texi:215 #, no-wrap msgid "CRAN" msgstr "" #. type: Plain text #: R-exts.texi:221 msgid "" "@acronym{CRAN} is a network of WWW sites holding the @R{} distributions and " "contributed code, especially @R{} packages. Users of @R{} are encouraged to " "join in the collaborative project and to submit their own packages to " "@acronym{CRAN}: current instructions are linked from @uref{https://CRAN.R-" "project.org/@/banner.shtml#submitting}." msgstr "" # #. type: node #: R-exts.texi:235 #: R-exts.texi:237 #: R-exts.texi:238 #: R-exts.texi:239 #: R-exts.texi:335 #: R-exts.texi:680 #: R-exts.texi:798 #: R-exts.texi:1015 #: R-exts.texi:1034 #: R-exts.texi:1319 #: R-exts.texi:1398 #: R-exts.texi:1456 #: R-exts.texi:1483 #, no-wrap msgid "Package structure" msgstr "" # #. type: node #: R-exts.texi:235 #: R-exts.texi:237 #: R-exts.texi:1483 #: R-exts.texi:1484 #: R-exts.texi:1730 #: R-exts.texi:2204 #: R-exts.texi:2339 #: R-exts.texi:2392 #: R-exts.texi:2496 #, no-wrap msgid "Configure and cleanup" msgstr "" # #. type: node #: R-exts.texi:235 #: R-exts.texi:1483 #: R-exts.texi:2496 #: R-exts.texi:2497 #: R-exts.texi:2544 #: R-exts.texi:2851 #: R-exts.texi:2975 #: R-exts.texi:3042 #, no-wrap msgid "Checking and building packages" msgstr "" # #. type: node #: R-exts.texi:235 #: R-exts.texi:2496 #: R-exts.texi:3042 #: R-exts.texi:3043 #: R-exts.texi:3199 #: R-exts.texi:3272 #: R-exts.texi:3330 #, no-wrap msgid "Writing package vignettes" msgstr "" # #. type: node #: R-exts.texi:235 #: R-exts.texi:3042 #: R-exts.texi:3330 #: R-exts.texi:3331 #: R-exts.texi:3388 #: R-exts.texi:3470 #: R-exts.texi:3509 #: R-exts.texi:3554 #: R-exts.texi:3737 #: R-exts.texi:3809 #: R-exts.texi:3931 #, no-wrap msgid "Package namespaces" msgstr "" # #. type: node #: R-exts.texi:235 #: R-exts.texi:3330 #: R-exts.texi:3931 #: R-exts.texi:3932 #: R-exts.texi:4276 #: R-exts.texi:4334 #: R-exts.texi:4362 #: R-exts.texi:4429 #: R-exts.texi:4539 #: R-exts.texi:4592 #, no-wrap msgid "Writing portable packages" msgstr "" # #. type: node #: R-exts.texi:235 #: R-exts.texi:3931 #: R-exts.texi:4592 #: R-exts.texi:4593 #: R-exts.texi:4691 #, no-wrap msgid "Diagnostic messages" msgstr "" # #. type: node #: R-exts.texi:235 #: R-exts.texi:4592 #: R-exts.texi:4691 #: R-exts.texi:4692 #: R-exts.texi:4710 #: R-exts.texi:4768 #: R-exts.texi:4795 #: R-exts.texi:4856 #, no-wrap msgid "Internationalization" msgstr "" # #. type: node #: R-exts.texi:235 #: R-exts.texi:4691 #: R-exts.texi:4856 #: R-exts.texi:4857 #: R-exts.texi:4924 #, no-wrap msgid "CITATION files" msgstr "" # #. type: node #: R-exts.texi:235 #: R-exts.texi:4856 #: R-exts.texi:4924 #: R-exts.texi:4925 #: R-exts.texi:4936 #: R-exts.texi:4953 #, no-wrap msgid "Package types" msgstr "" # #. type: section #: R-exts.texi:235 #: R-exts.texi:4924 #: R-exts.texi:4953 #: R-exts.texi:4954 #, no-wrap msgid "Services" msgstr "" # #. type: Plain text #: R-exts.texi:259 msgid "" "The sources of an @R{} package consists of a subdirectory containing a files " "@file{DESCRIPTION} and @file{NAMESPACE}, and the subdirectories @file{R}, " "@file{data}, @file{demo}, @file{exec}, @file{inst}, @file{man}, @file{po}, " "@file{src}, @file{tests}, @file{tools} and @file{vignettes} (some of which " "can be missing, but which should not be empty). The package subdirectory " "may also contain files @file{INDEX}, @file{configure}, @file{cleanup}, " "@file{LICENSE}, @file{LICENCE} and @file{NEWS}. Other files such as " "@file{INSTALL} (for non-standard installation instructions), @file{README}/" "@file{README.md}@footnote{This seems to be commonly used for a file in " "`markdown' format. Be aware that most users of @R{} will not know that, nor " "know how to view such a file: platforms such as OS X and Windows do not have " "a default viewer set in their file associations. The @acronym{CRAN} package " "web pages render such files in @HTML{}: the converter used expects the file " "to be encoded in UTF-8.}, or @file{ChangeLog} will be ignored by @R{}, but " "may be useful to end users. The utility @command{R CMD build} may add files " "in a @file{build} directory (but this should not be used for other purposes)." msgstr "" # #. type: Plain text #: R-exts.texi:265 msgid "" "Except where specifically mentioned,@footnote{currently, top-level files " "@file{.Rbuildignore} and @file{.Rinstignore}, and @file{vignettes/." "install_extras}.} packages should not contain Unix-style `hidden' files/" "directories (that is, those whose name starts with a dot)." msgstr "" # #. type: Plain text #: R-exts.texi:269 msgid "" "The @file{DESCRIPTION} and @file{INDEX} files are described in the " "subsections below. The @file{NAMESPACE} file is described in the section on " "@ref{Package namespaces}." msgstr "" # #. type: cindex #: R-exts.texi:270 #, no-wrap msgid "configure file" msgstr "" # #. type: cindex #: R-exts.texi:271 #, no-wrap msgid "cleanup file" msgstr "" # #. type: Plain text #: R-exts.texi:278 msgid "" "The optional files @file{configure} and @file{cleanup} are (Bourne shell) " "script files which are, respectively, executed before and (provided that " "option @option{--clean} was given) after installation on Unix-alikes, see " "@ref{Configure and cleanup}. The analogues on Windows are @file{configure." "win} and @file{cleanup.win}." msgstr "" #. type: Plain text #: R-exts.texi:282 msgid "" "For the conventions for files @file{NEWS} and @file{ChangeLog} in the " "@acronym{GNU} project see @uref{https://www.gnu.org/@/prep/@/standards/@/" "standards.html#Documentation}." msgstr "" # #. type: Plain text #: R-exts.texi:289 msgid "" "The package subdirectory should be given the same name as the package. " "Because some file systems (e.g., those on Windows and by default on OS X) " "are not case-sensitive, to maintain portability it is strongly recommended " "that case distinctions not be used to distinguish different packages. For " "example, if you have a package named @file{foo}, do not also create a " "package named @file{Foo}." msgstr "" # #. type: Plain text #: R-exts.texi:311 msgid "" "To ensure that file names are valid across file systems and supported " "operating systems, the @acronym{ASCII} control characters as well as the " "characters @samp{\"}, @samp{*}, @samp{:}, @samp{/}, @samp{<}, @samp{>}, " "@samp{?}, @samp{\\}, and @samp{|} are not allowed in file names. In " "addition, files with names @samp{con}, @samp{prn}, @samp{aux}, @samp{clock" "$}, @samp{nul}, @samp{com1} to @samp{com9}, and @samp{lpt1} to @samp{lpt9} " "after conversion to lower case and stripping possible ``extensions'' (e.g., " "@samp{lpt5.foo.bar}), are disallowed. Also, file names in the same " "directory must not differ only by case (see the previous paragraph). In " "addition, the basenames of @samp{.Rd} files may be used in URLs and so must " "be @acronym{ASCII} and not contain @code{%}. For maximal portability " "filenames should only contain only @acronym{ASCII} characters not excluded " "already (that is @code{A-Za-z0-9._!#$%&+,;=@@^()@{@}'[]} --- we exclude " "space as many utilities do not accept spaces in file paths): non-English " "alphabetic characters cannot be guaranteed to be supported in all locales. " "It would be good practice to avoid the shell metacharacters " "@code{()@{@}'[]$~}: @code{~} is also used as part of `8.3' filenames on " "Windows. In addition, packages are normally distributed as tarballs, and " "these have a limit on path lengths: for maximal portability 100 bytes." msgstr "" # #. type: Plain text #: R-exts.texi:320 msgid "" "A source package if possible should not contain binary executable files: " "they are not portable, and a security risk if they are of the appropriate " "architecture. @command{R CMD check} will warn about them@footnote{false " "positives are possible, but only a handful have been seen so far.} unless " "they are listed (one filepath per line) in a file @file{BinaryFiles} at the " "top level of the package. Note that @acronym{CRAN} will not accept " "submissions containing binary files even if they are listed." msgstr "" # #. type: Plain text #: R-exts.texi:323 msgid "" "The @R{} function @code{package.skeleton} can help to create the structure " "for a new package: see its help page for details." msgstr "" # #. type: node #: R-exts.texi:333 #: R-exts.texi:335 #: R-exts.texi:680 #, no-wrap msgid "The DESCRIPTION file" msgstr "" # #. type: node #: R-exts.texi:333 #: R-exts.texi:335 #: R-exts.texi:680 #: R-exts.texi:681 #: R-exts.texi:798 #, no-wrap msgid "Licensing" msgstr "" # #. type: node #: R-exts.texi:333 #: R-exts.texi:680 #: R-exts.texi:798 #: R-exts.texi:799 #: R-exts.texi:983 #: R-exts.texi:1015 #, no-wrap msgid "Package Dependencies" msgstr "" # #. type: node #: R-exts.texi:333 #: R-exts.texi:798 #: R-exts.texi:1015 #: R-exts.texi:1034 #, no-wrap msgid "The INDEX file" msgstr "" # #. type: node #: R-exts.texi:333 #: R-exts.texi:1015 #: R-exts.texi:1034 #: R-exts.texi:1035 #: R-exts.texi:1036 #: R-exts.texi:1319 #, no-wrap msgid "Package subdirectories" msgstr "" # #. type: node #: R-exts.texi:333 #: R-exts.texi:1034 #: R-exts.texi:1319 #: R-exts.texi:1320 #: R-exts.texi:1398 #, no-wrap msgid "Data in packages" msgstr "" # #. type: node #: R-exts.texi:333 #: R-exts.texi:1319 #: R-exts.texi:1398 #: R-exts.texi:1399 #: R-exts.texi:1456 #, no-wrap msgid "Non-R scripts in packages" msgstr "" #. type: subsection #: R-exts.texi:333 #: R-exts.texi:1398 #: R-exts.texi:1456 #: R-exts.texi:1457 #, no-wrap msgid "Specifying URLs" msgstr "" # #. type: subsection #: R-exts.texi:336 #, no-wrap msgid "The @file{DESCRIPTION} file" msgstr "" # #. type: cindex #: R-exts.texi:337 #, no-wrap msgid "DESCRIPTION file" msgstr "" # #. type: Plain text #: R-exts.texi:341 msgid "" "The @file{DESCRIPTION} file contains basic information about the package in " "the following format:" msgstr "" #. type: smallexample #: R-exts.texi:365 #, no-wrap msgid "" "Package: pkgname\n" "Version: 0.5-1\n" "Date: 2015-01-01\n" "Title: My First Collection of Functions\n" "Authors@@R: c(person(\"Joe\", \"Developer\", role = c(\"aut\", \"cre\"),\n" "\t\t email = \"Joe.Developer@@some.domain.net\"),\n" "\t person(\"Pat\", \"Developer\", role = \"aut\"),\n" "\t person(\"A.\", \"User\", role = \"ctb\",\n" "\t\t email = \"A.User@@whereever.net\"))\n" "Author: Joe Developer [aut, cre],\n" " Pat Developer [aut],\n" " A. User [ctb]\n" "Maintainer: Joe Developer <Joe.Developer@@some.domain.net>\n" "Depends: R (>= 3.1.0), nlme\n" "Suggests: MASS\n" "Description: A (one paragraph) description of what\n" " the package does and why it may be useful.\n" "License: GPL (>= 2)\n" "URL: https://www.r-project.org, http://www.another.url\n" "BugReports: https://pkgname.bugtracker.url\n" msgstr "" #. type: Plain text #: R-exts.texi:379 msgid "" "The format is that of a version of a `Debian Control File' (see the help for " "@samp{read.dcf} and @uref{https://www.debian.org/@/doc/@/debian-policy/@/ch-" "controlfields.html}: @R{} does not require encoding in UTF-8 and does not " "support comments starting with @samp{#}). Fields start with an " "@acronym{ASCII} name immediately followed by a colon: the value starts after " "the colon and a space. Continuation lines (for example, for descriptions " "longer than one line) start with a space or tab. Field names are case-" "sensitive: all those used by @R{} are capitalized." msgstr "" # #. type: Plain text #: R-exts.texi:383 msgid "" "For maximal portability, the @file{DESCRIPTION} file should be written " "entirely in @acronym{ASCII} --- if this is not possible it must contain an " "@samp{Encoding} field (see below)." msgstr "" # #. type: Plain text #: R-exts.texi:387 msgid "" "Several optional fields take @emph{logical values}: these can be specified " "as @samp{yes}, @samp{true}, @samp{no} or @samp{false}: capitalized values " "are also accepted." msgstr "" # #. type: Plain text #: R-exts.texi:394 msgid "" "The @samp{Package}, @samp{Version}, @samp{License}, @samp{Description}, " "@samp{Title}, @samp{Author}, and @samp{Maintainer} fields are mandatory, all " "other fields are optional. Fields @samp{Author} and @samp{Maintainer} can " "be auto-generated from @samp{Authors@@R}, and may be omitted if the latter " "is provided: however if they are not @acronym{ASCII} we recommend that they " "are provided." msgstr "" # #. type: Plain text #: R-exts.texi:401 msgid "" "The mandatory @samp{Package} field gives the name of the package. This " "should contain only (@acronym{ASCII}) letters, numbers and dot, have at " "least two characters and start with a letter and not end in a dot. If it " "needs explaining, this should be done in the @samp{Description} field (and " "not the @samp{Title} field)." msgstr "" # #. type: Plain text #: R-exts.texi:410 msgid "" "The mandatory @samp{Version} field gives the version of the package. This " "is a sequence of at least @emph{two} (and usually three) non-negative " "integers separated by single @samp{.} or @samp{-} characters. The canonical " "form is as shown in the example, and a version such as @samp{0.01} or " "@samp{0.01.0} will be handled as if it were @samp{0.1-0}. It is " "@strong{not} a decimal number, so for example @code{0.9 < 0.75} since " "@code{9 < 75}." msgstr "" # #. type: Plain text #: R-exts.texi:412 msgid "The mandatory @samp{License} field is discussed in the next subsection." msgstr "" #. type: Plain text #: R-exts.texi:423 msgid "" "The mandatory @samp{Title} field should give a @emph{short} description of " "the package. Some package listings may truncate the title to 65 " "characters. It should use @emph{title case} (that is, use capitals for the " "principal words: @code{tools::toTitleCase} can help you with this), not use " "any markup, not have any continuation lines, and not end in a period (unless " "part of @dots{}). Do not repeat the package name: it is often used prefixed " "by the name. Refer to other packages and external software in single " "quotes, and to book titles (and similar) in double quotes." msgstr "" #. type: Plain text #: R-exts.texi:437 msgid "" "The mandatory @samp{Description} field should give a @emph{comprehensive} " "description of what the package does. One can use several (complete) " "sentences, but only one paragraph. It should be intelligible to all the " "intended readership (e.g.@: for a @acronym{CRAN} package to all " "@acronym{CRAN} users). It is good practice not to start with the package " "name, `This package' or similar. As with the @samp{Title} field, double " "quotes should be used for quotations (including titles of books and " "articles), and single quotes for non-English usage, including names of other " "packages and external software. This field should also be used for " "explaining the package name if necessary. URLs should be enclosed in angle " "brackets, e.g.@: @samp{<https://www.r-project.org>}: see also " "@ref{Specifying URLs}." msgstr "" # #. type: Plain text #: R-exts.texi:447 msgid "" "The mandatory @samp{Author} field describes who wrote @emph{the package}. " "It is a plain text field intended for human readers, but not for automatic " "processing (such as extracting the email addresses of all listed " "contributors: for that use @samp{Authors@@R}). Note that all significant " "contributors must be included: if you wrote an @R{} wrapper for the work of " "others included in the @file{src} directory, you are not the sole (and maybe " "not even the main) author." msgstr "" # #. type: Plain text #: R-exts.texi:456 msgid "" "The mandatory @samp{Maintainer} field should give a @emph{single} name " "followed by a @emph{valid} (RFC 2822) email address in angle brackets. It " "should not end in a period or comma. This field is what is reported by the " "@code{maintainer} function and used by @code{bug.report}. For a " "@acronym{CRAN} package it should be a @emph{person}, not a mailing list and " "not a corporate entity: do ensure that it is valid and will remain valid for " "the lifetime of the package." msgstr "" # #. type: Plain text #: R-exts.texi:461 msgid "" "Note that the @emph{display name} (the part before the address in angle " "brackets) should be enclosed in double quotes if it contains non-" "alphanumeric characters such as comma or period. (The current standard, RFC " "5322, allows periods but RFC 2822 did not.)" msgstr "" # #. type: Plain text #: R-exts.texi:478 msgid "" "Both @samp{Author} and @samp{Maintainer} fields can be omitted if a suitable " "@samp{Authors@@R} field is given. This field can be used to provide a " "refined and machine-readable description of the package ``authors'' (in " "particular specifying their precise @emph{roles}), via suitable @R{} code. " "It should create an object of class @code{\"person'}, by either a call to " "@code{person} or a series of calls (one per ``author'') concatenated by " "@code{c()}): see the example @file{DESCRIPTION} file above. The roles can " "include @samp{\"aut\"} (author) for full authors, @samp{\"cre\"} (creator) " "for the package maintainer, and @samp{\"ctb\"} (contributor) for other " "contributors, @samp{\"cph\"} (copyright holder), among others. See @code{?" "person} for more information. Note that no role is assumed by default. " "Auto-generated package citation information takes advantage of this " "specification. The @samp{Author} and @samp{Maintainer} fields are auto-" "generated from it if needed when building@footnote{at least if this is done " "in a locale which matches the package encoding.} or installing." msgstr "" # #. type: findex #: R-exts.texi:479 #: R-exts.texi:1266 #, no-wrap msgid "COPYRIGHTS" msgstr "" # #. type: Plain text #: R-exts.texi:484 msgid "" "An optional @samp{Copyright} field can be used where the copyright holder(s) " "are not the authors. If necessary, this can refer to an installed file: the " "convention is to use file @file{inst/COPYRIGHTS}." msgstr "" #. type: Plain text #: R-exts.texi:491 msgid "" "The optional @samp{Date} field gives the @emph{release date} of the current " "version of the package. It is strongly recommended@footnote{and required by " "@acronym{CRAN}, so checked by @command{R CMD check --as-cran}.} to use the " "@samp{yyyy-mm-dd} format conforming to the ISO 8601 standard." msgstr "" # #. type: Plain text #: R-exts.texi:495 msgid "" "The @samp{Depends}, @samp{Imports}, @samp{Suggests}, @samp{Enhances}, " "@samp{LinkingTo} and @samp{Additional_repositories} fields are discussed in " "a later subsection." msgstr "" # #. type: Plain text #: R-exts.texi:500 msgid "" "Dependencies external to the @R{} system should be listed in the " "@samp{SystemRequirements} field, possibly amplified in a separate " "@file{README} file." msgstr "" #. type: Plain text #: R-exts.texi:507 msgid "" "The @samp{URL} field may give a list of @acronym{URL}s separated by commas " "or whitespace, for example the homepage of the author or a page where " "additional material describing the software can be found. These " "@acronym{URL}s are converted to active hyperlinks in @acronym{CRAN} package " "listings. @xref{Specifying URLs}." msgstr "" # #. type: Plain text #: R-exts.texi:513 msgid "" "The @samp{BugReports} field may contain a single @acronym{URL} to which bug " "reports about the package should be submitted. This @acronym{URL} will be " "used by @code{bug.report} instead of sending an email to the maintainer." msgstr "" # #. type: Plain text #: R-exts.texi:520 msgid "" "Base and recommended packages (i.e., packages contained in the @R{} source " "distribution or available from @acronym{CRAN} and recommended to be included " "in every binary distribution of @R{}) have a @samp{Priority} field with " "value @samp{base} or @samp{recommended}, respectively. These priorities " "must not be used by other packages." msgstr "" # #. type: Plain text #: R-exts.texi:536 msgid "" "A @samp{Collate} field can be used for controlling the collation order for " "the @R{} code files in a package when these are processed for package " "installation. The default is to collate according to the @samp{C} locale. " "If present, the collate specification must list @emph{all} @R{} code files " "in the package (taking possible OS-specific subdirectories into account, see " "@ref{Package subdirectories}) as a whitespace separated list of file paths " "relative to the @file{R} subdirectory. Paths containing white space or " "quotes need to be quoted. An OS-specific collation field (@samp{Collate." "unix} or @samp{Collate.windows}) will be used in preference to " "@samp{Collate}." msgstr "" # #. type: Plain text #: R-exts.texi:542 msgid "" "The @samp{LazyData} logical field controls whether the @R{} datasets use " "lazy-loading. A @samp{LazyLoad} field was used in versions prior to 2.14.0, " "but now is ignored." msgstr "" # #. type: Plain text #: R-exts.texi:548 msgid "" "The @samp{KeepSource} logical field controls if the package code is sourced " "using @code{keep.source = TRUE} or @code{FALSE}: it might be needed " "exceptionally for a package designed to always be used with @code{keep." "source = TRUE}." msgstr "" # #. type: Plain text #: R-exts.texi:558 msgid "" "The @samp{ByteCompile} logical field controls if the package code is to be " "byte-compiled on installation: the default is currently not to, so this may " "be useful for a package known to benefit particularly from byte-compilation " "(which can take quite a long time and increases the installed size of the " "package). It is used for the recommended packages, as they are byte-" "compiled when @R{} is installed and for consistency should be byte-compiled " "when updated. This can be overridden by installing with flag @option{--no-" "byte-compile}." msgstr "" # #. type: Plain text #: R-exts.texi:563 msgid "" "The @samp{ZipData} logical field was used to control whether the automatic " "Windows build would zip up the data directory or not prior to @R{} 2.13.0: " "it is now ignored." msgstr "" # #. type: Plain text #: R-exts.texi:568 msgid "" "The @samp{Biarch} logical field is used on Windows to select the " "@command{INSTALL} option @option{--force-biarch} for this package. " "(Introduced in @R{} 3.0.0.)" msgstr "" # #. type: Plain text #: R-exts.texi:577 msgid "" "The @samp{BuildVignettes} logical field can be set to a false value to stop " "@command{R CMD build} from attempting to build the vignettes, as well as " "preventing@footnote{But it is checked for Open Source packages by @command{R " "CMD check --as-cran}.} @command{R CMD check} from testing this. This should " "only be used exceptionally, for example if the PDFs include large figures " "which are not part of the package sources (and hence only in packages which " "do not have an Open Source license)." msgstr "" # #. type: Plain text #: R-exts.texi:585 msgid "" "The @samp{VignetteBuilder} field names (in a comma-separated list) packages " "that provide an engine for building vignettes. These may include the " "current package, or ones listed in @samp{Depends}, @samp{Suggests} or " "@samp{Imports}. The @pkg{utils} package is always implicitly appended. See " "@ref{Non-Sweave vignettes} for details." msgstr "" # #. type: Plain text #: R-exts.texi:598 msgid "" "If the @file{DESCRIPTION} file is not entirely in @acronym{ASCII} it should " "contain an @samp{Encoding} field specifying an encoding. This is used as " "the encoding of the @file{DESCRIPTION} file itself and of the @file{R} and " "@file{NAMESPACE} files, and as the default encoding of @file{.Rd} files. " "The examples are assumed to be in this encoding when running @command{R CMD " "check}, and it is used for the encoding of the @code{CITATION} file. Only " "encoding names @code{latin1}, @code{latin2} and @code{UTF-8} are known to be " "portable. (Do not specify an encoding unless one is actually needed: doing " "so makes the package @emph{less} portable. If a package has a specified " "encoding, you should run @command{R CMD build} etc in a locale using that " "encoding.)" msgstr "" # #. type: Plain text #: R-exts.texi:608 msgid "" "The @samp{NeedsCompilation} field should be set to @code{\"yes\"} if the " "package contains code which to be compiled, otherwise @code{\"no\"} (when " "the package could be installed from source on any platform without " "additional tools). This is used by @code{install.packages(type = \"both\")} " "in @R{} >= 2.15.2 on platforms where binary packages are the norm: it is " "normally set by @command{R CMD build} or the repository assuming compilation " "is required if and only if the package has a @file{src} directory." msgstr "" # #. type: Plain text #: R-exts.texi:614 msgid "" "The @samp{OS_type} field specifies the OS(es) for which the package is " "intended. If present, it should be one of @code{unix} or @code{windows}, " "and indicates that the package can only be installed on a platform with " "@samp{.Platform$OS.type} having that value." msgstr "" # #. type: Plain text #: R-exts.texi:618 msgid "" "The @samp{Type} field specifies the type of the package: @pxref{Package " "types}." msgstr "" # #. type: Plain text #: R-exts.texi:637 msgid "" "One can add subject classifications for the content of the package using the " "fields @samp{Classification/ACM} or @samp{Classification/ACM-2012} (using " "the Computing Classification System of the Association for Computing " "Machinery, @uref{http://www.acm.org/class/}; the former refers to the 1998 " "version), @samp{Classification/JEL} (the Journal of Economic Literature " "Classification System, @uref{https://www.aeaweb.org/@/econlit/@/jelCodes." "php}, or @samp{Classification/MSC} or @samp{Classification/MSC-2010} (the " "Mathematics Subject Classification of the American Mathematical Society, " "@uref{http://www.ams.org/msc/}; the former refers to the 2000 version). The " "subject classifications should be comma-separated lists of the respective " "classification codes, e.g., @samp{Classification/ACM: G.4, H.2.8, I.5.1}." msgstr "" #. type: Plain text #: R-exts.texi:649 msgid "" "A @samp{Language} field can be used to indicate if the package documentation " "is not in English: this should be a comma-separated list of standard (not " "private use or grandfathered) IETF language tags as currently defined by RFC " "5646 (@uref{https://tools.ietf.org/@/html/@/rfc5646}, see also @uref{https://" "en.wikipedia.org/@/wiki/@/IETF_language_tag}), i.e., use language subtags " "which in essence are 2-letter ISO 639-1 (@uref{https://en.wikipedia.@/org/@/" "wiki/@/ISO_639-1}) or 3-letter ISO 639-3 (@uref{https://en.wikipedia.@/org/@/" "wiki/@/ISO_639-3}) language codes." msgstr "" # #. type: Plain text #: R-exts.texi:660 msgid "" "As of @R{} 3.2.0, an @samp{RdMacros} field can be used to hold a comma-" "separated list of packages from which the current package will import Rd " "macro definitions. These will be imported after the system macros, in the " "order listed in the @samp{RdMacros} field, before any macro definitions in " "the current package are loaded. Macro definitions in individual @file{.Rd} " "files in the @file{man} directory are loaded last, and are local to later " "parts of that file. In case of any duplicates, the last loaded definition " "will be used@footnote{Duplicate definitions may trigger a warning: see " "@ref{User-defined macros}.}" msgstr "" # #. type: quotation #: R-exts.texi:663 #: R-exts.texi:2515 #: R-exts.texi:11361 #, no-wrap msgid "Note" msgstr "" # #. type: quotation #: R-exts.texi:666 msgid "" "There should be no @samp{Built} or @samp{Packaged} fields, as these are " "added by the package management tools." msgstr "" # #. type: Plain text #: R-exts.texi:677 msgid "" "There is no restriction on the use of other fields not mentioned here (but " "using other capitalizations of these field names would cause confusion). " "Fields @code{Note}, @code{Contact} (for contacting the authors/developers) " "and @code{MailingList} are in common use. Some repositories (including " "@acronym{CRAN} and R-forge) add their own fields." msgstr "" # #. type: Plain text #: R-exts.texi:685 msgid "" "Licensing for a package which might be distributed is an important but " "potentially complex subject." msgstr "" # #. type: Plain text #: R-exts.texi:689 msgid "" "It is very important that you include license information! Otherwise, it may " "not even be legally correct for others to distribute copies of the package, " "let alone use it." msgstr "" #. type: Plain text #: R-exts.texi:698 msgid "" "The package management tools use the concept of `free or open source " "software' (FOSS, e.g., @uref{https://en.wikipedia.org/@/wiki/@/FOSS}) " "licenses: the idea being that some users of @R{} and its packages want to " "restrict themselves to such software. Others need to ensure that there are " "no restrictions stopping them using a package, e.g.@: forbidding commercial " "or military use. It is a central tenet of FOSS software that there are no " "restrictions on users nor usage." msgstr "" # #. type: Plain text #: R-exts.texi:701 msgid "" "Do not use the @samp{License} field for information on copyright holders: if " "needed, use a @samp{Copyright} field." msgstr "" # #. type: Plain text #: R-exts.texi:709 msgid "" "The mandatory @samp{License} field in the @file{DESCRIPTION} file should " "specify the license of the package in a standardized form. Alternatives are " "indicated @emph{via} vertical bars. Individual specifications must be one of" msgstr "" # #. type: itemize #: R-exts.texi:712 msgid "One of the ``standard'' short specifications" msgstr "" # #. type: example #: R-exts.texi:715 #, no-wrap msgid "" "GPL-2 GPL-3 LGPL-2 LGPL-2.1 LGPL-3 AGPL-3 Artistic-2.0\n" "BSD_2_clause BSD_3_clause MIT\n" msgstr "" #. type: itemize #: R-exts.texi:719 msgid "" "as made available @emph{via} @uref{https://www.R-project.org/@/Licenses/} " "and contained in subdirectory @file{share/licenses} of the @R{} source or " "home directory." msgstr "" # #. type: itemize #: R-exts.texi:730 msgid "" "The names or abbreviations of other licenses contained in the license data " "base in file @file{share/licenses/license.db} in the @R{} source or home " "directory, possibly (for versioned licenses) followed by a version " "restriction of the form @samp{(@var{op} @var{v})} with @samp{@var{op}} one " "of the comparison operators @samp{<}, @samp{<=}, @samp{>}, @samp{>=}, " "@samp{==}, or @samp{!=} and @samp{@var{v}} a numeric version specification " "(strings of non-negative integers separated by @samp{.}), possibly combined " "@emph{via} @samp{,} (see below for an example). For versioned licenses, one " "can also specify the name followed by the version, or combine an existing " "abbreviation and the version with a @samp{-}." msgstr "" # #. type: itemize #: R-exts.texi:733 msgid "" "Abbreviations @code{GPL} and @code{LGPL} are ambiguous and usually taken to " "mean any version of the license: but it is better not to use them." msgstr "" # #. type: itemize #: R-exts.texi:737 msgid "" "One of the strings @samp{file LICENSE} or @samp{file LICENCE} referring to a " "file named @file{LICENSE} or @file{LICENCE} in the package (source and " "installation) top-level directory." msgstr "" # #. type: itemize #: R-exts.texi:741 msgid "" "The string @samp{Unlimited}, meaning that there are no restrictions on " "distribution or use other than those imposed by relevant laws (including " "copyright laws)." msgstr "" # #. type: Plain text #: R-exts.texi:751 msgid "" "If a package license @emph{restricts} a base license (where permitted, e.g., " "using GPL-3 or AGPL-3 with an attribution clause), the additional terms " "should be placed in file @file{LICENSE} (or @file{LICENCE}), and the string " "@samp{+ file LICENSE} (or @samp{+ file LICENCE}, respectively) should be " "appended to the corresponding individual license specification. Note that " "several commonly used licenses do not permit restrictions: this includes " "GPL-2 and hence any specification which includes it." msgstr "" # #. type: Plain text #: R-exts.texi:753 msgid "Examples of standardized specifications include" msgstr "" # #. type: example #: R-exts.texi:759 #, no-wrap msgid "" "License: GPL-2\n" "License: LGPL (>= 2.0, < 3) | Mozilla Public License\n" "License: GPL-2 | file LICENCE\n" "License: GPL (>= 2) | BSD_3_clause + file LICENSE\n" "License: Artistic-2.0 | AGPL-3 + file LICENSE\n" msgstr "" # #. type: Plain text #: R-exts.texi:762 msgid "" "Please note in particular that ``Public domain'' is not a valid license, " "since it is not recognized in some jurisdictions." msgstr "" # #. type: Plain text #: R-exts.texi:767 msgid "" "Please ensure that the license you choose also covers any dependencies " "(including system dependencies) of your package: it is particularly " "important that any restrictions on the use of such dependencies are evident " "to people reading your @file{DESCRIPTION} file." msgstr "" # #. type: Plain text #: R-exts.texi:775 msgid "" "Fields @samp{License_is_FOSS} and @samp{License_restricts_use} may be added " "by repositories where information cannot be computed from the name of the " "license. @samp{License_is_FOSS: yes} is used for licenses which are known " "to be FOSS, and @samp{License_restricts_use} can have values @samp{yes} or " "@samp{no} if the @file{LICENSE} file is known to restrict users or usage, or " "known not to. These are used by, e.g.@:, the @code{available.packages} " "filters." msgstr "" # #. type: cindex #: R-exts.texi:777 #, no-wrap msgid "LICENSE file" msgstr "" # #. type: cindex #: R-exts.texi:778 #, no-wrap msgid "LICENCE file" msgstr "" # #. type: Plain text #: R-exts.texi:783 msgid "" "The optional file @file{LICENSE}/@file{LICENCE} contains a copy of the " "license of the package. To avoid any confusion only include such a file if " "it is referred to in the @samp{License} field of the @file{DESCRIPTION} file." msgstr "" #. type: Plain text #: R-exts.texi:794 msgid "" "Whereas you should feel free to include a license file in your @emph{source} " "distribution, please do not arrange to @emph{install} yet another copy of " "the @acronym{GNU} @file{COPYING} or @file{COPYING.LIB} files but refer to " "the copies on @uref{https://www.R-project.org/@/Licenses/} and included in " "the @R{} distribution (in directory @file{share/licenses}). Since files " "named @file{LICENSE} or @file{LICENCE} @emph{will} be installed, do not use " "these names for standard license files. To include comments about the " "licensing rather than the body of a license, use a file named something like " "@file{LICENSE.note}." msgstr "" # #. type: Plain text #: R-exts.texi:797 msgid "" "A few ``standard'' licenses are rather license templates which need " "additional information to be completed @emph{via} @samp{+ file LICENSE}." msgstr "" # #. type: Plain text #: R-exts.texi:809 msgid "" "The @samp{Depends} field gives a comma-separated list of package names which " "this package depends on. Those packages will be attached before the current " "package when @code{library} or @code{require} is called. Each package name " "may be optionally followed by a comment in parentheses specifying a version " "requirement. The comment should contain a comparison operator, whitespace " "and a valid version number, e.g. @samp{MASS (>= 3.1-20)}." msgstr "" # #. type: Plain text #: R-exts.texi:817 msgid "" "The @samp{Depends} field can also specify a dependence on a certain version " "of @R{} --- e.g., if the package works only with @R{} version 3.0.0 or " "later, include @samp{R (>= 3.0.0)} in the @samp{Depends} field. You can " "also require a certain SVN revision for R-devel or R-patched, e.g.@: @samp{R " "(>= 2.14.0), R (>= r56550)} requires a version later than R-devel of late " "July 2011 (including released versions of 2.14.0)." msgstr "" # #. type: Plain text #: R-exts.texi:821 msgid "" "It makes no sense to declare a dependence on @code{R} without a version " "specification, nor on the package @pkg{base}: this is an @R{} package and " "package @pkg{base} is always available." msgstr "" # #. type: Plain text #: R-exts.texi:824 msgid "" "A package or @samp{R} can appear more than once in the @samp{Depends} field, " "for example to give upper and lower bounds on acceptable versions." msgstr "" # #. type: Plain text #: R-exts.texi:832 msgid "" "Both @code{library} and the @R{} package checking facilities use this field: " "hence it is an error to use improper syntax or misuse the @samp{Depends} " "field for comments on other software that might be needed. The @R{} " "@command{INSTALL} facilities check if the version of @R{} used is recent " "enough for the package being installed, and the list of packages which is " "specified will be attached (after checking version requirements) before the " "current package." msgstr "" # #. type: Plain text #: R-exts.texi:845 msgid "" "The @samp{Imports} field lists packages whose namespaces are imported from " "(as specified in the @file{NAMESPACE} file) but which do not need to be " "attached. Namespaces accessed by the @samp{::} and @samp{:::} operators " "must be listed here, or in @samp{Suggests} or @samp{Enhances} (see below). " "Ideally this field will include all the standard packages that are used, and " "it is important to include S4-using packages (as their class definitions can " "change and the @file{DESCRIPTION} file is used to decide which packages to " "re-install when this happens). Packages declared in the @samp{Depends} " "field should not also be in the @samp{Imports} field. Version requirements " "can be specified and are checked when the namespace is loaded (since @R{} >= " "3.0.0)." msgstr "" # #. type: Plain text #: R-exts.texi:857 msgid "" "The @samp{Suggests} field uses the same syntax as @samp{Depends} and lists " "packages that are not necessarily needed. This includes packages used only " "in examples, tests or vignettes (@pxref{Writing package vignettes}), and " "packages loaded in the body of functions. E.g., suppose an " "example@footnote{even one wrapped in @code{\\donttest}.} from package " "@pkg{foo} uses a dataset from package @pkg{bar}. Then it is not necessary to " "have @pkg{bar} use @pkg{foo} unless one wants to execute all the examples/" "tests/vignettes: it is useful to have @pkg{bar}, but not necessary. Version " "requirements can be specified, and will be used by @command{R CMD check}." msgstr "" # #. type: Plain text #: R-exts.texi:869 msgid "" "Finally, the @samp{Enhances} field lists packages ``enhanced'' by the " "package at hand, e.g., by providing methods for classes from these packages, " "or ways to handle objects from these packages (so several packages have " "@samp{Enhances: chron} because they can handle datetime objects from " "@CRANpkg{chron} even though they prefer @R{}'s native datetime functions). " "Version requirements can be specified, but are currently not used. Such " "packages cannot be required to check the package: any tests which use them " "must be conditional on the presence of the package. (If your tests use e.g." "@: a dataset from another package it should be in @samp{Suggests} and not " "@samp{Enhances}.)" msgstr "" # #. type: Plain text #: R-exts.texi:871 msgid "The general rules are" msgstr "" # #. type: itemize #: R-exts.texi:875 msgid "A package should be listed in only one of these fields." msgstr "" # #. type: itemize #: R-exts.texi:881 msgid "" "Packages whose namespace only is needed to load the package using " "@code{library(@var{pkgname})} should be listed in the @samp{Imports} field " "and not in the @samp{Depends} field. Packages listed in @code{imports} or " "@code{importFrom} directives in the @file{NAMESPACE} file should almost " "always be in @samp{Imports} and not @samp{Depends}." msgstr "" # #. type: itemize #: R-exts.texi:885 msgid "" "Packages that need to be attached to successfully load the package using " "@code{library(@var{pkgname})} must be listed in the @samp{Depends} field." msgstr "" # #. type: itemize #: R-exts.texi:901 msgid "" "All packages that are needed@footnote{This includes all packages directly " "called by @code{library} and @code{require} calls, as well as data obtained " "@emph{via} @code{data(theirdata, package = \"somepkg\")} calls: @command{R " "CMD check} will warn about all of these. But there are subtler uses which " "it will not detect: e.g.@: if package A uses package B and makes use of " "functionality in package B which uses package C which package B suggests or " "enhances, then package C needs to be in the @samp{Suggests} list for package " "A. Nor will undeclared uses in included files be reported, nor " "unconditional uses of packages listed under @samp{Enhances}.} to " "successfully run @code{R CMD check} on the package must be listed in one of " "@samp{Depends} or @samp{Suggests} or @samp{Imports}. Packages used to run " "examples or tests conditionally (e.g.@: @emph{via} " "@code{if(require(@var{pkgname}))}) should be listed in @samp{Suggests} or " "@samp{Enhances}. (This allows checkers to ensure that all the packages " "needed for a complete check are installed.)" msgstr "" # #. type: Plain text #: R-exts.texi:907 msgid "" "In particular, packages providing ``only'' data for examples or vignettes " "should be listed in @samp{Suggests} rather than @samp{Depends} in order to " "make lean installations possible." msgstr "" # #. type: Plain text #: R-exts.texi:913 msgid "" "Version dependencies in the @samp{Depends} and @samp{Imports} fields are " "used by @code{library} when it loads the package, and @code{install." "packages} checks versions for the @samp{Depends}, @samp{Imports} and (for " "@code{dependencies = TRUE}) @samp{Suggests} fields." msgstr "" # #. type: Plain text #: R-exts.texi:918 msgid "" "It is increasingly important that the information in these fields is " "complete and accurate: it is for example used to compute which packages " "depend on an updated package and which packages can safely be installed in " "parallel." msgstr "" # #. type: Plain text #: R-exts.texi:922 msgid "" "This scheme was developed before all packages had namespaces (@R{} 2.14.0 in " "October 2011), and good practice changed once that was in place." msgstr "" # #. type: Plain text #: R-exts.texi:928 msgid "" "Field @samp{Depends} should nowadays be used rarely, only for packages which " "are intended to be put on the search path to make their facilities available " "to the end user (and not to the package itself): for example it makes sense " "that a user of package @CRANpkg{latticeExtra} would want the functions of " "package @CRANpkg{lattice} made available." msgstr "" # #. type: Plain text #: R-exts.texi:933 msgid "" "Almost always packages mentioned in @samp{Depends} should also be imported " "from in the @file{NAMESPACE} file: this ensures that any needed parts of " "those packages are available when some other package imports the current " "package." msgstr "" # #. type: Plain text #: R-exts.texi:939 msgid "" "The @samp{Imports} field should not contain packages which are not imported " "from (@emph{via} the @file{NAMESPACE} file or @code{::} or @code{:::} " "operators), as all the packages listed in that field need to be installed " "for the current package to be installed. (This is checked by @command{R CMD " "check}.)" msgstr "" # #. type: Plain text #: R-exts.texi:947 msgid "" "@R{} code in the package should call @code{library} or @code{require} only " "exceptionally. Such calls are never needed for packages listed in " "@samp{Depends} as they will already be on the search path. It used to be " "common practice to use @code{require} calls for packages listed in " "@samp{Suggests} in functions which used their functionality, but nowadays it " "is better to access such functionality @emph{via} @code{::} calls." msgstr "" # #. type: Plain text #: R-exts.texi:952 msgid "" "A package that wishes to make use of header files in other packages needs to " "declare them as a comma-separated list in the field @samp{LinkingTo} in the " "@file{DESCRIPTION} file. For example" msgstr "" # #. type: example #: R-exts.texi:955 #, no-wrap msgid "LinkingTo: link1, link2\n" msgstr "" # #. type: Plain text #: R-exts.texi:961 msgid "" "As from @R{} 3.0.2 the @samp{LinkingTo} field can have a version requirement " "which is checked at installation. (In earlier versions of @R{} it would " "cause the specification to be ignored.)" msgstr "" #. type: Plain text #: R-exts.texi:968 msgid "" "Specifying a package in @samp{LinkingTo} suffices if these are C++ headers " "containing source code or static linking is done at installation: the " "packages do not need to be (and usually should not be) listed in the " "@samp{Depends} or @samp{Imports} fields. This includes @acronym{CRAN} " "package @CRANpkg{BH} and almost all users of @CRANpkg{RcppArmadillo} and " "@CRANpkg{RcppEigen}." msgstr "" # #. type: Plain text #: R-exts.texi:971 msgid "" "For another use of @samp{LinkingTo} see @ref{Linking to native routines in " "other packages}." msgstr "" #. type: Plain text #: R-exts.texi:978 msgid "" "The @samp{Additional_repositories} field is a comma-separated list of " "repository URLs where the packages named in the other fields may be found. " "It is currently used by @command{R CMD check} to check that the packages can " "be found, at least as source packages (which can be installed on any " "platform)." msgstr "" # #. type: subsubsection #: R-exts.texi:981 #: R-exts.texi:983 #: R-exts.texi:984 #, no-wrap msgid "Suggested packages" msgstr "" # #. type: Plain text #: R-exts.texi:991 msgid "" "Note that someone wanting to run the examples/tests/vignettes may not have a " "suggested package available (and it may not even be possible to install it " "for that platform). The recommendation used to be to make their use " "conditional @emph{via} @code{if(require(\"@var{pkgname}\"))}): this is fine " "if that conditioning is done in examples/tests/vignettes." msgstr "" # #. type: Plain text #: R-exts.texi:997 msgid "" "However, using @code{require} for conditioning @emph{in package code} is not " "good practice as it alters the search path for the rest of the session and " "relies on functions in that package not being masked by other @code{require} " "or @code{library} calls. It is better practice to use code like" msgstr "" # #. type: example #: R-exts.texi:1003 #, no-wrap msgid "" " if (requireNamespace(\"rgl\", quietly = TRUE)) @{\n" " rgl::plot3d(...)\n" " @} else @{\n" " ## do something else not involving rgl.\n" " @}\n" msgstr "" # #. type: Plain text #: R-exts.texi:1010 msgid "" "Note the use of @code{rgl::} as that object would not necessarily be visible " "(and if it is, it need not be the one from that namespace: @code{plot3d} " "occurs in several other packages). If the intention is to give an error if " "the suggested package is not available, simply use e.g.@: @code{rgl::plot3d}." msgstr "" # #. type: Plain text #: R-exts.texi:1014 msgid "" "As noted above, packages in @samp{Enhances} @emph{must} be used " "conditionally and hence objects within them should always be accessed " "@emph{via} @code{::}." msgstr "" # #. type: subsection #: R-exts.texi:1016 #, no-wrap msgid "The @file{INDEX} file" msgstr "" # #. type: cindex #: R-exts.texi:1017 #, no-wrap msgid "INDEX file" msgstr "" # #. type: Plain text #: R-exts.texi:1025 msgid "" "The optional file @file{INDEX} contains a line for each sufficiently " "interesting object in the package, giving its name and a description " "(functions such as print methods not usually called explicitly might not be " "included). Normally this file is missing and the corresponding information " "is automatically generated from the documentation sources (using " "@code{tools::Rdindex()}) when installing from source." msgstr "" # #. type: Plain text #: R-exts.texi:1028 msgid "" "The file is part of the information given by @code{library(help = " "@var{pkgname})}." msgstr "" # #. type: Plain text #: R-exts.texi:1033 msgid "" "Rather than editing this file, it is preferable to put customized " "information about the package into an overview help page (@pxref{Documenting " "packages}) and/or a vignette (@pxref{Writing package vignettes})." msgstr "" # #. type: Plain text #: R-exts.texi:1056 msgid "" "The @file{R} subdirectory contains @R{} code files, only. The code files to " "be installed must start with an @acronym{ASCII} (lower or upper case) letter " "or digit and have one of the extensions@footnote{Extensions @file{.S} and " "@file{.s} arise from code originally written for S(-PLUS), but are commonly " "used for assembler code. Extension @file{.q} was used for S, which at one " "time was tentatively called QPE.} @file{.R}, @file{.S}, @file{.q}, @file{." "r}, or @file{.s}. We recommend using @file{.R}, as this extension seems to " "be not used by any other software. It should be possible to read in the " "files using @code{source()}, so @R{} objects must be created by " "assignments. Note that there need be no connection between the name of the " "file and the @R{} objects created by it. Ideally, the @R{} code files " "should only directly assign @R{} objects and definitely should not call " "functions with side effects such as @code{require} and @code{options}. If " "computations are required to create objects these can use code `earlier' in " "the package (see the @samp{Collate} field) plus functions in the " "@samp{Depends} packages provided that the objects created do not depend on " "those packages except @emph{via} namespace imports." msgstr "" # #. type: Plain text #: R-exts.texi:1066 msgid "" "Two exceptions are allowed: if the @file{R} subdirectory contains a file " "@file{sysdata.rda} (a saved image of one or more @R{} objects: please use " "suitable compression as suggested by @code{tools::resaveRdaFiles}, and see " "also the @samp{SysDataCompression} @file{DESCRIPTION} field.) this will be " "lazy-loaded into the namespace environment -- this is intended for system " "datasets that are not intended to be user-accessible @emph{via} " "@code{data}. Also, files ending in @samp{.in} will be allowed in the " "@file{R} directory to allow a @file{configure} script to generate suitable " "files." msgstr "" #. type: Plain text #: R-exts.texi:1079 msgid "" "Only @acronym{ASCII} characters (and the control characters tab, formfeed, " "LF and CR) should be used in code files. Other characters are accepted in " "comments@footnote{but they should be in the encoding declared in the " "@file{DESCRIPTION} file.}, but then the comments may not be readable in e.g." "@: a UTF-8 locale. Non-@acronym{ASCII} characters in object names will " "normally@footnote{This is true for OSes which implement the @samp{C} locale: " "Windows' idea of the @samp{C} locale uses the WinAnsi charset.} fail when " "the package is installed. Any byte will be allowed in a quoted character " "string but @code{\\uxxxx} escapes should be used for non-@acronym{ASCII} " "characters. However, non-@acronym{ASCII} character strings may not be " "usable in some locales and may display incorrectly in others." msgstr "" # #. type: findex #: R-exts.texi:1081 #: R-exts.texi:8597 #, no-wrap msgid "library.dynam" msgstr "" # #. type: Plain text #: R-exts.texi:1084 msgid "" "Various @R{} functions in a package can be used to initialize and clean up. " "@xref{Load hooks}." msgstr "" # #. type: Plain text #: R-exts.texi:1103 msgid "" "The @file{man} subdirectory should contain (only) documentation files for " "the objects in the package in @dfn{R documentation} (Rd) format. The " "documentation filenames must start with an @acronym{ASCII} (lower or upper " "case) letter or digit and have the extension @file{.Rd} (the default) or " "@file{.rd}. Further, the names must be valid in @samp{file://} URLs, which " "means@footnote{More precisely, they can contain the English alphanumeric " "characters and the symbols @samp{$ - _ . + ! ' ( ) , ; @ = &}.} they must be " "entirely @acronym{ASCII} and not contain @samp{%}. @xref{Writing R " "documentation files}, for more information. Note that all user-level " "objects in a package should be documented; if a package @var{pkg} contains " "user-level objects which are for ``internal'' use only, it should provide a " "file @file{@var{pkg}-internal.Rd} which documents all such objects, and " "clearly states that these are not meant to be called by the user. See e.g." "@: the sources for package @pkg{grid} in the @R{} distribution. Note that " "packages which use internal objects extensively should not export those " "objects from their namespace, when they do not need to be documented " "(@pxref{Package namespaces})." msgstr "" # #. type: Plain text #: R-exts.texi:1106 msgid "" "Having a @file{man} directory containing no documentation files may give an " "installation error." msgstr "" # #. type: Plain text #: R-exts.texi:1111 msgid "" "The @file{man} subdirectory may contain a subdirectory named @file{macros}; " "this will contain source for user-defined Rd macros. (See @ref{User-defined " "macros}.) These use the Rd format, but may not contain anything but macro " "definitions, comments and whitespace." msgstr "" # #. type: Plain text #: R-exts.texi:1114 msgid "" "The @file{R} and @file{man} subdirectories may contain OS-specific " "subdirectories named @file{unix} or @file{windows}." msgstr "" # #. type: Plain text #: R-exts.texi:1137 msgid "" "The sources and headers for the compiled code are in @file{src}, plus " "optionally a file @file{Makevars} or @file{Makefile}. When a package is " "installed using @code{R CMD INSTALL}, @command{make} is used to control " "compilation and linking into a shared object for loading into @R{}. There " "are default @command{make} variables and rules for this (determined when " "@R{} is configured and recorded in @file{@var{R_HOME}/etc@var{R_ARCH}/" "Makeconf}), providing support for C, C++, FORTRAN 77, Fortran " "9x@footnote{Note that Ratfor is not supported. If you have Ratfor source " "code, you need to convert it to FORTRAN. Only FORTRAN 77 (which we write in " "upper case) is supported on all platforms, but most also support Fortran-95 " "(for which we use title case). If you want to ship Ratfor source files, " "please do so in a subdirectory of @file{src} and not in the main " "subdirectory.}, Objective C and Objective C++@footnote{either or both of " "which may not be supported on particular platforms} with associated " "extensions @file{.c}, @file{.cc} or @file{.cpp}, @file{.f}, @file{.f90} or " "@file{.f95}, @file{.m}, and @file{.mm}, respectively. We recommend using " "@file{.h} for headers, also for C++@footnote{Using @file{.hpp} is not " "guaranteed to be portable.} or Fortran 9x include files. (Use of extension " "@file{.C} for C++ is no longer supported.) Files in the @file{src} " "directory should not be hidden (start with a dot), and hidden files will " "under some versions of @R{} be ignored." msgstr "" # #. type: Plain text #: R-exts.texi:1142 msgid "" "It is not portable (and may not be possible at all) to mix all these " "languages in a single package, and we do not support using both C++ and " "Fortran 9x. Because @R{} itself uses it, we know that C and FORTRAN 77 can " "be used together and mixing C and C++ seems to be widely successful." msgstr "" # #. type: Plain text #: R-exts.texi:1150 msgid "" "If your code needs to depend on the platform there are certain defines which " "can used in C or C++. On all Windows builds (even 64-bit ones) " "@samp{_WIN32} will be defined: on 64-bit Windows builds also @samp{_WIN64}, " "and on OS X @samp{__APPLE__} is defined.@footnote{There is also " "@samp{__APPLE_CC__}, but that indicates a compiler with Apple-specific " "features, not the OS. It is used in @file{Rinlinedfuns.h}.}" msgstr "" # #. type: Plain text #: R-exts.texi:1165 msgid "" "The default rules can be tweaked by setting macros@footnote{the POSIX " "terminology, called `make variables' by GNU make.} in a file @file{src/" "Makevars} (@pxref{Using Makevars}). Note that this mechanism should be " "general enough to eliminate the need for a package-specific @file{src/" "Makefile}. If such a file is to be distributed, considerable care is needed " "to make it general enough to work on all @R{} platforms. If it has any " "targets at all, it should have an appropriate first target named @samp{all} " "and a (possibly empty) target @samp{clean} which removes all files generated " "by running @command{make} (to be used by @samp{R CMD INSTALL --clean} and " "@samp{R CMD INSTALL --preclean}). There are platform-specific file names on " "Windows: @file{src/Makevars.win} takes precedence over @file{src/Makevars} " "and @file{src/Makefile.win} must be used. Some @command{make} programs " "require makefiles to have a complete final line, including a newline." msgstr "" # #. type: Plain text #: R-exts.texi:1170 msgid "" "A few packages use the @file{src} directory for purposes other than making a " "shared object (e.g.@: to create executables). Such packages should have " "files @file{src/Makefile} and @file{src/Makefile.win} (unless intended for " "only Unix-alikes or only Windows)." msgstr "" # #. type: Plain text #: R-exts.texi:1188 msgid "" "In very special cases packages may create binary files other than the shared " "objects/DLLs in the @file{src} directory. Such files will not be installed " "in a multi-architecture setting since @code{R CMD INSTALL --libs-only} is " "used to merge multiple sub-architectures and it only copies shared objects/" "DLLs. If a package wants to install other binaries (for example executable " "programs), it should provide an @R{} script @file{src/install.libs.R} which " "will be run as part of the installation in the @code{src} build directory " "@emph{instead of} copying the shared objects/DLLs. The script is run in a " "separate @R{} environment containing the following variables: " "@code{R_PACKAGE_NAME} (the name of the package), @code{R_PACKAGE_SOURCE} " "(the path to the source directory of the package), @code{R_PACKAGE_DIR} (the " "path of the target installation directory of the package), @code{R_ARCH} " "(the arch-dependent part of the path, often empty), @code{SHLIB_EXT} (the " "extension of shared objects) and @code{WINDOWS} (@code{TRUE} on Windows, " "@code{FALSE} elsewhere). Something close to the default behavior could be " "replicated with the following @file{src/install.libs.R} file:" msgstr "" # #. type: example #: R-exts.texi:1196 #, no-wrap msgid "" "files <- Sys.glob(paste0(\"*\", SHLIB_EXT))\n" "dest <- file.path(R_PACKAGE_DIR, paste0('libs', R_ARCH))\n" "dir.create(dest, recursive = TRUE, showWarnings = FALSE)\n" "file.copy(files, dest, overwrite = TRUE)\n" "if(file.exists(\"symbols.rds\"))\n" " file.copy(\"symbols.rds\", dest, overwrite = TRUE)\n" msgstr "" # #. type: Plain text #: R-exts.texi:1200 msgid "" "On the other hand, executable programs could be installed along the lines of" msgstr "" # #. type: example #: R-exts.texi:1208 #, no-wrap msgid "" "execs <- c(\"one\", \"two\", \"three\")\n" "if(WINDOWS) execs <- paste0(execs, \".exe\")\n" "if ( any(file.exists(execs)) ) @{\n" " dest <- file.path(R_PACKAGE_DIR, paste0('bin', R_ARCH)\n" " dir.create(dest, recursive = TRUE, showWarnings = FALSE)\n" " file.copy(execs, dest, overwrite = TRUE)\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:1213 msgid "" "Note the use of architecture-specific subdirectories of @file{bin} where " "needed." msgstr "" # #. type: Plain text #: R-exts.texi:1215 msgid "" "The @file{data} subdirectory is for data files: @xref{Data in packages}." msgstr "" # #. type: Plain text #: R-exts.texi:1229 msgid "" "The @file{demo} subdirectory is for @R{} scripts (for running @emph{via} " "@code{demo()}) that demonstrate some of the functionality of the package. " "Demos may be interactive and are not checked automatically, so if testing is " "desired use code in the @file{tests} directory to achieve this. The script " "files must start with a (lower or upper case) letter and have one of the " "extensions @file{.R} or @file{.r}. If present, the @file{demo} subdirectory " "should also have a @file{00Index} file with one line for each demo, giving " "its name and a description separated by a tab or at least three spaces. " "(This index file is not generated automatically.) Note that a demo does not " "have a specified encoding and so should be an @acronym{ASCII} file " "(@pxref{Encoding issues}). As from @R{} 3.0.0 @code{demo()} will use the " "package encoding if there is one, but this is mainly useful for non-" "@acronym{ASCII} comments." msgstr "" # #. type: cindex #: R-exts.texi:1230 #, no-wrap msgid ".Rinstignore file" msgstr "" # #. type: Plain text #: R-exts.texi:1245 msgid "" "The contents of the @file{inst} subdirectory will be copied recursively to " "the installation directory. Subdirectories of @file{inst} should not " "interfere with those used by @R{} (currently, @file{R}, @file{data}, " "@file{demo}, @file{exec}, @file{libs}, @file{man}, @file{help}, @file{html} " "and @file{Meta}, and earlier versions used @file{latex}, @file{R-ex}). The " "copying of the @file{inst} happens after @file{src} is built so its " "@file{Makefile} can create files to be installed. To exclude files from " "being installed, one can specify a list of exclude patterns in file @file{." "Rinstignore} in the top-level source directory. These patterns should be " "Perl-like regular expressions (see the help for @code{regexp} in @R{} for " "the precise details), one per line, to be matched case-" "insensitively@footnote{on all platforms from @R{} 3.1.0} against the file " "and directory paths, e.g.@: @file{doc/.*[.]png$} will exclude all PNG files " "in @file{inst/doc} based on the extension." msgstr "" # #. type: Plain text #: R-exts.texi:1255 msgid "" "Note that with the exceptions of @file{INDEX}, @file{LICENSE}/@file{LICENCE} " "and @file{NEWS}, information files at the top level of the package will " "@emph{not} be installed and so not be known to users of Windows and OS X " "compiled packages (and not seen by those who use @command{R CMD INSTALL} or " "@command{install.packages} on the tarball). So any information files you " "wish an end user to see should be included in @file{inst}. Note that if the " "named exceptions also occur in @file{inst}, the version in @file{inst} will " "be that seen in the installed package." msgstr "" # #. type: findex #: R-exts.texi:1256 #: R-exts.texi:4854 #, no-wrap msgid "CITATION" msgstr "" # #. type: cindex #: R-exts.texi:1257 #: R-exts.texi:4855 #, no-wrap msgid "citation" msgstr "" # #. type: findex #: R-exts.texi:1258 #, no-wrap msgid "NEWS.Rd" msgstr "" # #. type: cindex #: R-exts.texi:1259 #, no-wrap msgid "news" msgstr "" #. type: Plain text #: R-exts.texi:1264 msgid "" "Things you might like to add to @file{inst} are a @file{CITATION} file for " "use by the @code{citation} function, and a @file{NEWS.Rd} file for use by " "the @code{news} function. See its help page for the specific format " "restrictions of the @file{NEWS.Rd} file." msgstr "" # #. type: findex #: R-exts.texi:1265 #, no-wrap msgid "AUTHORS" msgstr "" # #. type: Plain text #: R-exts.texi:1270 msgid "" "Another file sometimes needed in @file{inst} is @file{AUTHORS} or " "@file{COPYRIGHTS} to specify the authors or copyright holders when this is " "too complex to put in the @file{DESCRIPTION} file." msgstr "" # #. type: Plain text #: R-exts.texi:1294 msgid "" "Subdirectory @file{tests} is for additional package-specific test code, " "similar to the specific tests that come with the @R{} distribution. Test " "code can either be provided directly in a @file{.R} file, or @emph{via} a " "@file{.Rin} file containing code which in turn creates the corresponding " "@file{.R} file (e.g., by collecting all function objects in the package and " "then calling them with the strangest arguments). The results of running a " "@file{.R} file are written to a @file{.Rout} file. If there is a " "corresponding@footnote{The best way to generate such a file is to copy the " "@file{.Rout} from a successful run of @command{R CMD check}. If you want to " "generate it separately, do run @R{} with options @option{--vanilla --slave} " "and with environment variable @env{LANGUAGE=en} set to get messages in " "English. Be careful not to use output with the option @option{--timings} " "(and note that @option{--as-cran} sets it).} @file{.Rout.save} file, these " "two are compared, with differences being reported but not causing an error. " "The directory @file{tests} is copied to the check area, and the tests are " "run with the copy as the working directory and with @code{R_LIBS} set to " "ensure that the copy of the package installed during testing will be found " "by @code{library(@var{pkg_name})}. Note that the package-specific tests are " "run in a vanilla @R{} session without setting the random-number seed, so " "tests which use random numbers will need to set the seed to obtain " "reproducible results (and it can be helpful to do so in all cases, to avoid " "occasional failures when tests are run)." msgstr "" # #. type: Plain text #: R-exts.texi:1300 msgid "" "If directory @file{tests} has a subdirectory @file{Examples} containing a " "file @code{@var{pkg}-Ex.Rout.save}, this is compared to the output file for " "running the examples when the latter are checked. Reference output should " "be produced without having the @option{--timings} option set (and note that " "@option{--as-cran} sets it)." msgstr "" # #. type: Plain text #: R-exts.texi:1310 msgid "" "Subdirectory @file{exec} could contain additional executable scripts the " "package needs, typically scripts for interpreters such as the shell, Perl, " "or Tcl. NB: only files (and not directories) under @file{exec} are " "installed (and those with names starting with a dot are ignored), and they " "are all marked as executable (mode @code{755}, moderated by @samp{umask}) on " "POSIX platforms. Note too that this is not suitable for executable " "@emph{programs} since some platforms (including Windows) support multiple " "architectures using the same installed package directory." msgstr "" # #. type: Plain text #: R-exts.texi:1313 msgid "" "Subdirectory @file{po} is used for files related to @emph{localization}: " "@pxref{Internationalization}." msgstr "" # #. type: Plain text #: R-exts.texi:1317 msgid "" "Subdirectory @file{tools} is the preferred place for auxiliary files needed " "during configuration, and also for sources need to re-create scripts (e.g.@: " "M4 files for @command{autoconf})." msgstr "" # #. type: Plain text #: R-exts.texi:1328 msgid "" "The @file{data} subdirectory is for data files, either to be made available " "@emph{via} lazy-loading or for loading using @code{data()}. (The choice is " "made by the @samp{LazyData} field in the @file{DESCRIPTION} file: the " "default is not to do so.) It should not be used for other data files needed " "by the package, and the convention has grown up to use directory @file{inst/" "extdata} for such files." msgstr "" #. type: Plain text #: R-exts.texi:1339 msgid "" "Data files can have one of three types as indicated by their extension: " "plain @R{} code (@file{.R} or @file{.r}), tables (@file{.tab}, @file{.txt}, " "or @file{.csv}, see @code{?data} for the file formats, and note that @file{." "csv} is @strong{not} the standard@footnote{e.g.@: @uref{https://tools.ietf." "org/@/html/@/rfc4180}.} CSV format), or @code{save()} images (@file{.RData} " "or @file{.rda}). The files should not be hidden (have names starting with a " "dot). Note that @R{} code should be ``self-sufficient'' and not make use of " "extra functionality provided by the package, so that the data file can also " "be used without having to load the package or its namespace." msgstr "" # #. type: Plain text #: R-exts.texi:1350 msgid "" "Images (extensions @file{.RData}@footnote{People who have trouble with case " "are advised to use @file{.rda} as a common error is to refer to @file{abc." "RData} as @file{abc.Rdata}!} or @file{.rda}) can contain references to the " "namespaces of packages that were used to create them. Preferably there " "should be no such references in data files, and in any case they should only " "be to packages listed in the @code{Depends} and @code{Imports} fields, as " "otherwise it may be impossible to install the package. To check for such " "references, load all the images into a vanilla @R{} session, and look at the " "output of @code{loadedNamespaces()}." msgstr "" # #. type: Plain text #: R-exts.texi:1359 msgid "" "If your data files are large and you are not using @samp{LazyData} you can " "speed up installation by providing a file @file{datalist} in the @file{data} " "subdirectory. This should have one line per topic that @code{data()} will " "find, in the format @samp{foo} if @code{data(foo)} provides @samp{foo}, or " "@samp{foo: bar bah} if @code{data(foo)} provides @samp{bar} and @samp{bah}. " "@command{R CMD build} will automatically add a @file{datalist} file to " "@file{data} directories of over 1Mb, using the function @code{tools::" "add_datalist}." msgstr "" # #. type: Plain text #: R-exts.texi:1364 msgid "" "Tables (@file{.tab}, @file{.txt}, or @file{.csv} files) can be compressed by " "@command{gzip}, @command{bzip2} or @command{xz}, optionally with additional " "extension @file{.gz}, @file{.bz2} or @file{.xz}." msgstr "" # #. type: Plain text #: R-exts.texi:1373 msgid "" "If your package is to be distributed, do consider the resource implications " "of large datasets for your users: they can make packages very slow to " "download and use up unwelcome amounts of storage space, as well as taking " "many seconds to load. It is normally best to distribute large datasets as " "@file{.rda} images prepared by @code{save(, compress = TRUE)} (the " "default). Using @command{bzip2} or @command{xz} compression will usually " "reduce the size of both the package tarball and the installed package, in " "some cases by a factor of two or more." msgstr "" # #. type: Plain text #: R-exts.texi:1378 msgid "" "Package @pkg{tools} has a couple of functions to help with data images: " "@code{checkRdaFiles} reports on the way the image was saved, and " "@code{resaveRdaFiles} will re-save with a different type of compression, " "including choosing the best type for that particular image." msgstr "" # #. type: Plain text #: R-exts.texi:1388 msgid "" "Some packages using @samp{LazyData} will benefit from using a form of " "compression other than @command{gzip} in the installed lazy-loading " "database. This can be selected by the @option{--data-compress} option to " "@command{R CMD INSTALL} or by using the @samp{LazyDataCompression} field in " "the @file{DESCRIPTION} file. Useful values are @code{bzip2}, @code{xz} and " "the default, @code{gzip}. The only way to discover which is best is to try " "them all and look at the size of the @file{@var{pkgname}/data/Rdata.rdb} " "file." msgstr "" # #. type: Plain text #: R-exts.texi:1392 msgid "" "Lazy-loading is not supported for very large datasets (those which when " "serialized exceed 2GB, the limit for the format on 32-bit platforms and all " "platforms prior to @R{} 3.0.0)." msgstr "" # #. type: Plain text #: R-exts.texi:1397 msgid "" "The analogue for @file{sysdata.rda} is field @samp{SysDataCompression}: the " "default (since @R{} 2.12.2) is @code{xz} for files bigger than 1MB otherwise " "@code{gzip}." msgstr "" # #. type: Plain text #: R-exts.texi:1404 msgid "" "Code which needs to be compiled (C, C++, FORTRAN, Fortran 95 @dots{}) is " "included in the @file{src} subdirectory and discussed elsewhere in this " "document." msgstr "" # #. type: Plain text #: R-exts.texi:1412 msgid "" "Subdirectory @file{exec} could be used for scripts for interpreters such as " "the shell, BUGS, JavaScript, Matlab, Perl, php (@CRANpkg{amap}), Python or " "Tcl (@CRANpkg{Simile}), or even @R{}. However, it seems more common to use " "the @file{inst} directory, for example @file{WriteXLS/inst/Perl}, @file{NMF/" "inst/m-files}, @file{RnavGraph/inst/tcl}, @file{RProtoBuf/inst/python} and " "@file{emdbook/inst/BUGS} and @file{gridSVG/inst/js}." msgstr "" # #. type: Plain text #: R-exts.texi:1420 msgid "" "Java code is a special case: except for very small programs, @file{.java} " "files should be byte-compiled (to a @file{.class} file) and distributed as " "part of a @file{.jar} file: the conventional location for the @file{.jar} " "file(s) is @file{inst/java}. It is desirable (and required under an Open " "Source license) to make the Java source files available: this is best done " "in a top-level @file{java} directory in the package---the source files " "should not be installed." msgstr "" # #. type: Plain text #: R-exts.texi:1425 msgid "" "If your package requires one of these interpreters or an extension then this " "should be declared in the @samp{SystemRequirements} field of its " "@file{DESCRIPTION} file. (Users of Java most often do so @emph{via} " "@CRANpkg{rJava}, when depending on/importing that suffices.)" msgstr "" #. type: Plain text #: R-exts.texi:1433 msgid "" "Windows and Mac users should be aware that the Tcl extensions @samp{BWidget} " "and @samp{Tktable} which are currently included with the @R{} for Windows " "and in the OS X installers @emph{are} extensions and do need to be declared " "for users of other platforms (and that @samp{Tktable} is less widely " "available than it used to be, including not in the main repositories for " "major Linux distributions)." msgstr "" #. type: Plain text #: R-exts.texi:1436 msgid "" "@samp{BWidget} needs to be installed by the user on other OSes. This is " "fairly easy to do: first find the Tcl/Tk search path:" msgstr "" # #. type: example #: R-exts.texi:1440 #, no-wrap msgid "" "library(tcltk)\n" "strsplit(tclvalue('auto_path'), \" \")[[1]]\n" msgstr "" #. type: Plain text #: R-exts.texi:1446 msgid "" "then download the sources from @uref{http://sourceforge.net/@/projects/@/" "tcllib/@/files/@/BWidget/} and at the command line run something like" msgstr "" #. type: example #: R-exts.texi:1450 #, no-wrap msgid "" "tar xf bwidget-1.9.8.tar.gz\n" "sudo mv bwidget-1.9.8 /usr/local/lib\n" msgstr "" # #. type: Plain text #: R-exts.texi:1455 msgid "" "substituting a location on the Tcl/Tk search path for @file{/usr/local/lib} " "if needed." msgstr "" #. type: Plain text #: R-exts.texi:1462 msgid "" "URLs in many places in the package documentation will be converted to " "clickable hyperlinks in at least some of their renderings. So care is " "needed that their forms are correct and portable." msgstr "" #. type: Plain text #: R-exts.texi:1465 msgid "" "The full URL should be given, including the scheme (often @samp{http://} or " "@samp{https://}) and a final @samp{/} for references to directories." msgstr "" #. type: Plain text #: R-exts.texi:1470 msgid "" "Spaces in URLs are not portable and how they are handled does vary by HTTP " "server and by client. There should be no space in the host part of an " "@samp{http://} URL, and spaces in the remainder should be encoded, with each " "space replaced by @samp{%20}." msgstr "" #. type: Plain text #: R-exts.texi:1473 msgid "" "Other characters may benefit from being encoded: see the help on " "@code{URLencode()}." msgstr "" #. type: Plain text #: R-exts.texi:1475 msgid "The canonical URL for a @acronym{CRAN} package is" msgstr "" #. type: example #: R-exts.texi:1477 #, no-wrap msgid "https://cran.r-project.org/package=@var{pkgname}\n" msgstr "" #. type: Plain text #: R-exts.texi:1482 msgid "" "and not a version starting @samp{http://cran.r-project.org/web/packages/" "@var{pkgname}}." msgstr "" # #. type: Plain text #: R-exts.texi:1488 msgid "" "Note that most of this section is specific to Unix-alikes: see the comments " "later on about the Windows port of @R{}." msgstr "" # #. type: Plain text #: R-exts.texi:1500 msgid "" "If your package needs some system-dependent configuration before " "installation you can include an executable (Bourne shell) script " "@file{configure} in your package which (if present) is executed by @code{R " "CMD INSTALL} before any other action is performed. This can be a script " "created by the Autoconf mechanism, but may also be a script written by " "yourself. Use this to detect if any nonstandard libraries are present such " "that corresponding code in the package can be disabled at install time " "rather than giving error messages when the package is compiled or used. To " "summarize, the full power of Autoconf is available for your extension " "package (including variable substitution, searching for libraries, etc.)." msgstr "" # #. type: Plain text #: R-exts.texi:1505 msgid "" "Under a Unix-alike only, an executable (Bourne shell) script @file{cleanup} " "is executed as the last thing by @code{R CMD INSTALL} if option @option{--" "clean} was given, and by @code{R CMD build} when preparing the package for " "building from its source." msgstr "" # #. type: Plain text #: R-exts.texi:1515 msgid "" "As an example consider we want to use functionality provided by a (C or " "FORTRAN) library @code{foo}. Using Autoconf, we can create a configure " "script which checks for the library, sets variable @code{HAVE_FOO} to " "@code{TRUE} if it was found and to @code{FALSE} otherwise, and then " "substitutes this value into output files (by replacing instances of " "@samp{@@HAVE_FOO@@} in input files with the value of @code{HAVE_FOO}). For " "example, if a function named @code{bar} is to be made available by linking " "against library @code{foo} (i.e., using @option{-lfoo}), one could use" msgstr "" # #. type: group #: R-exts.texi:1523 #, no-wrap msgid "" "AC_CHECK_LIB(foo, @var{fun}, [HAVE_FOO=TRUE], [HAVE_FOO=FALSE])\n" "AC_SUBST(HAVE_FOO)\n" "......\n" "AC_CONFIG_FILES([foo.R])\n" "AC_OUTPUT\n" msgstr "" # #. type: Plain text #: R-exts.texi:1528 msgid "in @file{configure.ac} (assuming Autoconf 2.50 or later)." msgstr "" # #. type: Plain text #: R-exts.texi:1530 msgid "" "The definition of the respective @R{} function in @file{foo.R.in} could be" msgstr "" # #. type: group #: R-exts.texi:1537 #, no-wrap msgid "" "foo <- function(x) @{\n" " if(!@@HAVE_FOO@@)\n" " stop(\"Sorry, library 'foo' is not available\"))\n" " ...\n" msgstr "" # #. type: Plain text #: R-exts.texi:1543 msgid "" "From this file @command{configure} creates the actual @R{} source file " "@file{foo.R} looking like" msgstr "" # #. type: group #: R-exts.texi:1550 #, no-wrap msgid "" "foo <- function(x) @{\n" " if(!FALSE)\n" " stop(\"Sorry, library 'foo' is not available\"))\n" " ...\n" msgstr "" # #. type: Plain text #: R-exts.texi:1556 msgid "" "if library @code{foo} was not found (with the desired functionality). In " "this case, the above @R{} code effectively disables the function." msgstr "" # #. type: Plain text #: R-exts.texi:1559 msgid "" "One could also use different file fragments for available and missing " "functionality, respectively." msgstr "" # #. type: Plain text #: R-exts.texi:1564 msgid "" "You will very likely need to ensure that the same C compiler and compiler " "flags are used in the @file{configure} tests as when compiling @R{} or your " "package. Under a Unix-alike, you can achieve this by including the " "following fragment early in @file{configure.ac}" msgstr "" # #. type: group #: R-exts.texi:1575 #, no-wrap msgid "" ": $@{R_HOME=`R RHOME`@}\n" "if test -z \"$@{R_HOME@}\"; then\n" " echo \"could not determine R_HOME\"\n" " exit 1\n" "fi\n" "CC=`\"$@{R_HOME@}/bin/R\" CMD config CC`\n" "CFLAGS=`\"$@{R_HOME@}/bin/R\" CMD config CFLAGS`\n" "CPPFLAGS=`\"$@{R_HOME@}/bin/R\" CMD config CPPFLAGS`\n" msgstr "" # #. type: Plain text #: R-exts.texi:1583 msgid "" "(Using @samp{$@{R_HOME@}/bin/R} rather than just @samp{R} is necessary in " "order to use the correct version of @R{} when running the script as part of " "@code{R CMD INSTALL}, and the quotes since @samp{$@{R_HOME@}} might contain " "spaces.)" msgstr "" # #. type: Plain text #: R-exts.texi:1585 msgid "If your code does load checks then you may also need" msgstr "" # #. type: example #: R-exts.texi:1587 #, no-wrap msgid "LDFLAGS=`\"$@{R_HOME@}/bin/R\" CMD config LDFLAGS`\n" msgstr "" # #. type: Plain text #: R-exts.texi:1592 msgid "" "and packages written with C++ need to pick up the details for the C++ " "compiler and switch the current language to C++ by" msgstr "" # #. type: example #: R-exts.texi:1594 #, no-wrap msgid "AC_LANG(C++)\n" msgstr "" # #. type: Plain text #: R-exts.texi:1599 msgid "" "The latter is important, as for example C headers may not be available to C+" "+ programs or may not be written to avoid C++ name-mangling." msgstr "" # #. type: findex #: R-exts.texi:1600 #, no-wrap msgid "R CMD config" msgstr "" # #. type: Plain text #: R-exts.texi:1605 msgid "" "You can use @code{R CMD config} for getting the value of the basic " "configuration variables, and also the header and library flags necessary for " "linking a front-end executable program against @R{}, see @kbd{R CMD config --" "help} for details." msgstr "" # #. type: Plain text #: R-exts.texi:1608 msgid "" "To check for an external BLAS library using the @code{ACX_BLAS} macro from " "the official Autoconf Macro Archive, one can simply do" msgstr "" # #. type: group #: R-exts.texi:1615 #, no-wrap msgid "" "F77=`\"$@{R_HOME@}/bin/R\" CMD config F77`\n" "AC_PROG_F77\n" "FLIBS=`\"$@{R_HOME@}/bin/R\" CMD config FLIBS`\n" "ACX_BLAS([], AC_MSG_ERROR([could not find your BLAS library], 1))\n" msgstr "" # #. type: Plain text #: R-exts.texi:1624 msgid "" "Note that @code{FLIBS} as determined by @R{} must be used to ensure that " "FORTRAN 77 code works on all @R{} platforms. Calls to the Autoconf macro " "@code{AC_F77_LIBRARY_LDFLAGS}, which would overwrite @code{FLIBS}, must not " "be used (and hence e.g.@: removed from @code{ACX_BLAS}). (Recent versions " "of Autoconf in fact allow an already set @code{FLIBS} to override the test " "for the FORTRAN linker flags.)" msgstr "" # #. type: Plain text #: R-exts.texi:1631 msgid "" "@strong{N.B.}: If the @command{configure} script creates files, e.g.@: " "@file{src/Makevars}, you do need a @command{cleanup} script to remove them. " "Otherwise if the package has vignettes, @command{R CMD build} will ship the " "files that are created. For example, package @CRANpkg{RODBC} has" msgstr "" # #. type: example #: R-exts.texi:1634 #, no-wrap msgid "" "#!/bin/sh\n" "\n" msgstr "" # #. type: example #: R-exts.texi:1636 #, no-wrap msgid "rm -f config.* src/Makevars src/config.h\n" msgstr "" # #. type: Plain text #: R-exts.texi:1641 msgid "" "As this example shows, @command{configure} often creates working files such " "as @file{config.log}." msgstr "" # #. type: Plain text #: R-exts.texi:1644 msgid "" "If your configure script needs auxiliary files, it is recommended that you " "ship them in a @file{tools} directory (as @R{} itself does)." msgstr "" # #. type: Plain text #: R-exts.texi:1659 msgid "" "You should bear in mind that the configure script will not be used on " "Windows systems. If your package is to be made publicly available, please " "give enough information for a user on a non-Unix-alike platform to configure " "it manually, or provide a @file{configure.win} script to be used on that " "platform. (Optionally, there can be a @file{cleanup.win} script. Both " "should be shell scripts to be executed by @command{ash}, which is a minimal " "version of Bourne-style @command{sh}.) When @file{configure.win} is run the " "environment variables @env{R_HOME} (which uses @samp{/} as the file " "separator), @env{R_ARCH} and Use @env{R_ARCH_BIN} will be set. Use " "@env{R_ARCH} to decide if this is a 64-bit build (its value there is @samp{/" "x64}) and to install DLLs to the correct place (@file{$@{R_HOME@}/libs" "$@{R_ARCH@}}). Use @env{R_ARCH_BIN} to find the correct place under the " "@file{bin} directory, e.g.@: @file{$@{R_HOME@}/bin$@{R_ARCH_BIN@}/Rscript." "exe}." msgstr "" # #. type: Plain text #: R-exts.texi:1673 msgid "" "In some rare circumstances, the configuration and cleanup scripts need to " "know the location into which the package is being installed. An example of " "this is a package that uses C code and creates two shared object/DLLs. " "Usually, the object that is dynamically loaded by @R{} is linked against the " "second, dependent, object. On some systems, we can add the location of this " "dependent object to the object that is dynamically loaded by @R{}. This " "means that each user does not have to set the value of the " "@env{LD_LIBRARY_PATH} (or equivalent) environment variable, but that the " "secondary object is automatically resolved. Another example is when a " "package installs support files that are required at run time, and their " "location is substituted into an @R{} data structure at installation time. " "(This happens with the Java Archive files in the Omegahat @pkg{SJava} " "package.)" msgstr "" # #. type: vindex #: R-exts.texi:1673 #, no-wrap msgid "R_LIBRARY_DIR" msgstr "" # #. type: vindex #: R-exts.texi:1674 #, no-wrap msgid "R_PACKAGE_DIR" msgstr "" # #. type: vindex #: R-exts.texi:1675 #, no-wrap msgid "R_PACKAGE_NAME" msgstr "" # #. type: Plain text #: R-exts.texi:1689 msgid "" "The names of the top-level library directory (i.e., specifiable @emph{via} " "the @samp{-l} argument) and the directory of the package itself are made " "available to the installation scripts @emph{via} the two shell/environment " "variables @env{R_LIBRARY_DIR} and @env{R_PACKAGE_DIR}. Additionally, the " "name of the package (e.g.@: @samp{survival} or @samp{MASS}) being installed " "is available from the environment variable @env{R_PACKAGE_NAME}. (Currently " "the value of @env{R_PACKAGE_DIR} is always @code{$@{R_LIBRARY_DIR@}/" "$@{R_PACKAGE_NAME@}}, but this used not to be the case when versioned " "installs were allowed. Its main use is in @file{configure.win} scripts for " "the installation path of external software's DLLs.) Note that the value of " "@env{R_PACKAGE_DIR} may contain spaces and other shell-unfriendly " "characters, and so should be quoted in makefiles and configure scripts." msgstr "" # #. type: Plain text #: R-exts.texi:1698 msgid "" "One of the more tricky tasks can be to find the headers and libraries of " "external software. One tool which is increasingly available on Unix-alikes " "(but not by default on OS X) to do this is @command{pkg-config}. The " "@file{configure} script will need to test for the presence of the command " "itself (see for example package @CRANpkg{Cairo}), and if present it can be " "asked if the software is installed, of a suitable version and for " "compilation/linking flags by e.g.@:" msgstr "" # #. type: example #: R-exts.texi:1707 #, no-wrap msgid "" "$ pkg-config --exists 'QtCore >= 4.0.0' # check the status\n" "$ pkg-config --modversion QtCore\n" "4.7.1\n" "$ pkg-config --cflags QtCore\n" "-DQT_SHARED -I/usr/include/QtCore\n" "$ pkg-config --libs QtCore\n" "-lQtCore\n" msgstr "" # #. type: Plain text #: R-exts.texi:1714 msgid "" "Note that @command{pkg-config --libs} gives the information required to link " "against the default version of that library (usually the dynamic one), and " "@command{pkg-config --static} is needed if the static library is to be used." msgstr "" # #. type: Plain text #: R-exts.texi:1718 msgid "" "Sometimes the name by which the software is known to @command{pkg-config} is " "not what one might expect (e.g.@: @samp{gtk+-2.0} even for 2.22). To get a " "complete list use" msgstr "" # #. type: example #: R-exts.texi:1721 #, no-wrap msgid "pkg-config --list-all | sort\n" msgstr "" # #. type: node #: R-exts.texi:1728 #: R-exts.texi:1730 #: R-exts.texi:1993 #: R-exts.texi:2094 #: R-exts.texi:2146 #: R-exts.texi:2204 #, no-wrap msgid "Using Makevars" msgstr "" # #. type: node #: R-exts.texi:1728 #: R-exts.texi:1730 #: R-exts.texi:2204 #: R-exts.texi:2205 #: R-exts.texi:2339 #, no-wrap msgid "Configure example" msgstr "" # #. type: node #: R-exts.texi:1728 #: R-exts.texi:2204 #: R-exts.texi:2339 #: R-exts.texi:2340 #: R-exts.texi:2392 #, no-wrap msgid "Using F95 code" msgstr "" # #. type: subsection #: R-exts.texi:1728 #: R-exts.texi:2339 #: R-exts.texi:2392 #: R-exts.texi:2393 #, no-wrap msgid "Using C++11 code" msgstr "" # #. type: subsection #: R-exts.texi:1731 #, no-wrap msgid "Using @file{Makevars}" msgstr "" # #. type: node #: R-exts.texi:1737 #: R-exts.texi:1993 #: R-exts.texi:1994 #: R-exts.texi:2094 #, no-wrap msgid "OpenMP support" msgstr "" # #. type: node #: R-exts.texi:1737 #: R-exts.texi:1993 #: R-exts.texi:2094 #: R-exts.texi:2095 #: R-exts.texi:2146 #, no-wrap msgid "Using pthreads" msgstr "" # #. type: subsubsection #: R-exts.texi:1737 #: R-exts.texi:2094 #: R-exts.texi:2146 #: R-exts.texi:2147 #, no-wrap msgid "Compiling in sub-directories" msgstr "" # #. type: Plain text #: R-exts.texi:1743 msgid "" "Sometimes writing your own @file{configure} script can be avoided by " "supplying a file @file{Makevars}: also one of the most common uses of a " "@file{configure} script is to make @file{Makevars} from @file{Makevars.in}." msgstr "" # #. type: Plain text #: R-exts.texi:1749 msgid "" "A @file{Makevars} file is a makefile and is used as one of several makefiles " "by @command{R CMD SHLIB} (which is called by @command{R CMD INSTALL} to " "compile code in the @file{src} directory). It should be written if at all " "possible in a portable style, in particular (except for @file{Makevars.win}) " "without the use of GNU extensions." msgstr "" # #. type: Plain text #: R-exts.texi:1756 msgid "" "The most common use of a @file{Makevars} file is to set additional " "preprocessor options (for example include paths) for C/C++ files @emph{via} " "@code{PKG_CPPFLAGS}, and additional compiler flags by setting " "@code{PKG_CFLAGS}, @code{PKG_CXXFLAGS}, @code{PKG_FFLAGS} or " "@code{PKG_FCFLAGS}, for C, C++, FORTRAN or Fortran 9x respectively " "(@pxref{Creating shared objects})." msgstr "" # #. type: Plain text #: R-exts.texi:1761 msgid "" "@strong{N.B.}: Include paths are preprocessor options, not compiler options, " "and @strong{must} be set in @code{PKG_CPPFLAGS} as otherwise platform-" "specific paths (e.g.@: @samp{-I/usr/local/include}) will take precedence." msgstr "" # #. type: Plain text #: R-exts.texi:1764 msgid "" "@file{Makevars} can also be used to set flags for the linker, for example " "@samp{-L} and @samp{-l} options, @emph{via} @code{PKG_LIBS}." msgstr "" # #. type: Plain text #: R-exts.texi:1770 msgid "" "When writing a @file{Makevars} file for a package you intend to distribute, " "take care to ensure that it is not specific to your compiler: flags such as " "@option{-O2 -Wall -pedantic} (and all other @option{-W} flags: for the " "Solaris compiler these are used to pass arguments to compiler phases) are " "all specific to GCC." msgstr "" # #. type: Plain text #: R-exts.texi:1774 msgid "" "Also, do not set variables such as @code{CPPFLAGS}, @code{CFLAGS} etc.: " "these should be settable by users (sites) through appropriate personal (site-" "wide) @file{Makevars} files." msgstr "" # #. type: ifset #: R-exts.texi:1777 #: R-exts.texi:4054 #: R-exts.texi:9048 msgid "" "@xref{Customizing package compilation, , Customizing package compilation, R-" "admin, R Installation and Administration}," msgstr "" # #. type: Plain text #: R-exts.texi:1786 msgid "" "There are some macros@footnote{in POSIX parlance: GNU @command{make} calls " "these `make variables'.} which are set whilst configuring the building of " "@R{} itself and are stored in @file{@var{R_HOME}/etc@var{R_ARCH}/Makeconf}. " "That makefile is included as a @file{Makefile} @emph{after} @file{Makevars[." "win]}, and the macros it defines can be used in macro assignments and make " "command lines in the latter. These include" msgstr "" # #. type: vindex #: R-exts.texi:1788 #: R-exts.texi:1789 #, no-wrap msgid "FLIBS" msgstr "" # #. type: table #: R-exts.texi:1793 msgid "" "A macro containing the set of libraries need to link FORTRAN code. This may " "need to be included in @code{PKG_LIBS}: it will normally be included " "automatically if the package contains FORTRAN source files." msgstr "" # #. type: vindex #: R-exts.texi:1794 #: R-exts.texi:1795 #, no-wrap msgid "BLAS_LIBS" msgstr "" # #. type: table #: R-exts.texi:1805 msgid "" "A macro containing the BLAS libraries used when building @R{}. This may " "need to be included in @code{PKG_LIBS}. Beware that if it is empty then the " "@R{} executable will contain all the double-precision and double-complex " "BLAS routines, but no single-precision nor complex routines. If " "@code{BLAS_LIBS} is included, then @code{FLIBS} also needs to be@footnote{at " "least on Unix-alikes: the Windows build currently resolves such dependencies " "to a static FORTRAN library when @file{Rblas.dll} is built.} included " "following it, as most BLAS libraries are written at least partially in " "FORTRAN." msgstr "" # #. type: vindex #: R-exts.texi:1806 #: R-exts.texi:1807 #, no-wrap msgid "LAPACK_LIBS" msgstr "" # #. type: table #: R-exts.texi:1815 msgid "" "A macro containing the LAPACK libraries (and paths where appropriate) used " "when building @R{}. This may need to be included in @code{PKG_LIBS}. It " "may point to a dynamic library @code{libRlapack} which contains the main " "double-precision LAPACK routines as well as those double-complex LAPACK " "routines needed to build @R{}, or it may point to an external LAPACK " "library, or may be empty if an external BLAS library also contains LAPACK." msgstr "" # #. type: table #: R-exts.texi:1819 msgid "" "[@code{libRlapack} includes all the double-precision LAPACK routines current " "in 2003: a list of which routines are included is in file @file{src/modules/" "lapack/README}.]" msgstr "" # #. type: table #: R-exts.texi:1822 msgid "" "For portability, the macros @code{BLAS_LIBS} and @code{FLIBS} should always " "be included @emph{after} @code{LAPACK_LIBS} (and in that order)." msgstr "" # #. type: vindex #: R-exts.texi:1823 #: R-exts.texi:1824 #, no-wrap msgid "SAFE_FFLAGS" msgstr "" # #. type: table #: R-exts.texi:1833 msgid "" "A macro containing flags which are needed to circumvent over-optimization of " "FORTRAN code: it is typically @samp{-g -O2 -ffloat-store} on @cputype{ix86} " "platforms using @command{gfortran}. Note that this is @strong{not} an " "additional flag to be used as part of @code{PKG_FFLAGS}, but a replacement " "for @code{FFLAGS}, and that it is intended for the FORTRAN 77 compiler " "@samp{F77} and not necessarily for the Fortran 90/95 compiler @samp{FC}. " "See the example later in this section." msgstr "" # #. type: vindex #: R-exts.texi:1835 #: R-exts.texi:9028 #, no-wrap msgid "OBJECTS" msgstr "" # #. type: Plain text #: R-exts.texi:1844 msgid "" "Setting certain macros in @file{Makevars} will prevent @command{R CMD SHLIB} " "setting them: in particular if @file{Makevars} sets @samp{OBJECTS} it will " "not be set on the @command{make} command line. This can be useful in " "conjunction with implicit rules to allow other types of source code to be " "compiled and included in the shared object. It can also be used to control " "the set of files which are compiled, either by excluding some files in " "@file{src} or including some files in subdirectories. For example" msgstr "" # #. type: example #: R-exts.texi:1847 #, no-wrap msgid "OBJECTS = 4dfp/endianio.o 4dfp/Getifh.o R4dfp-object.o\n" msgstr "" # #. type: Plain text #: R-exts.texi:1856 msgid "" "Note that @file{Makevars} should not normally contain targets, as it is " "included before the default makefile and @command{make} will call the first " "target, intended to be @code{all} in the default makefile. If you really " "need to circumvent that, use a suitable (phony) target @code{all} before any " "actual targets in @file{Makevars.[win]}: for example package " "@CRANpkg{fastICA} used to have" msgstr "" # #. type: example #: R-exts.texi:1859 #, no-wrap msgid "" "PKG_LIBS = @@BLAS_LIBS@@\n" "\n" msgstr "" # #. type: example #: R-exts.texi:1861 #, no-wrap msgid "" "SLAMC_FFLAGS=$(R_XTRA_FFLAGS) $(FPICFLAGS) $(SHLIB_FFLAGS) $(SAFE_FFLAGS)\n" "\n" msgstr "" # #. type: example #: R-exts.texi:1863 #: R-exts.texi:1874 #, no-wrap msgid "" "all: $(SHLIB)\n" "\n" msgstr "" # #. type: example #: R-exts.texi:1866 #, no-wrap msgid "" "slamc.o: slamc.f\n" "\t$(F77) $(SLAMC_FFLAGS) -c -o slamc.o slamc.f\n" msgstr "" # #. type: Plain text #: R-exts.texi:1871 msgid "" "needed to ensure that the LAPACK routines find some constants without " "infinite looping. The Windows equivalent was" msgstr "" # #. type: example #: R-exts.texi:1877 #, no-wrap msgid "" "slamc.o: slamc.f\n" "\t$(F77) $(SAFE_FFLAGS) -c -o slamc.o slamc.f\n" msgstr "" # #. type: Plain text #: R-exts.texi:1884 msgid "" "(since the other macros are all empty on that platform, and @R{}'s internal " "BLAS was not used). Note that the first target in @file{Makevars} will be " "called, but for back-compatibility it is best named @code{all}." msgstr "" # #. type: Plain text #: R-exts.texi:1887 msgid "" "If you want to create and then link to a library, say using code in a " "subdirectory, use something like" msgstr "" # #. type: example #: R-exts.texi:1890 #, no-wrap msgid "" ".PHONY: all mylibs\n" "\n" msgstr "" # #. type: example #: R-exts.texi:1893 #, no-wrap msgid "" "all: $(SHLIB)\n" "$(SHLIB): mylibs\n" "\n" msgstr "" # #. type: example #: R-exts.texi:1896 #, no-wrap msgid "" "mylibs:\n" "\t(cd subdir; make)\n" msgstr "" # #. type: Plain text #: R-exts.texi:1903 msgid "" "Be careful to create all the necessary dependencies, as there is a no " "guarantee that the dependencies of @code{all} will be run in a particular " "order (and some of the @acronym{CRAN} build machines use multiple CPUs and " "parallel makes)." msgstr "" # #. type: Plain text #: R-exts.texi:1909 msgid "" "Note that on Windows it is required that @file{Makevars[.win]} does create a " "DLL: this is needed as it is the only reliable way to ensure that building a " "DLL succeeded. If you want to use the @file{src} directory for some purpose " "other than building a DLL, use a @file{Makefile.win} file." msgstr "" # #. type: Plain text #: R-exts.texi:1918 msgid "" "It is sometimes useful to have a target @samp{clean} in @file{Makevars} or " "@file{Makevars.win}: this will be used by @command{R CMD build} to clean up " "(a copy of) the package sources. When it is run by @command{build} it will " "have fewer macros set, in particular not @code{$(SHLIB)}, nor " "@code{$(OBJECTS)} unless set in the file itself. It would also be possible " "to add tasks to the target @samp{shlib-clean} which is run by @command{R CMD " "INSTALL} and @command{R CMD SHLIB} with options @option{--clean} and " "@option{--preclean}." msgstr "" # #. type: Plain text #: R-exts.texi:1924 msgid "" "If you want to run @R{} code in @file{Makevars}, e.g.@: to find " "configuration information, please do ensure that you use the correct copy of " "@code{R} or @code{Rscript}: there might not be one in the path at all, or it " "might be the wrong version or architecture. The correct way to do this is " "@emph{via}" msgstr "" # #. type: example #: R-exts.texi:1928 #, no-wrap msgid "" "\"$(R_HOME)/bin$(R_ARCH_BIN)/Rscript\" @var{filename}\n" "\"$(R_HOME)/bin$(R_ARCH_BIN)/Rscript\" -e '@var{R expression}'\n" msgstr "" # #. type: Plain text #: R-exts.texi:1932 msgid "where @code{$(R_ARCH_BIN)} is only needed currently on Windows." msgstr "" # #. type: Plain text #: R-exts.texi:1936 msgid "" "Environment or make variables can be used to select different macros for 32- " "and 64-bit code, for example (GNU @command{make} syntax, allowed on Windows)" msgstr "" # #. type: example #: R-exts.texi:1943 #, no-wrap msgid "" "ifeq \"$(WIN)\" \"64\"\n" "PKG_LIBS = @var{value for 64-bit Windows}\n" "else\n" "PKG_LIBS = @var{value for 32-bit Windows}\n" "endif\n" msgstr "" # #. type: Plain text #: R-exts.texi:1950 msgid "" "On Windows there is normally a choice between linking to an import library " "or directly to a DLL. Where possible, the latter is much more reliable: " "import libraries are tied to a specific toolchain, and in particular on 64-" "bit Windows two different conventions have been commonly used. So for " "example instead of" msgstr "" # #. type: example #: R-exts.texi:1953 #, no-wrap msgid "PKG_LIBS = -L$(XML_DIR)/lib -lxml2\n" msgstr "" # #. type: Plain text #: R-exts.texi:1957 msgid "one can use" msgstr "" # #. type: example #: R-exts.texi:1960 #, no-wrap msgid "PKG_LIBS = -L$(XML_DIR)/bin -lxml2\n" msgstr "" # #. type: Plain text #: R-exts.texi:1964 msgid "since on Windows @code{-lxxx} will look in turn for" msgstr "" # #. type: example #: R-exts.texi:1972 #, no-wrap msgid "" "libxxx.dll.a\n" "xxx.dll.a\n" "libxxx.a\n" "xxx.lib\n" "libxxx.dll\n" "xxx.dll\n" msgstr "" #. type: Plain text #: R-exts.texi:1979 msgid "" "where the first and second are conventionally import libraries, the third " "and fourth often static libraries (with @code{.lib} intended for Visual C+" "+), but might be import libraries. See for example @uref{https://sourceware." "org/@/binutils/@/docs-2.20/@/ld/@/WIN32.html#WIN32}." msgstr "" # #. type: Plain text #: R-exts.texi:1985 msgid "" "The fly in the ointment is that the DLL might not be named @file{libxxx." "dll}, and in fact on 32-bit Windows there is a @file{libxml2.dll} whereas on " "one build for 64-bit Windows the DLL is called @file{libxml2-2.dll}. Using " "import libraries can cover over these differences but can cause equal " "difficulties." msgstr "" # #. type: Plain text #: R-exts.texi:1992 msgid "" "If static libraries are available they can save a lot of problems with run-" "time finding of DLLs, especially when binary packages are to be distributed " "and even more when these support both architectures. Where using DLLs is " "unavoidable we normally arrange (@emph{via} @file{configure.win}) to ship " "them in the same directory as the package DLL." msgstr "" # #. type: cindex #: R-exts.texi:1996 #: R-exts.texi:12614 #, no-wrap msgid "OpenMP" msgstr "" #. type: Plain text #: R-exts.texi:2003 msgid "" "There is some support for packages which wish to use " "OpenMP@footnote{@uref{http://www.openmp.org/}, @uref{https://en.wikipedia." "org/@/wiki/@/OpenMP}, @uref{https://computing.llnl.gov/@/tutorials/@/" "openMP/}}. The @command{make} macros" msgstr "" #. type: example #: R-exts.texi:2009 #, no-wrap msgid "" "SHLIB_OPENMP_CFLAGS\n" "SHLIB_OPENMP_CXXFLAGS\n" "SHLIB_OPENMP_FCFLAGS\n" "SHLIB_OPENMP_FFLAGS\n" msgstr "" #. type: Plain text #: R-exts.texi:2020 msgid "" "are available for use in @file{src/Makevars} or @file{src/Makevars.win}. " "Include the appropriate macro in @code{PKG_CFLAGS}, @code{PKG_CPPFLAGS} and " "so on, and also in @code{PKG_LIBS}. C/C++ code that needs to be conditioned " "on the use of OpenMP can be used inside @code{#ifdef _OPENMP}: note that " "some toolchains used for @R{} (including most of those using @command{clang}" "@footnote{Some builds of @command{clang} 3.7 have support for OpenMP 3.1}) " "have no OpenMP support at all, not even @file{omp.h}." msgstr "" # #. type: Plain text #: R-exts.texi:2023 msgid "" "For example, a package with C code written for OpenMP should have in " "@file{src/Makevars} the lines" msgstr "" # #. type: example #: R-exts.texi:2027 #, no-wrap msgid "" "PKG_CFLAGS = $(SHLIB_OPENMP_CFLAGS)\n" "PKG_LIBS = $(SHLIB_OPENMP_CFLAGS)\n" msgstr "" # #. type: Plain text #: R-exts.texi:2032 msgid "" "Note that the macro @code{SHLIB_OPENMP_CXXFLAGS} applies to the C++98 " "compiler and not necessarily to the C++11 compiler: users of the latter " "should do their own @command{configure} checks." msgstr "" #. type: Plain text #: R-exts.texi:2038 msgid "" "Some care is needed when compilers are from different families which may use " "different OpenMP runtimes (e.g.@: @command{clang} @emph{vs} GCC including " "@command{gfortran}, although it is currently possible to use the " "@command{clang} runtime with GCC but not @emph{vice versa}). For a package " "with Fortran 77 code using OpenMP the appropriate lines are" msgstr "" #. type: example #: R-exts.texi:2042 #, no-wrap msgid "" "PKG_FFLAGS = $(SHLIB_OPENMP_FFLAGS)\n" "PKG_LIBS = $(SHLIB_OPENMP_CFLAGS)\n" msgstr "" #. type: Plain text #: R-exts.texi:2047 msgid "" "as the C compiler will be used to link the package code (and there is no " "guarantee that this will work everywhere)." msgstr "" #. type: Plain text #: R-exts.texi:2054 msgid "" "There is nothing to say what version of OpenMP is supported: version 3.0 " "(May 2008) is supported by recent versions of the Linux, Windows and Solaris " "platforms, but portable packages cannot assume that end users have recent " "versions. OS X currently uses Apple builds of @command{clang} with no " "OpenMP support." msgstr "" #. type: Plain text #: R-exts.texi:2064 msgid "" "The performance of OpenMP varies substantially between platforms. Both the " "Windows and earlier Apple OS X implementations have substantial overheads " "and are only beneficial if quite substantial tasks are run in parallel. " "Also, on Windows new threads are started with the default@footnote{Windows " "default, not MinGW-w64 default.} FPU control word, so computations done on " "OpenMP threads will not make use of extended-precision arithmetic which is " "the default for the main process." msgstr "" # #. type: Plain text #: R-exts.texi:2069 msgid "" "Calling any of the @R{} API from threaded code is `for experts only': they " "will need to read the source code to determine if it is thread-safe. In " "particular, code which makes use of the stack-checking mechanism must not be " "called from threaded code." msgstr "" #. type: Plain text #: R-exts.texi:2088 msgid "" "Packages are not standard-alone programs, and an @R{} process could contain " "more than one OpenMP-enabled package as well as other components (for " "example, an optimized BLAS) making use of OpenMP. So careful consideration " "needs to be given to resource usage. OpenMP works with parallel regions, " "and for most implementations the default is to use as many threads as `CPUs' " "for such regions. Parallel regions can be nested, although it is common to " "use only a single thread below the first level. The correctness of the " "detected number of `CPUs' and the assumption that the @R{} process is " "entitled to use them all are both dubious assumptions. The best way to " "limit resources is to limit the overall number of threads available to " "OpenMP in the @R{} process: this can be done via environment variable " "@env{OMP_THREAD_LIMIT}, where implemented.@footnote{Which it was at the time " "of writing with GCC, Solaris Studio, Intel and Clang 3.7.x compilers.} " "Alternatively, the number of threads per region can be limited by the " "environment variable @env{OMP_NUM_THREADS} or API call " "@code{omp_set_num_threads}, or, better, for the regions in your code as part " "of their specification. E.g.@: @R{} uses" msgstr "" # #. type: example #: R-exts.texi:2090 #, no-wrap msgid "#pragma omp parallel for num_threads(nthreads) @dots{}\n" msgstr "" # #. type: Plain text #: R-exts.texi:2093 msgid "" "That way you only control your own code and not that of other OpenMP users." msgstr "" # #. type: Plain text #: R-exts.texi:2101 msgid "" "There is no direct support for the POSIX threads (more commonly known as " "@code{pthreads}): by the time we considered adding it several packages were " "using it unconditionally so it seems that nowadays it is universally " "available on POSIX operating systems (hence not Windows)." msgstr "" # #. type: Plain text #: R-exts.texi:2104 msgid "" "For reasonably recent versions of @command{gcc} and @command{clang} the " "correct specification is" msgstr "" # #. type: example #: R-exts.texi:2108 #, no-wrap msgid "" "PKG_CPPFLAGS = -pthread\n" "PKG_LIBS = -pthread\n" msgstr "" # #. type: Plain text #: R-exts.texi:2113 msgid "" "(and the plural version is also accepted on some systems/versions). For " "other platforms the specification is" msgstr "" # #. type: example #: R-exts.texi:2117 #, no-wrap msgid "" "PKG_CPPFLAGS = -D_REENTRANT\n" "PKG_LIBS = -lpthread\n" msgstr "" # #. type: Plain text #: R-exts.texi:2122 msgid "" "(and note that the library name is singular). This is what @option{-" "pthread} does on all known current platforms (although earlier versions of " "OpenBSD used a different library name)." msgstr "" # #. type: Plain text #: R-exts.texi:2125 msgid "" "For a tutorial see @uref{https://computing.llnl.gov/@/tutorials/@/pthreads/}." msgstr "" # #. type: Plain text #: R-exts.texi:2130 msgid "" "POSIX threads are not normally used on Windows, which has its own native " "concepts of threads. However, there are two projects implementing " "@code{pthreads} on top of Windows, @code{pthreads-w32} and " "@code{winpthreads} (a recent part of the MinGW-w64 project)." msgstr "" # #. type: Plain text #: R-exts.texi:2136 msgid "" "Whether Windows toolchains implement @code{pthreads} is up to the toolchain " "provider: the currently recommended toolchain does by default provide it. A " "@command{make} variable @code{SHLIB_PTHREAD_FLAGS} is available: this should " "be included in both @code{PKG_CPPFLAGS} (or the Fortran or F9x equivalents) " "and @code{PKG_LIBS}." msgstr "" # #. type: Plain text #: R-exts.texi:2141 msgid "" "The presence of a working @code{pthreads} implementation cannot be " "unambiguously determined without testing for yourself: however, that " "@samp{_REENTRANT} is defined@footnote{some Windows toolchains have the typo " "@samp{_REENTRANCE} instead.} in C/C++ code is a good indication." msgstr "" # #. type: Plain text #: R-exts.texi:2145 msgid "" "See also the comments on thread-safety and performance under OpenMP: on all " "known @R{} platforms OpenMP is implemented @emph{via} @code{pthreads} and " "the known performance issues are in the latter." msgstr "" # #. type: Plain text #: R-exts.texi:2152 msgid "" "Package authors fairly often want to organize code in sub-directories of " "@file{src}, for example if they are including a separate piece of external " "software to which this is an @R{} interface." msgstr "" # #. type: Plain text #: R-exts.texi:2156 msgid "" "One simple way is simply to set @code{OBJECTS} to be all the objects that " "need to be compiled, including in sub-directories. For example, " "@acronym{CRAN} package @CRANpkg{RSiena} has" msgstr "" # #. type: smallexample #: R-exts.texi:2159 #, no-wrap msgid "" "SOURCES = $(wildcard data/*.cpp network/*.cpp utils/*.cpp model/*.cpp model/*/*.cpp model/*/*/*.cpp)\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2161 #, no-wrap msgid "OBJECTS = siena07utilities.o siena07internals.o siena07setup.o siena07models.o $(SOURCES:.cpp=.o)\n" msgstr "" # #. type: Plain text #: R-exts.texi:2167 msgid "" "One problem with that approach is that unless GNU make extensions are used, " "the source files need to be listed and kept up-to-date. As in the following " "from @acronym{CRAN} package @CRANpkg{lossDev}:" msgstr "" # #. type: smallexample #: R-exts.texi:2176 #, no-wrap msgid "" "OBJECTS.samplers = samplers/ExpandableArray.o samplers/Knots.o \\\n" " samplers/RJumpSpline.o samplers/RJumpSplineFactory.o \\\n" " samplers/RealSlicerOV.o samplers/SliceFactoryOV.o samplers/MNorm.o\n" "OBJECTS.distributions = distributions/DSpline.o \\\n" " distributions/DChisqrOV.o distributions/DTOV.o \\\n" " distributions/DNormOV.o distributions/DUnifOV.o distributions/RScalarDist.o\n" "OBJECTS.root = RJump.o\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2178 #, no-wrap msgid "OBJECTS = $(OBJECTS.samplers) $(OBJECTS.distributions) $(OBJECTS.root)\n" msgstr "" # #. type: Plain text #: R-exts.texi:2182 msgid "" "Where the subdirectory is self-contained code with a suitable makefile, the " "best approach is something like" msgstr "" # #. type: smallexample #: R-exts.texi:2185 #, no-wrap msgid "" "PKG_LIBS = -LCsdp/lib -lsdp $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2187 #, no-wrap msgid "" "$(SHLIB): Csdp/lib/libsdp.a\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2191 #, no-wrap msgid "" "Csdp/lib/libsdp.a\n" "\t@@(cd Csdp/lib && $(MAKE) libsdp.a \\\n" "\t CC=\"$(CC)\" CFLAGS=\"$(CFLAGS) $(CPICFLAGS)\" AR=\"$(AR)\" RANLIB=\"$(RANLIB)\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:2199 msgid "" "Note the quotes: the macros can contain spaces, e.g.@: @code{CC = \"gcc -m64 " "-std=gnu99\"}. Several authors have forgotten about parallel makes: the " "static library in the subdirectory must be made before the shared object " "(@code{$(SHLIB)}) and so the latter must depend on the former. Others " "forget the need for position-independent code." msgstr "" # #. type: Plain text #: R-exts.texi:2203 msgid "" "We really do not recommend using @file{src/Makefile} instead of @file{src/" "Makevars}, and as the example above shows, it is not necessary." msgstr "" # #. type: Plain text #: R-exts.texi:2210 msgid "" "It may be helpful to give an extended example of using a @file{configure} " "script to create a @file{src/Makevars} file: this is based on that in the " "@CRANpkg{RODBC} package." msgstr "" # #. type: Plain text #: R-exts.texi:2214 msgid "" "The @file{configure.ac} file follows: @file{configure} is created from this " "by running @command{autoconf} in the top-level package directory (containing " "@file{configure.ac})." msgstr "" # #. type: smallexample #: R-exts.texi:2219 #, no-wrap msgid "" "AC_INIT([RODBC], 1.1.8) dnl package name, version\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2226 #, no-wrap msgid "" "dnl A user-specifiable option\n" "odbc_mgr=\"\"\n" "AC_ARG_WITH([odbc-manager],\n" "\t AC_HELP_STRING([--with-odbc-manager=MGR],\n" "\t\t\t [specify the ODBC manager, e.g. odbc or iodbc]),\n" "\t [odbc_mgr=$withval])\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2230 #, no-wrap msgid "" "if test \"$odbc_mgr\" = \"odbc\" ; then\n" " AC_PATH_PROGS(ODBC_CONFIG, odbc_config)\n" "fi\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2245 #, no-wrap msgid "" "dnl Select an optional include path, from a configure option\n" "dnl or from an environment variable.\n" "AC_ARG_WITH([odbc-include],\n" "\t AC_HELP_STRING([--with-odbc-include=INCLUDE_PATH],\n" "\t\t\t [the location of ODBC header files]),\n" "\t [odbc_include_path=$withval])\n" "RODBC_CPPFLAGS=\"-I.\"\n" "if test [ -n \"$odbc_include_path\" ] ; then\n" " RODBC_CPPFLAGS=\"-I. -I$@{odbc_include_path@}\"\n" "else\n" " if test [ -n \"$@{ODBC_INCLUDE@}\" ] ; then\n" " RODBC_CPPFLAGS=\"-I. -I$@{ODBC_INCLUDE@}\"\n" " fi\n" "fi\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2263 #, no-wrap msgid "" "dnl ditto for a library path\n" "AC_ARG_WITH([odbc-lib],\n" "\t AC_HELP_STRING([--with-odbc-lib=LIB_PATH],\n" "\t\t\t [the location of ODBC libraries]),\n" "\t [odbc_lib_path=$withval])\n" "if test [ -n \"$odbc_lib_path\" ] ; then\n" " LIBS=\"-L$odbc_lib_path $@{LIBS@}\"\n" "else\n" " if test [ -n \"$@{ODBC_LIBS@}\" ] ; then\n" " LIBS=\"-L$@{ODBC_LIBS@} $@{LIBS@}\"\n" " else\n" " if test -n \"$@{ODBC_CONFIG@}\"; then\n" " odbc_lib_path=`odbc_config --libs | sed s/-lodbc//`\n" " LIBS=\"$@{odbc_lib_path@} $@{LIBS@}\"\n" " fi\n" " fi\n" "fi\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2276 #, no-wrap msgid "" "dnl Now find the compiler and compiler flags to use\n" ": $@{R_HOME=`R RHOME`@}\n" "if test -z \"$@{R_HOME@}\"; then\n" " echo \"could not determine R_HOME\"\n" " exit 1\n" "fi\n" "CC=`\"$@{R_HOME@}/bin/R\" CMD config CC`\n" "CPP=`\"$@{R_HOME@}/bin/R\" CMD config CPP`\n" "CFLAGS=`\"$@{R_HOME@}/bin/R\" CMD config CFLAGS`\n" "CPPFLAGS=`\"$@{R_HOME@}/bin/R\" CMD config CPPFLAGS`\n" "AC_PROG_CC\n" "AC_PROG_CPP\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2282 #, no-wrap msgid "" "if test -n \"$@{ODBC_CONFIG@}\"; then\n" " RODBC_CPPFLAGS=`odbc_config --cflags`\n" "fi\n" "CPPFLAGS=\"$@{CPPFLAGS@} $@{RODBC_CPPFLAGS@}\"\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2289 #, no-wrap msgid "" "dnl Check the headers can be found\n" "AC_CHECK_HEADERS(sql.h sqlext.h)\n" "if test \"$@{ac_cv_header_sql_h@}\" = no ||\n" " test \"$@{ac_cv_header_sqlext_h@}\" = no; then\n" " AC_MSG_ERROR(\"ODBC headers sql.h and sqlext.h not found\")\n" "fi\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2298 #, no-wrap msgid "" "dnl search for a library containing an ODBC function\n" "if test [ -n \"$@{odbc_mgr@}\" ] ; then\n" " AC_SEARCH_LIBS(SQLTables, $@{odbc_mgr@}, ,\n" " AC_MSG_ERROR(\"ODBC driver manager $@{odbc_mgr@} not found\"))\n" "else\n" " AC_SEARCH_LIBS(SQLTables, odbc odbc32 iodbc, ,\n" " AC_MSG_ERROR(\"no ODBC driver manager found\"))\n" "fi\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2303 #, no-wrap msgid "" "dnl for 64-bit ODBC need SQL[U]LEN, and it is unclear where they are defined.\n" "AC_CHECK_TYPES([SQLLEN, SQLULEN], , , [# include <sql.h>])\n" "dnl for unixODBC header\n" "AC_CHECK_SIZEOF(long, 4)\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:2311 #, no-wrap msgid "" "dnl substitute RODBC_CPPFLAGS and LIBS\n" "AC_SUBST(RODBC_CPPFLAGS)\n" "AC_SUBST(LIBS)\n" "AC_CONFIG_HEADERS([src/config.h])\n" "dnl and do substitution in the src/Makevars.in and src/config.h\n" "AC_CONFIG_FILES([src/Makevars])\n" "AC_OUTPUT\n" msgstr "" # #. type: Plain text #: R-exts.texi:2317 msgid "where @file{src/Makevars.in} would be simply" msgstr "" # #. type: example #: R-exts.texi:2322 #, no-wrap msgid "" "PKG_CPPFLAGS = @@RODBC_CPPFLAGS@@\n" "PKG_LIBS = @@LIBS@@\n" msgstr "" # #. type: Plain text #: R-exts.texi:2327 msgid "" "A user can then be advised to specify the location of the ODBC driver " "manager files by options like (lines broken for easier reading)" msgstr "" # #. type: example #: R-exts.texi:2333 #, no-wrap msgid "" "R CMD INSTALL \\\n" " --configure-args='--with-odbc-include=/opt/local/include \\\n" " --with-odbc-lib=/opt/local/lib --with-odbc-manager=iodbc' \\\n" " RODBC\n" msgstr "" # #. type: Plain text #: R-exts.texi:2338 msgid "" "or by setting the environment variables @code{ODBC_INCLUDE} and " "@code{ODBC_LIBS}." msgstr "" # #. type: Plain text #: R-exts.texi:2349 msgid "" "@R{} assumes that source files with extension @file{.f} are FORTRAN 77, and " "passes them to the compiler specified by @samp{F77}. On most but not all " "platforms that compiler will accept Fortran 90/95 code: some platforms have " "a separate Fortran 90/95 compiler and a few (by now quite " "rare@footnote{Cygwin used @command{g77} up to 2011, and some pre-built " "versions of @R{} for Unix OSes still do.}) platforms have no Fortran 90/95 " "support." msgstr "" #. type: Plain text #: R-exts.texi:2355 msgid "" "This means that portable packages need to be written in correct FORTRAN 77, " "which will also be valid Fortran 95. See @uref{https://developer.R-project." "org/@/Portability.html} for reference resources. In particular, @emph{free " "source form} F95 code is not portable." msgstr "" # #. type: Plain text #: R-exts.texi:2367 msgid "" "On some systems an alternative F95 compiler is available: from the " "@code{gcc} family this might be @command{gfortran} or @command{g95}. " "Configuring @R{} will try to find a compiler which (from its name) appears " "to be a Fortran 90/95 compiler, and set it in macro @samp{FC}. Note that it " "does not check that such a compiler is fully (or even partially) compliant " "with Fortran 90/95. Packages making use of Fortran 90/95 features should " "use file extension @file{.f90} or @file{.f95} for the source files: the " "variable @code{PKG_FCFLAGS} specifies any special flags to be used. There " "is no guarantee that compiled Fortran 90/95 code can be mixed with any other " "type of compiled code, nor that a build of @R{} will have support for such " "packages." msgstr "" #. type: Plain text #: R-exts.texi:2375 msgid "" "Some (but not) all compilers specified by the @samp{FC} macro will accept " "Fortran 2003 or 2008 code: such code should still use file extension @file{." "f90} or @file{.f95}. For platforms using @command{gfortran}, you may need " "to include @option{-std=f2003} or @option{-std=f2008} in @code{PKG_FCFLAGS}: " "the default is `GNU Fortran', Fortran 95 with non-standard extensions. The " "Solaris @command{f95} compiler `accepts some Fortran 2003 features'." msgstr "" # #. type: Plain text #: R-exts.texi:2387 msgid "" "Modern versions of Fortran support modules, whereby compiling one source " "file creates a module file which is then included in others. (Module files " "typically have a @file{.mod} extension: they do depend on the compiler used " "and so should never be included in a package.) This creates a dependence " "which @command{make} will not know about and often causes installation with " "a parallel make to fail. Thus it is necessary to add explicit dependencies " "to @file{src/Makevars} to tell @command{make} the constraints on the order " "of compilation. For example, if file @file{iface.f90} creates a module " "@samp{iface} used by files @file{cmi.f90} and @file{dmi.f90} then @file{src/" "Makevars} needs to contain something like" msgstr "" # #. type: example #: R-exts.texi:2390 #, no-wrap msgid "cmi.o dmi.o: iface.o\n" msgstr "" #. type: Plain text #: R-exts.texi:2407 msgid "" "@R{} can be built without a C++ compiler although one is available (but not " "necessarily installed) on all known @R{} platforms. For full portability " "across platforms, all that can be assumed is approximate support for the C+" "+98 standard (the widely used @command{g++} deviates considerably from the " "standard). Some compilers have a concept of `C++03' (`essentially a bug " "fix') or `C++ Technical Report 1' (TR1), an optional addition to the `C++03' " "revision which was published in 2007. A revised standard was published in " "2011 and compilers with fairly complete implementations are becoming " "available. C++11 added all of the C99 features which are not otherwise " "implemented in C++, and C++ compilers commonly accept C99 extensions to C+" "+98. A minor update to C++11 (sometimes known as C++14) was approved in " "August 2014." msgstr "" #. type: Plain text #: R-exts.texi:2417 msgid "" "Since version 3.1.0, @R{} has provided support for C++11 in packages in " "addition to C++98. This support is not uniform across platforms as it " "depends on the capabilities of the compiler (see below). When @R{} is " "configured, it will determine whether the C++ compiler supports C++11 and " "which compiler flags, if any, are required to enable C++11 support. For " "example, recent versions of @command{g++} or @command{clang++} accept the " "compiler flag @option{-std=c++11}, and earlier versions support a flag " "@option{-std=c++0x}, but the latter only provides partial support for the C+" "+11 standard." msgstr "" # #. type: Plain text #: R-exts.texi:2420 msgid "" "In order to use C++11 code in a package, the package's @file{Makevars} file " "(or @file{Makevars.win} on Windows) should include the line" msgstr "" # #. type: example #: R-exts.texi:2423 #, no-wrap msgid "CXX_STD = CXX11\n" msgstr "" # #. type: Plain text #: R-exts.texi:2429 msgid "" "Compilation and linking will then be done with the C++11 compiler. If any " "other value is given to the @samp{CXX_STD} macro it will be ignored. " "(Further options may become available in the future as the C++ standard " "evolves.)" msgstr "" # #. type: Plain text #: R-exts.texi:2433 msgid "" "Packages without a @file{Makevars} file may specify that they require C++11 " "by including @samp{C++11} in the @samp{SystemRequirements} field of the " "@file{DESCRIPTION} file, e.g." msgstr "" # #. type: example #: R-exts.texi:2436 #, no-wrap msgid "SystemRequirements: C++11\n" msgstr "" # #. type: Plain text #: R-exts.texi:2441 msgid "" "If a package does have a @file{Makevars[.win]} file then setting the make " "variable @samp{CXX_STD} is preferred, as it allows @command{R CMD SHLIB} to " "work correctly in the package's @file{src} directory." msgstr "" # #. type: Plain text #: R-exts.texi:2447 msgid "" "The C++11 compiler will be used systematically by R for all C++ code if the " "environment variable @env{USE_CXX1X} is defined (with any value). Hence this " "environment variable should be defined when invoking @command{R CMD SHLIB} " "in the absence of a @file{Makevars} file (or @file{Makevars.win} on Windows) " "if a C++11 compiler is required." msgstr "" # #. type: Plain text #: R-exts.texi:2453 msgid "" "Further control over compilation of C++11 code can be obtained by specifying " "the macros @samp{CXX1X} and @samp{CXX1XSTD} when @R{} is " "configured@footnote{For details of these and related macros, see file " "@file{config.site} in the @R{} sources.}, or in a personal or site " "@file{Makevars} file." msgstr "" # #. type: ifset #: R-exts.texi:2456 msgid "" "@xref{Customizing package compilation, , Customizing package compilation, R-" "admin, R Installation and Administration}." msgstr "" #. type: Plain text #: R-exts.texi:2469 msgid "" "If C++11 support is not available then these macros are both empty. " "Otherwise, @samp{CXX1X} defaults to the same value as the C++ compiler " "@samp{CXX} and the flag @samp{CXX1XSTD} defaults to @option{-std=c++11} or " "@option{-std=c++0x} (the latter on Windows). It is possible to specify " "@samp{CXX1X} to be a distinct compiler just for C++11--using packages, e.g." "@: @command{g++} on Solaris. Note however that different C++ compilers (and " "even different versions of the same compiler) often differ in their ABI so " "their outputs can rarely be mixed. By setting @samp{CXX1XSTD} it is also " "possible to choose a different dialect of the standard, such as @option{-" "std=gnu++11}, or enable support for the 2014 revision using something like " "@option{-std=c++14} or @option{-std=c++1y}." msgstr "" #. type: Plain text #: R-exts.texi:2476 msgid "" "As noted above, support for C++11 varies across platforms. The default " "compiler on Windows is GCC 4.6.x and supports the @option{-std=c++0x} flag " "and some C++11 features (see @uref{https://gcc.gnu.org/@/gcc-4.6/@/" "cxx0x_status.html}). On some platforms, it may be possible or necessary to " "select a different compiler for C++11, @emph{via} personal or site " "@file{Makevars} files." msgstr "" # #. type: Plain text #: R-exts.texi:2481 msgid "" "There is no guarantee that C++11 can be used in a package in combination " "with any other compiled language (even C), as the C++11 compiler may be " "incompatible with the native compilers for the platform. (There are known " "problems mixing C++11 with Fortran.)" msgstr "" #. type: Plain text #: R-exts.texi:2484 msgid "" "If a package using C++11 has a @command{configure} script it is essential " "that it selects the correct compiler, @emph{via} something like" msgstr "" #. type: example #: R-exts.texi:2491 #, no-wrap msgid "" "CXX1X=`\"$@{R_HOME@}/bin/R\" CMD config CXX11X`\n" "CXX1XSTD=`\"$@{R_HOME@}/bin/R\" CMD config CXX11XSTD`\n" "CXX=\"$(CXX1X) $(CXX1XSTD)\"\n" "CXXFLAGS=`\"$@{R_HOME@}/bin/R\" CMD config CXX11XFLAGS`\n" "AC_LANG(C++)\n" msgstr "" #. type: Plain text #: R-exts.texi:2495 msgid "(paying attention to all the quotes required)." msgstr "" # #. type: Plain text #: R-exts.texi:2503 msgid "" "Before using these tools, please check that your package can be installed " "(which checked it can be loaded). @code{R CMD check} will @emph{inter alia} " "do this, but you may get more detailed error messages doing the install " "directly." msgstr "" # #. type: node #: R-exts.texi:2508 #: R-exts.texi:2544 #: R-exts.texi:2545 #: R-exts.texi:2546 #: R-exts.texi:2851 #, no-wrap msgid "Checking packages" msgstr "" # #. type: node #: R-exts.texi:2508 #: R-exts.texi:2544 #: R-exts.texi:2851 #: R-exts.texi:2852 #: R-exts.texi:2975 #, no-wrap msgid "Building package tarballs" msgstr "" # #. type: cindex #: R-exts.texi:2508 #: R-exts.texi:2851 #: R-exts.texi:2975 #: R-exts.texi:2976 #: R-exts.texi:2977 #, no-wrap msgid "Building binary packages" msgstr "" # #. type: Plain text #: R-exts.texi:2514 msgid "" "If your package specifies an encoding in its @file{DESCRIPTION} file, you " "should run these tools in a locale which makes use of that encoding: they " "may not work at all or may work incorrectly in other locales (although UTF-8 " "locales will most likely work)." msgstr "" # #. type: quotation #: R-exts.texi:2527 msgid "" "@code{R CMD check} and @code{R CMD build} run @R{} processes with @option{--" "vanilla} in which none of the user's startup files are read. If you need " "@env{R_LIBS} set (to find packages in a non-standard library) you can set it " "in the environment: also you can use the check and build environment files " "(as specified by the environment variables @env{R_CHECK_ENVIRON} and " "@env{R_BUILD_ENVIRON}; if unset, files@footnote{On systems which use sub-" "architectures, architecture-specific versions such as @file{~/.R/check." "Renviron.i386} take precedence.} @file{~/.R/check.Renviron} and @file{~/.R/" "build.Renviron} are used) to set environment variables when using these " "utilities." msgstr "" # #. type: quotation #: R-exts.texi:2529 #, no-wrap msgid "Note to Windows users" msgstr "" # #. type: quotation #: R-exts.texi:2535 msgid "" "@code{R CMD build} may make use of the Windows toolset (see the ``R " "Installation and Administration'' manual) if present and in your path, and " "it is required for packages which need it to install (including those with " "@file{configure.win} or @file{cleanup.win} scripts or a @file{src} " "directory) and e.g.@: need vignettes built." msgstr "" # #. type: quotation #: R-exts.texi:2541 msgid "" "You may need to set the environment variable @env{TMPDIR} to point to a " "suitable writable directory with a path not containing spaces -- use forward " "slashes for the separators. Also, the directory needs to be on a case-" "honouring file system (some network-mounted file systems are not)." msgstr "" # #. type: findex #: R-exts.texi:2548 #, no-wrap msgid "R CMD check" msgstr "" # #. type: Plain text #: R-exts.texi:2554 msgid "" "Using @code{R CMD check}, the @R{} package checker, one can test whether " "@emph{source} @R{} packages work correctly. It can be run on one or more " "directories, or compressed package @command{tar} archives with extension " "@file{.tar.gz}, @file{.tgz}, @file{.tar.bz2} or @file{.tar.xz}." msgstr "" # #. type: Plain text #: R-exts.texi:2557 msgid "" "It is strongly recommended that the final checks are run on a @command{tar} " "archive prepared by @command{R CMD build}." msgstr "" # #. type: Plain text #: R-exts.texi:2559 msgid "This runs a series of checks, including" msgstr "" # #. type: enumerate #: R-exts.texi:2564 msgid "" "The package is installed. This will warn about missing cross-references and " "duplicate aliases in help files." msgstr "" # #. type: enumerate #: R-exts.texi:2568 msgid "" "The file names are checked to be valid across file systems and supported " "operating system platforms." msgstr "" # #. type: enumerate #: R-exts.texi:2572 msgid "" "The files and directories are checked for sufficient permissions (Unix-" "alikes only)." msgstr "" # #. type: enumerate #: R-exts.texi:2581 msgid "" "The files are checked for binary executables, using a suitable version of " "@command{file} if available@footnote{A suitable @command{file.exe} is part " "of the Windows toolset: it checks for @command{gfile} if a suitable " "@command{file} is not found: the latter is available in the OpenCSW " "collection for Solaris at @uref{http://www.opencsw.org}. The source " "repository is @uref{ftp://ftp.astron.com/pub/file/}.}. (There may be rare " "false positives.)" msgstr "" # #. type: enumerate #: R-exts.texi:2596 msgid "" "The @file{DESCRIPTION} file is checked for completeness, and some of its " "entries for correctness. Unless installation tests are skipped, checking is " "aborted if the package dependencies cannot be resolved at run time. (You " "may need to set @env{R_LIBS} in the environment if dependent packages are in " "a separate library tree.) One check is that the package name is not that of " "a standard package, nor one of the defunct standard packages (@samp{ctest}, " "@samp{eda}, @samp{lqs}, @samp{mle}, @samp{modreg}, @samp{mva}, @samp{nls}, " "@samp{stepfun} and @samp{ts}). Another check is that all packages mentioned " "in @code{library} or @code{require}s or from which the @file{NAMESPACE} file " "imports or are called @emph{via} @code{::} or @code{:::} are listed (in " "@samp{Depends}, @samp{Imports}, @samp{Suggests}): this is not an exhaustive " "check of the actual imports." msgstr "" # #. type: enumerate #: R-exts.texi:2600 msgid "" "Available index information (in particular, for demos and vignettes) is " "checked for completeness." msgstr "" # #. type: enumerate #: R-exts.texi:2611 msgid "" "The package subdirectories are checked for suitable file names and for not " "being empty. The checks on file names are controlled by the option " "@option{--check-subdirs=@var{value}}. This defaults to @samp{default}, " "which runs the checks only if checking a tarball: the default can be " "overridden by specifying the value as @samp{yes} or @samp{no}. Further, the " "check on the @file{src} directory is only run if the package does not " "contain a @file{configure} script (which corresponds to the value @samp{yes-" "maybe}) and there is no @file{src/Makefile} or @file{src/Makefile.in}." msgstr "" # #. type: enumerate #: R-exts.texi:2614 msgid "" "To allow a @file{configure} script to generate suitable files, files ending " "in @samp{.in} will be allowed in the @file{R} directory." msgstr "" # #. type: enumerate #: R-exts.texi:2618 msgid "" "A warning is given for directory names that look like @R{} package check " "directories -- many packages have been submitted to @acronym{CRAN} " "containing these." msgstr "" # #. type: enumerate #: R-exts.texi:2624 msgid "" "The @R{} files are checked for syntax errors. Bytes which are non-" "@acronym{ASCII} are reported as warnings, but these should be regarded as " "errors unless it is known that the package will always be used in the same " "locale." msgstr "" # #. type: enumerate #: R-exts.texi:2632 msgid "" "It is checked that the package can be loaded, first with the usual default " "packages and then only with package @pkg{base} already loaded. It is checked " "that the namespace this can be loaded in an empty session with only the " "@pkg{base} namespace loaded. (Namespaces and packages can be loaded very " "early in the session, before the default packages are available, so packages " "should work then.)" msgstr "" # #. type: enumerate #: R-exts.texi:2649 msgid "" "The @R{} files are checked for correct calls to @code{library.dynam}. " "Package startup functions are checked for correct argument lists and " "(incorrect) calls to functions which modify the search path or " "inappropriately generate messages. The @R{} code is checked for possible " "problems using @CRANpkg{codetools}. In addition, it is checked whether S3 " "methods have all arguments of the corresponding generic, and whether the " "final argument of replacement functions is called @samp{value}. All foreign " "function calls (@code{.C}, @code{.Fortran}, @code{.Call} and @code{." "External} calls) are tested to see if they have a @code{PACKAGE} argument, " "and if not, whether the appropriate DLL might be deduced from the namespace " "of the package. Any other calls are reported. (The check is generous, and " "users may want to supplement this by examining the output of @code{tools::" "checkFF(\"mypkg\", verbose=TRUE)}, especially if the intention were to " "always use a @code{PACKAGE} argument)" msgstr "" # #. type: enumerate #: R-exts.texi:2656 msgid "" "The @file{Rd} files are checked for correct syntax and metadata, including " "the presence of the mandatory fields (@code{\\name}, @code{\\alias}, " "@code{\\title} and @code{\\description}). The @file{Rd} name and title are " "checked for being non-empty, and there is a check for missing cross-" "references (links)." msgstr "" # #. type: enumerate #: R-exts.texi:2660 msgid "" "A check is made for missing documentation entries, such as undocumented user-" "level objects in the package." msgstr "" # #. type: enumerate #: R-exts.texi:2664 msgid "" "Documentation for functions, data sets, and S4 classes is checked for " "consistency with the corresponding code." msgstr "" # #. type: enumerate #: R-exts.texi:2669 msgid "" "It is checked whether all function arguments given in @code{\\usage} " "sections of @file{Rd} files are documented in the corresponding " "@code{\\arguments} section." msgstr "" # #. type: enumerate #: R-exts.texi:2673 msgid "" "The @file{data} directory is checked for non-@acronym{ASCII} characters and " "for the use of reasonable levels of compression." msgstr "" # #. type: enumerate #: R-exts.texi:2682 msgid "" "C, C++ and FORTRAN source and header files@footnote{An exception is made for " "subdirectories with names starting @samp{win} or @samp{Win}.} are tested for " "portable (LF-only) line endings. If there is a @file{Makefile} or " "@file{Makefile.in} or @file{Makevars} or @file{Makevars.in} file under the " "@file{src} directory, it is checked for portable line endings and the " "correct use of @samp{$(BLAS_LIBS)} and @samp{$(LAPACK_LIBS)}" msgstr "" # #. type: enumerate #: R-exts.texi:2692 msgid "" "Compiled code is checked for symbols corresponding to functions which might " "terminate @R{} or write to @file{stdout}/@file{stderr} instead of the " "console. Note that the latter might give false positives in that the " "symbols might be pulled in with external libraries and could never be " "called. Windows@footnote{on most other platforms such runtime libraries are " "dynamic, but static libraries are currently used on Windows because the " "toolchain is not a standard part of the OS.} users should note that the " "Fortran and C++ runtime libraries are examples of such external libraries." msgstr "" # #. type: enumerate #: R-exts.texi:2698 msgid "" "Some checks are made of the contents of the @file{inst/doc} directory. " "These always include checking for files that look like leftovers, and if " "suitable tools (such as @command{qpdf}) are available, checking that the PDF " "documentation is of minimal size." msgstr "" # #. type: enumerate #: R-exts.texi:2705 msgid "" "The examples provided by the package's documentation are run. " "(@pxref{Writing R documentation files}, for information on using " "@code{\\examples} to create executable example code.) If there is a file " "@file{tests/Examples/@var{pkg}-Ex.Rout.save}, the output of running the " "examples is compared to that file." msgstr "" # #. type: enumerate #: R-exts.texi:2712 msgid "" "Of course, released packages should be able to run at least their own " "examples. Each example is run in a `clean' environment (so earlier examples " "cannot be assumed to have been run), and with the variables @code{T} and " "@code{F} redefined to generate an error unless they are set in the example: " "@xref{Logical vectors, , Logical vectors, R-intro, An Introduction to R}." msgstr "" # #. type: enumerate #: R-exts.texi:2727 msgid "" "If the package sources contain a @file{tests} directory then the tests " "specified in that directory are run. (Typically they will consist of a set " "of @file{.R} source files and target output files @file{.Rout.save}.) " "Please note that the comparison will be done in the end user's locale, so " "the target output files should be @acronym{ASCII} if at all possible. (The " "command line option @code{--test-dir=foo} may be used to specify tests in a " "non-standard location. For example, unusually slow tests could be placed in " "@file{inst/slowTests} and then @code{R CMD check --test-dir=inst/slowTests} " "would be used to run them. Other names that have been suggested are, for " "example, @file{inst/testWithOracle} for tests that require Oracle to be " "installed, @file{inst/randomTests} for tests which use random values and may " "occasionally fail by chance, etc.)" msgstr "" # #. type: enumerate #: R-exts.texi:2739 msgid "" "The code in package vignettes (@pxref{Writing package vignettes}) is " "executed, and the vignette PDFs re-made from their sources as a check of " "completeness of the sources (unless there is a @samp{BuildVignettes} field " "in the package's @file{DESCRIPTION} file with a false value). If there is a " "target output file @file{.Rout.save} in the vignette source directory, the " "output from running the code in that vignette is compared with the target " "output file and any differences are reported (but not recorded in the log " "file). (If the vignette sources are in the deprecated location @file{inst/" "doc}, do mark such target output files to not be installed in @file{." "Rinstignore}.)" msgstr "" # #. type: enumerate #: R-exts.texi:2751 msgid "" "If there is an error@footnote{or if option @option{--use-valgrind} is used " "or environment variable @env{_R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_} is set to " "a true value or if there are differences from a target output file} in " "executing the @R{} code in vignette @file{@var{foo.ext}}, a log file " "@file{@var{foo.ext}.log} is created in the check directory. The vignette " "PDFs are re-made in a copy of the package sources in the @file{vign_test} " "subdirectory of the check directory, so for further information on errors " "look in directory @file{@var{pkgname}/vign_test/vignettes}. (It is only " "retained if there are errors or if environment variable " "@env{_R_CHECK_CLEAN_VIGN_TEST_} is set to a false value.)" msgstr "" # #. type: enumerate #: R-exts.texi:2756 msgid "" "The PDF version of the package's manual is created (to check that the " "@file{Rd} files can be converted successfully). This needs @LaTeX{} and " "suitable fonts and @LaTeX{} packages to be installed." msgstr "" # #. type: ifset #: R-exts.texi:2759 msgid "" "@xref{Making the manuals, , Making the manuals, R-admin, R Installation and " "Administration}." msgstr "" # #. type: ifclear #: R-exts.texi:2763 msgid "" "See the section `Making the manuals' in the `R Installation and " "Administration' manual' for further details." msgstr "" # #. type: Plain text #: R-exts.texi:2770 msgid "" "All these tests are run with collation set to the @code{C} locale, and for " "the examples and tests with environment variable @env{LANGUAGE=en}: this is " "to minimize differences between platforms." msgstr "" # #. type: Plain text #: R-exts.texi:2775 msgid "" "Use @kbd{R CMD check --help} to obtain more information about the usage of " "the @R{} package checker. A subset of the checking steps can be selected by " "adding command-line options. It also allows customization by setting " "environment variables @w{@env{_R_CHECK_*_}:}, as described in" msgstr "" # #. type: ifset #: R-exts.texi:2777 msgid "@ref{Tools, , Tools, R-ints, R Internals}:" msgstr "" # #. type: ifclear #: R-exts.texi:2780 msgid "`R Internals':" msgstr "" #. type: Plain text #: R-exts.texi:2790 msgid "" "a set of these customizations similar to those used by @acronym{CRAN} can be " "selected by the option @option{--as-cran} (which works best if Internet " "access is available). Some Windows users may need to set environment " "variable @env{R_WIN_NO_JUNCTIONS} to a non-empty value. The test of cyclic " "declarations@footnote{For example, in early 2014 @CRANpkg{gdata} declared " "@samp{Imports: gtools} and @CRANpkg{gtools} declared @samp{Imports: gdata}.}" "in @file{DESCRIPTION} files needs repositories (including @acronym{CRAN}) " "set: do this in @file{~/.Rprofile}, by e.g.@:" msgstr "" #. type: example #: R-exts.texi:2792 #, no-wrap msgid "options(repos = c(CRAN=\"https://cran.r-project.org\"))\n" msgstr "" # #. type: Plain text #: R-exts.texi:2795 msgid "One check customization which can be revealing is" msgstr "" # #. type: example #: R-exts.texi:2797 #, no-wrap msgid "_R_CHECK_CODETOOLS_PROFILE_=\"suppressLocalUnused=FALSE\"\n" msgstr "" # #. type: Plain text #: R-exts.texi:2807 msgid "" "which reports unused local assignments. Not only does this point out " "computations which are unnecessary because their results are unused, it also " "can show errors. (Two such are to intend to update an object by assigning a " "value but mistype its name or assign in the wrong scope, for example using " "@code{<-} where @code{<<-} was intended.) This can give false positives, " "most commonly because of non-standard evaluation for formulae and because " "the intention is to return objects in the environment of a function for " "later use." msgstr "" #. type: Plain text #: R-exts.texi:2813 msgid "" "Complete checking of a package which contains a file @file{README.md} needs " "@command{pandoc} installed: see @uref{http://johnmacfarlane.net/@/pandoc/@/" "installing.html}. This should be reasonably current: @acronym{CRAN} used " "version 1.12.4.1 to process these files at the time of writing" msgstr "" # #. type: Plain text #: R-exts.texi:2821 msgid "" "You do need to ensure that the package is checked in a suitable locale if it " "contains non-@acronym{ASCII} characters. Such packages are likely to fail " "some of the checks in a @code{C} locale, and @command{R CMD check} will warn " "if it spots the problem. You should be able to check any package in a UTF-8 " "locale (if one is available). Beware that although a @code{C} locale is " "rarely used at a console, it may be the default if logging in remotely or " "for batch jobs." msgstr "" # #. type: quotation #: R-exts.texi:2822 #, no-wrap msgid "Multiple sub-architectures" msgstr "" # #. type: quotation #: R-exts.texi:2834 msgid "" "On systems which support multiple sub-architectures (principally Windows), " "@command{R CMD check} will install and check a package which contains " "compiled code under all available sub-architectures. (Use option @option{--" "force-multiarch} to force this for packages without compiled code, which are " "otherwise only checked under the main sub-architecture.) This will run the " "loading tests, examples and @file{tests} directory under each installed sub-" "architecture in turn, and give an error if any fail. Where environment " "variables (including perhaps @env{PATH}) need to be set differently for each " "sub-architecture, these can be set in architecture-specific files such as " "@file{@var{R_HOME}/etc/i386/Renviron.site}." msgstr "" # #. type: quotation #: R-exts.texi:2843 msgid "" "An alternative approach is to use @command{R CMD check --no-multiarch} to " "check the primary sub-architecture, and then to use something like " "@command{R --arch=x86_64 CMD check --extra-arch} or (Windows) @command{/" "path/to/R/bin/x64/Rcmd check --extra-arch} to run for each additional sub-" "architecture just the checks@footnote{loading, examples, tests, running " "vignette code} which differ by sub-architecture. (This approach is required " "for packages which are installed by @command{R CMD INSTALL --merge-" "multiarch}.)" msgstr "" # #. type: quotation #: R-exts.texi:2847 msgid "" "Where packages need additional commands to install all the sub-architectures " "these can be supplied by e.g.@: @option{--install-args=--force-biarch}." msgstr "" # #. type: cindex #: R-exts.texi:2853 #, no-wrap msgid "Building source packages" msgstr "" # #. type: findex #: R-exts.texi:2855 #, no-wrap msgid "R CMD build" msgstr "" # #. type: cindex #: R-exts.texi:2856 #, no-wrap msgid "Package builder" msgstr "" # #. type: cindex #: R-exts.texi:2857 #, no-wrap msgid "tarballs" msgstr "" # #. type: Plain text #: R-exts.texi:2863 msgid "" "Packages may be distributed in source form as ``tarballs'' (@file{.tar.gz} " "files) or in binary form. The source form can be installed on all platforms " "with suitable tools and is the usual form for Unix-like systems; the binary " "form is platform-specific, and is the more common distribution form for the " "Windows and OS X platforms." msgstr "" # #. type: Plain text #: R-exts.texi:2866 msgid "" "Using @command{R CMD build}, the @R{} package builder, one can build @R{} " "package tarballs from their sources (for example, for subsequent release)." msgstr "" # #. type: Plain text #: R-exts.texi:2873 msgid "" "Prior to actually building the package in the standard gzipped tar file " "format, a few diagnostic checks and cleanups are performed. In particular, " "it is tested whether object indices exist and can be assumed to be up-to-" "date, and C, C++ and FORTRAN source files and relevant makefiles in a " "@file{src} directory are tested and converted to LF line-endings if " "necessary." msgstr "" # #. type: Plain text #: R-exts.texi:2876 msgid "" "Run-time checks whether the package works correctly should be performed " "using @command{R CMD check} prior to invoking the final build procedure." msgstr "" # #. type: cindex #: R-exts.texi:2877 #, no-wrap msgid ".Rbuildignore file" msgstr "" # #. type: Plain text #: R-exts.texi:2896 msgid "" "To exclude files from being put into the package, one can specify a list of " "exclude patterns in file @file{.Rbuildignore} in the top-level source " "directory. These patterns should be Perl-like regular expressions (see the " "help for @code{regexp} in @R{} for the precise details), one per line, to be " "matched case-insensitively@footnote{on all platforms from @R{} 3.1.0.} " "against the file and directory names relative to the top-level package " "source directory. In addition, directories from source control " "systems@footnote{called @file{CVS} or @file{.svn} or @file{.arch-ids} or " "@file{.bzr} or @file{.git} (but not files called @file{.git}) or @file{." "hg}.} or from @command{eclipse}@footnote{called @file{.metadata}.}, " "directories with names ending @file{.Rcheck} or @file{Old} or @file{old} and " "files @file{GNUMakefile}@footnote{which is an error: GNU make uses " "@file{GNUmakefile}.}, @file{Read-and-delete-me} or with base names starting " "with @samp{.#}, or starting and ending with @samp{#}, or ending in @samp{~}, " "@samp{.bak} or @samp{.swp}, are excluded by default. In addition, those " "files in the @file{R}, @file{demo} and @file{man} directories which are " "flagged by @command{R CMD check} as having invalid names will be excluded." msgstr "" # #. type: Plain text #: R-exts.texi:2899 msgid "" "Use @kbd{R CMD build --help} to obtain more information about the usage of " "the @R{} package builder." msgstr "" # #. type: Plain text #: R-exts.texi:2909 msgid "" "Unless @kbd{R CMD build} is invoked with the @option{--no-build-vignettes} " "option (or the package's @file{DESCRIPTION} contains @samp{BuildVignettes: " "no} or similar), it will attempt to (re)build the vignettes (@pxref{Writing " "package vignettes}) in the package. To do so it installs the current " "package into a temporary library tree, but any dependent packages need to be " "installed in an available library tree (see the Note: at the top of this " "section)." msgstr "" # #. type: Plain text #: R-exts.texi:2922 msgid "" "Similarly, if the @file{.Rd} documentation files contain any @code{\\Sexpr} " "macros (@pxref{Dynamic pages}), the package will be temporarily installed to " "execute them. Post-execution binary copies of those pages containing build-" "time macros will be saved in @file{build/partial.rdb}. If there are any " "install-time or render-time macros, a @file{.pdf} version of the package " "manual will be built and installed in the @file{build} subdirectory. (This " "allows @acronym{CRAN} or other repositories to display the manual even if " "they are unable to install the package.) This can be suppressed by the " "option @option{--no-manual} or if package's @file{DESCRIPTION} contains " "@samp{BuildManual: no} or similar." msgstr "" # #. type: Plain text #: R-exts.texi:2930 msgid "" "One of the checks that @command{R CMD build} runs is for empty source " "directories. These are in most (but not all) cases unintentional, if they " "are intentional use the option @option{--keep-empty-dirs} (or set the " "environment variable @env{_R_BUILD_KEEP_EMPTY_DIRS_} to @samp{TRUE}, or have " "a @samp{BuildKeepEmpty} field with a true value in the @file{DESCRIPTION} " "file)." msgstr "" # #. type: Plain text #: R-exts.texi:2947 msgid "" "The @option{--resave-data} option allows saved images (@file{.rda} and " "@file{.RData} files) in the @file{data} directory to be optimized for size. " "It will also compress tabular files and convert @file{.R} files to saved " "images. It can take values @code{no}, @code{gzip} (the default if this " "option is not supplied, which can be changed by setting the environment " "variable @env{_R_BUILD_RESAVE_DATA_}) and @code{best} (equivalent to giving " "it without a value), which chooses the most effective compression. Using " "@code{best} adds a dependence on @code{R (>= 2.10)} to the " "@file{DESCRIPTION} file if @command{bzip2} or @command{xz} compression is " "selected for any of the files. If this is thought undesirable, @option{--" "resave-data=gzip} (which is the default if that option is not supplied) will " "do what compression it can with @command{gzip}. A package can control how " "its data is resaved by supplying a @samp{BuildResaveData} field (with one of " "the values given earlier in this paragraph) in its @file{DESCRIPTION} file." msgstr "" # #. type: Plain text #: R-exts.texi:2954 msgid "" "The @option{--compact-vignettes} option will run @code{tools::compactPDF} " "over the PDF files in @file{inst/doc} (and its subdirectories) to losslessly " "compress them. This is not enabled by default (it can be selected by " "environment variable @env{_R_BUILD_COMPACT_VIGNETTES_}) and needs " "@command{qpdf} (@uref{http://qpdf.sourceforge.net/}) to be available." msgstr "" # #. type: Plain text #: R-exts.texi:2957 msgid "" "It can be useful to run @command{R CMD check --check-subdirs=yes} on the " "built tarball as a final check on the contents." msgstr "" # #. type: Plain text #: R-exts.texi:2968 msgid "" "Where a non-POSIX file system is in use which does not utilize execute " "permissions, some care is needed with permissions. This applies on Windows " "and to e.g.@: FAT-formatted drives and SMB-mounted file systems on other " "OSes. The `mode' of the file recorded in the tarball will be whatever " "@code{file.info()} returns. On Windows this will record only directories as " "having execute permission and on other OSes it is likely that all files have " "reported `mode' @code{0777}. A particular issue is packages being built on " "Windows which are intended to contain executable scripts such as " "@file{configure} and @file{cleanup}: @command{R CMD build} ensures those two " "are recorded with execute permission." msgstr "" # #. type: Plain text #: R-exts.texi:2974 msgid "" "Directory @file{build} of the package sources is reserved for use by " "@command{R CMD build}: it contains information which may not easily be " "created when the package is installed, including index information on the " "vignettes and, rarely, information on the help pages and perhaps a copy of " "the PDF reference manual (see above)." msgstr "" # #. type: Plain text #: R-exts.texi:2986 msgid "" "Binary packages are compressed copies of installed versions of packages. " "They contain compiled shared libraries rather than C, C++ or Fortran source " "code, and the R functions are included in their installed form. The format " "and filename are platform-specific; for example, a binary package for " "Windows is usually supplied as a @file{.zip} file, and for the OS X platform " "the default binary package file extension is @file{.tgz}." msgstr "" # #. type: Plain text #: R-exts.texi:2988 msgid "The recommended method of building binary packages is to use" msgstr "" # #. type: command{#1} #: R-exts.texi:2990 msgid "R CMD INSTALL --build pkg" msgstr "" # #. type: Plain text #: R-exts.texi:2996 msgid "" "where @file{pkg} is either the name of a source tarball (in the usual @file{." "tar.gz} format) or the location of the directory of the package source to be " "built. This operates by first installing the package and then packing the " "installed binaries into the appropriate binary package file for the " "particular platform." msgstr "" # #. type: Plain text #: R-exts.texi:3000 msgid "" "By default, @command{R CMD INSTALL --build} will attempt to install the " "package into the default library tree for the local installation of @R{}. " "This has two implications:" msgstr "" # #. type: itemize #: R-exts.texi:3005 msgid "" "If the installation is successful, it will overwrite any existing " "installation of the same package." msgstr "" # #. type: itemize #: R-exts.texi:3009 msgid "" "The default library tree must have write permission; if not, the package " "will not install and the binary will not be created." msgstr "" # #. type: Plain text #: R-exts.texi:3017 msgid "" "To prevent changes to the present working installation or to provide an " "install location with write access, create a suitably located directory with " "write access and use the @command{-l} option to build the package in the " "chosen location. The usage is then" msgstr "" # #. type: command{#1} #: R-exts.texi:3019 msgid "R CMD INSTALL -l location --build pkg" msgstr "" # #. type: Plain text #: R-exts.texi:3024 msgid "" "where @file{location} is the chosen directory with write access. The package " "will be installed as a subdirectory of @file{location}, and the package " "binary will be created in the current directory." msgstr "" #. type: Plain text #: R-exts.texi:3028 msgid "" "Other options for @command{R CMD INSTALL} can be found using @command{R CMD " "INSTALL --help}, and platform-specific details for special cases are " "discussed in the platform-specific FAQs." msgstr "" # #. type: Plain text #: R-exts.texi:3041 msgid "" "Finally, at least one web-based service is available for building binary " "packages from (checked) source code: WinBuilder (see @uref{http://win-" "builder.R-project.org/}) is able to build Windows binaries. Note that this " "is intended for developers on other platforms who do not have access to " "Windows but wish to provide binaries for the Windows platform." msgstr "" # #. type: cindex #: R-exts.texi:3044 #, no-wrap msgid "vignettes" msgstr "" # #. type: cindex #: R-exts.texi:3045 #, no-wrap msgid "Sweave" msgstr "" # #. type: node #: R-exts.texi:3050 #: R-exts.texi:3199 #: R-exts.texi:3200 #: R-exts.texi:3272 #, no-wrap msgid "Encodings and vignettes" msgstr "" # #. type: subsection #: R-exts.texi:3050 #: R-exts.texi:3199 #: R-exts.texi:3272 #: R-exts.texi:3273 #, no-wrap msgid "Non-Sweave vignettes" msgstr "" # #. type: Plain text #: R-exts.texi:3064 msgid "" "In addition to the help files in @file{Rd} format, @R{} packages allow the " "inclusion of documents in arbitrary other formats. The standard location " "for these is subdirectory @file{inst/doc} of a source package, the contents " "will be copied to subdirectory @file{doc} when the package is installed. " "Pointers from package help indices to the installed documents are " "automatically created. Documents in @file{inst/doc} can be in arbitrary " "format, however we strongly recommend providing them in PDF format, so users " "on almost all platforms can easily read them. To ensure that they can be " "accessed from a browser (as an @HTML{} index is provided), the file names " "should start with an @acronym{ASCII} letter and be comprised entirely of " "@acronym{ASCII} letters or digits or hyphen or underscore." msgstr "" # #. type: Plain text #: R-exts.texi:3073 msgid "" "A special case is @emph{package vignettes}. Vignettes are documents in PDF " "or @HTML{} format obtained from plain text literate source files from which " "@R{} knows how to extract @R{} code and create output (in PDF/@HTML{} or " "intermediate (La)@TeX{}). Vignette engines do this work, using ``tangle'' " "and ``weave'' functions respectively. Sweave, provided by the R " "distribution, is the default engine. Since @R{} version 3.0.0, other " "vignette engines besides Sweave are supported; see @ref{Non-Sweave " "vignettes}." msgstr "" # #. type: Plain text #: R-exts.texi:3079 msgid "" "Package vignettes have their sources in subdirectory @file{vignettes} of the " "package sources. Note that the location of the vignette sources only " "affects @command{R CMD build} and @command{R CMD check}: the tarball built " "by @command{R CMD build} includes in @file{inst/doc} the components intended " "to be installed." msgstr "" # #. type: Plain text #: R-exts.texi:3088 msgid "" "Sweave vignette sources are normally given the file extension @file{.Rnw} or " "@file{.Rtex}, but for historical reasons extensions@footnote{and to avoid " "problems with case-insensitive file systems, lower-case versions of all " "these extensions.} @file{.Snw} and @file{.Stex} are also recognized. Sweave " "allows the integration of @LaTeX{} documents: see the @code{Sweave} help " "page in @R{} and the @code{Sweave} vignette in package @pkg{utils} for " "details on the source document format." msgstr "" # #. type: Plain text #: R-exts.texi:3100 msgid "" "Package vignettes are tested by @code{R CMD check} by executing all @R{} " "code chunks they contain (except those marked for non-evaluation, e.g., with " "option @code{eval=FALSE} for Sweave). The @R{} working directory for all " "vignette tests in @code{R CMD check} is a @emph{copy} of the vignette source " "directory. Make sure all files needed to run the @R{} code in the vignette " "(data sets, @dots{}) are accessible by either placing them in the @file{inst/" "doc} hierarchy of the source package or by using calls to @code{system." "file()}. All other files needed to re-make the vignettes (such as @LaTeX{} " "style files, Bib@TeX{} input files and files for any figures not created by " "running the code in the vignette) must be in the vignette source directory." msgstr "" # #. type: Plain text #: R-exts.texi:3112 msgid "" "@code{R CMD build} will automatically@footnote{unless inhibited by using " "@samp{BuildVignettes: no} in the @file{DESCRIPTION} file.} create the (PDF " "or @HTML{} versions of the) vignettes in @file{inst/doc} for distribution " "with the package sources. By including the vignette outputs in the package " "sources it is not necessary that these can be re-built at install time, i." "e., the package author can use private @R{} packages, screen snapshots and " "@LaTeX{} extensions which are only available on his machine." "@footnote{provided the conditions of the package's license are met: many, " "including @acronym{CRAN}, see the omission of source components as " "incompatible with an Open Source license.}" msgstr "" # #. type: Plain text #: R-exts.texi:3118 msgid "" "By default @code{R CMD build} will run @code{Sweave} on all Sweave vignette " "source files in @file{vignettes}. If @file{Makefile} is found in the " "vignette source directory, then @code{R CMD build} will try to run " "@command{make} after the @code{Sweave} runs, otherwise @code{texi2pdf} is " "run on each @file{.tex} file produced." msgstr "" # #. type: Plain text #: R-exts.texi:3129 msgid "" "The first target in the @file{Makefile} should take care of both creation of " "PDF/@HTML{} files and cleaning up afterwards (including after " "@code{Sweave}), i.e., delete all files that shall not appear in the final " "package archive. Note that if the @code{make} step runs @R{} it needs to be " "careful to respect the environment values of @env{R_LIBS} and @env{R_HOME}" "@footnote{@code{R_HOME/bin} is prepended to the @env{PATH} so that " "references to @command{R} or @command{Rscript} in the @file{Makefile} do " "make use of the currently running version of @R{}.}. Finally, if there is a " "@file{Makefile} and it has a @samp{clean:} target, @command{make clean} is " "run." msgstr "" # #. type: Plain text #: R-exts.texi:3134 msgid "" "All the usual @emph{caveats} about including a @file{Makefile} apply. It " "must be portable (no @acronym{GNU} extensions), use LF line endings and must " "work correctly with a parallel @command{make}: too many authors have written " "things like" msgstr "" # #. type: example #: R-exts.texi:3138 #, no-wrap msgid "" "## BAD EXAMPLE\n" "all: pdf clean\n" "\n" msgstr "" # #. type: example #: R-exts.texi:3140 #, no-wrap msgid "" "pdf: ABC-intro.pdf ABC-details.pdf\n" "\n" msgstr "" # #. type: example #: R-exts.texi:3143 #, no-wrap msgid "" "%.pdf: %.tex\n" "\ttexi2dvi --pdf $*\n" "\n" msgstr "" # #. type: example #: R-exts.texi:3146 #, no-wrap msgid "" "clean:\n" "\trm *.tex ABC-details-*.pdf\n" msgstr "" # #. type: Plain text #: R-exts.texi:3151 msgid "" "which will start removing the source files whilst @command{pdflatex} is " "working." msgstr "" # #. type: Plain text #: R-exts.texi:3155 msgid "" "Metadata lines can be placed in the source file, preferably in @LaTeX{} " "comments in the preamble. One such is a @code{\\VignetteIndexEntry} of the " "form" msgstr "" # #. type: example #: R-exts.texi:3157 #, no-wrap msgid "%\\VignetteIndexEntry@{Using Animal@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:3166 msgid "" "Others you may see are @code{\\VignettePackage} (currently ignored), " "@code{\\VignetteDepends} and @code{\\VignetteKeyword} (which replaced " "@code{\\VignetteKeywords}). These are processed at package installation " "time to create the saved data frame @file{Meta/vignette.rds}, but only the " "@code{\\VignetteIndexEntry} and @code{\\VignetteKeyword} statements are " "currently used. The @code{\\VignetteEngine} statement is described in " "@ref{Non-Sweave vignettes}." msgstr "" #. type: Plain text #: R-exts.texi:3177 msgid "" "At install time an @HTML{} index for all vignettes in the package is " "automatically created from the @code{\\VignetteIndexEntry} statements unless " "a file @file{index.html} exists in directory @file{inst/doc}. This index is " "linked from the @HTML{} help index for the package. If you do supply a " "@file{inst/doc/index.html} file it should contain relative links only to " "files under the installed @file{doc} directory, or perhaps (not really an " "index) to @HTML{} help files or to the @file{DESCRIPTION} file, and be valid " "@HTML{} as confirmed via the @uref{https://validator.w3.org, W3C Markup " "Validation Service} or @uref{https://validator.nu/, Validator.nu}." msgstr "" # #. type: Plain text #: R-exts.texi:3183 msgid "" "Sweave/Stangle allows the document to specify the @code{split=TRUE} option " "to create a single @R{} file for each code chunk: this will not work for " "vignettes where it is assumed that each vignette source generates a single " "file with the vignette extension replaced by @file{.R}." msgstr "" # #. type: Plain text #: R-exts.texi:3189 msgid "" "Do watch that PDFs are not too large -- one in a @acronym{CRAN} package was " "72MB! This is usually caused by the inclusion of overly detailed figures, " "which will not render well in PDF viewers. Sometimes it is much better to " "generate fairly high resolution bitmap (PNG, JPEG) figures and include " "those in the PDF document." msgstr "" # #. type: cindex #: R-exts.texi:3190 #, no-wrap msgid ".install_extras file" msgstr "" # #. type: Plain text #: R-exts.texi:3197 msgid "" "When @command{R CMD build} builds the vignettes, it copies these and the " "vignette sources from directory @file{vignettes} to @file{inst/doc}. To " "install any other files from the @file{vignettes} directory, include a file " "@file{vignettes/.install_extras} which specifies these as Perl-like regular " "expressions on one or more lines. (See the description of the @file{." "Rinstignore} file for full details.)" msgstr "" # #. type: Plain text #: R-exts.texi:3206 msgid "" "Vignettes will in general include descriptive text, @R{} input, @R{} output " "and figures, @LaTeX{} include files and bibliographic references. As any of " "these may contain non-@acronym{ASCII} characters, the handling of encodings " "can become very complicated." msgstr "" # #. type: Plain text #: R-exts.texi:3213 msgid "" "The vignette source file should be written in @acronym{ASCII} or contain a " "declaration of the encoding (see below). This applies even to comments " "within the source file, since vignette engines process comments to look for " "options and metadata lines. When an engine's weave and tangle functions are " "called on the vignette source, it will be converted to the encoding of the " "current @R{} session." msgstr "" # #. type: Plain text #: R-exts.texi:3217 msgid "" "@code{Stangle()} will produce an @R{} code file in the current locale's " "encoding: for a non-@acronym{ASCII} vignette what that is recorded in a " "comment at the top of the file." msgstr "" # #. type: Plain text #: R-exts.texi:3221 msgid "" "@code{Sweave()} will produce a @file{.tex} file in the current encoding, or " "in UTF-8 if that is declared. Non-@acronym{ASCII} encodings need to be " "declared to @LaTeX{} via a line like" msgstr "" # #. type: example #: R-exts.texi:3223 #: R-exts.texi:6423 #, no-wrap msgid "\\usepackage[utf8]@{inputenc@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:3229 msgid "" "(It is also possible to use the more recent @samp{inputenx} @LaTeX{} " "package.) For files where this line is not needed (e.g. chapters included " "within the body of a larger document, or non-Sweave vignettes), the encoding " "may be declared using a comment like" msgstr "" # #. type: example #: R-exts.texi:3231 #, no-wrap msgid "%!\\VignetteEncoding@{UTF-8@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:3235 msgid "" "If the encoding is UTF-8, this can also be declared using the declaration" msgstr "" # #. type: example #: R-exts.texi:3237 #, no-wrap msgid "%!\\SweaveUTF8\n" msgstr "" # #. type: Plain text #: R-exts.texi:3243 msgid "" "If no declaration is given in the vignette, it will be assumed to be in the " "encoding declared for the package. If there is no encoding declared in " "either place, then it is an error to use non-@acronym{ASCII} characters in " "the vignette." msgstr "" # #. type: Plain text #: R-exts.texi:3246 msgid "" "In any case, be aware that @LaTeX{} may require the @samp{usepackage} " "declaration." msgstr "" # #. type: Plain text #: R-exts.texi:3258 msgid "" "@code{Sweave()} will also parse and evaluate the @R{} code in each chunk. " "The @R{} output will also be in the current locale (or @acronym{UTF-8} if so " "declared), and should be covered by the @samp{inputenc} declaration. One " "thing people often forget is that the @R{} output may not be @acronym{ASCII} " "even for @acronym{ASCII} @R{} sources, for many possible reasons. One " "common one is the use of `fancy' quotes: see the @R{} help on @code{sQuote}: " "note carefully that it is not portable to declare UTF-8 or CP1252 to cover " "such quotes, as their encoding will depend on the locale used to run " "@code{Sweave()}: this can be circumvented by setting " "@code{options(useFancyQuotes=\"UTF-8\")} in the vignette." msgstr "" # #. type: Plain text #: R-exts.texi:3263 msgid "" "The final issue is the encoding of figures -- this applies only to PDF " "figures and not PNG etc. The PDF figures will contain declarations for " "their encoding, but the Sweave option @code{pdf.encoding} may need to be set " "appropriately: see the help for the @code{pdf()} graphics device." msgstr "" # #. type: Plain text #: R-exts.texi:3271 msgid "" "As a real example of the complexities, consider the @CRANpkg{fortunes} " "package version @samp{1.4-0}. That package did not have a declared " "encoding, and its vignette was in @acronym{ASCII}. However, the data it " "displays are read from a UTF-8 CSV file and will be assumed to be in the " "current encoding, so @file{fortunes.tex} will be in UTF-8 in any locale. " "Had @code{read.table} been told the data were UTF-8, @file{fortunes.tex} " "would have been in the locale's encoding." msgstr "" # #. type: Plain text #: R-exts.texi:3284 msgid "" "@R{} 3.0.0 and later allow vignettes in formats other than Sweave by means " "of ``vignette engines''. For example @CRANpkg{knitr} version 1.1 or later " "can create @file{.tex} files from a variation on Sweave format, and @file{." "html} files from a variation on ``markdown'' format. These engines replace " "the @code{Sweave()} function with other functions to convert vignette source " "files into @LaTeX{} files for processing into @file{.pdf}, or directly into " "@file{.pdf} or @file{.html} files. The @code{Stangle()} function is replaced " "with a function that extracts the @R{} source from a vignette." msgstr "" # #. type: Plain text #: R-exts.texi:3290 msgid "" "@R{} recognizes non-Sweave vignettes using filename extensions specified by " "the engine. For example, the @CRANpkg{knitr} package supports the extension " "@file{.Rmd} (standing for ``R markdown''). The user indicates the vignette " "engine within the vignette source using a @code{\\VignetteEngine} line, for " "example" msgstr "" # #. type: example #: R-exts.texi:3292 #, no-wrap msgid "%\\VignetteEngine@{knitr::knitr@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:3305 msgid "" "This specifies the name of a package and an engine to use in place of Sweave " "in processing the vignette. As @code{Sweave} is the only engine supplied " "with the @R{} distribution, the package providing any other engine must be " "specified in the @samp{VignetteBuilder} field of the package " "@file{DESCRIPTION} file, and also specified in the @samp{Suggests}, " "@samp{Imports} or @samp{Depends} field (since its namespace must be " "available to build or check your package). If more than one package is " "specified as a builder, they will be searched in the order given there. The " "@pkg{utils} package is always implicitly appended to the list of builder " "packages, but may be included earlier to change the search order." msgstr "" # #. type: Plain text #: R-exts.texi:3310 msgid "" "Note that a package with non-Sweave vignettes should always have a " "@samp{VignetteBuilder} field in the @file{DESCRIPTION} file, since this is " "how @command{R CMD check} recognizes that there are vignettes to be checked: " "packages listed there are required when the package is checked." msgstr "" # #. type: Plain text #: R-exts.texi:3316 msgid "" "The vignette engine can produce @file{.tex}, @file{.pdf}, or @file{.html} " "files as output. If it produces @file{.tex} files, @R{} will call " "@code{texi2pdf} to convert them to @file{.pdf} for display to the user " "(unless there is a @file{Makefile} in the @file{vignettes} directory)." msgstr "" # #. type: Plain text #: R-exts.texi:3320 msgid "" "Package writers who would like to supply vignette engines need to register " "those engines in the package @code{.onLoad} function. For example, that " "function could make the call" msgstr "" # #. type: example #: R-exts.texi:3323 #, no-wrap msgid "" "tools::vignetteEngine(\"knitr\", weave = vweave, tangle = vtangle,\n" "\t\t pattern = \"[.]Rmd$\", package = \"knitr\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:3328 msgid "" "(The actual registration in @CRANpkg{knitr} is more complicated, because it " "supports other input formats.) See the @code{?tools::vignetteEngine} help " "topic for details on engine registration." msgstr "" # #. type: cindex #: R-exts.texi:3332 #, no-wrap msgid "namespaces" msgstr "" # #. type: Plain text #: R-exts.texi:3339 msgid "" "@R{} has a namespace management system for code in packages. This system " "allows the package writer to specify which variables in the package should " "be @emph{exported} to make them available to package users, and which " "variables should be @emph{imported} from other packages." msgstr "" #. type: Plain text #: R-exts.texi:3348 msgid "" "The namespace for a package is specified by the @file{NAMESPACE} file in the " "top level package directory. This file contains @emph{namespace directives} " "describing the imports and exports of the namespace. Additional directives " "register any shared objects to be loaded and any S3-style methods that are " "provided. Note that although the file looks like @R{} code (and often has " "@R{}-style comments) it is not processed as @R{} code. Only very simple " "conditional processing of @code{if} statements is implemented." msgstr "" # #. type: Plain text #: R-exts.texi:3360 msgid "" "Packages are loaded and attached to the search path by calling " "@code{library} or @code{require}. Only the exported variables are placed in " "the attached frame. Loading a package that imports variables from other " "packages will cause these other packages to be loaded as well (unless they " "have already been loaded), but they will @emph{not} be placed on the search " "path by these implicit loads. Thus code in the package can only depend on " "objects in its own namespace and its imports (including the @pkg{base} " "namespace) being visible@footnote{Note that lazy-loaded datasets are " "@emph{not} in the package's namespace so need to be accessed @emph{via} " "@code{::}, e.g.@: @code{survival::survexp.us}.}." msgstr "" # #. type: Plain text #: R-exts.texi:3367 msgid "" "Namespaces are @emph{sealed} once they are loaded. Sealing means that " "imports and exports cannot be changed and that internal variable bindings " "cannot be changed. Sealing allows a simpler implementation strategy for the " "namespace mechanism. Sealing also allows code analysis and compilation " "tools to accurately identify the definition corresponding to a global " "variable reference in a function body." msgstr "" # #. type: Plain text #: R-exts.texi:3372 msgid "" "The namespace controls the search strategy for variables used by functions " "in the package. If not found locally, @R{} searches the package namespace " "first, then the imports, then the base namespace and then the normal search " "path." msgstr "" # #. type: Plain text #: R-exts.texi:3376 msgid "" "Prior to @R{} 2.14.0, namespaces were optional in packages: a default " "namespace was generated on installation in 2.14.x and 2.15.x. As from 3.0.0 " "a namespace is mandatory." msgstr "" # #. type: node #: R-exts.texi:3385 #: R-exts.texi:3388 #: R-exts.texi:3389 #: R-exts.texi:3470 #, no-wrap msgid "Specifying imports and exports" msgstr "" # #. type: node #: R-exts.texi:3385 #: R-exts.texi:3388 #: R-exts.texi:3470 #: R-exts.texi:3471 #: R-exts.texi:3509 #, no-wrap msgid "Registering S3 methods" msgstr "" # #. type: node #: R-exts.texi:3385 #: R-exts.texi:3470 #: R-exts.texi:3509 #: R-exts.texi:3510 #: R-exts.texi:3554 #, no-wrap msgid "Load hooks" msgstr "" # #. type: node #: R-exts.texi:3385 #: R-exts.texi:3509 #: R-exts.texi:3554 #: R-exts.texi:3555 #: R-exts.texi:3562 #: R-exts.texi:3737 #, no-wrap msgid "useDynLib" msgstr "" # #. type: subsection #: R-exts.texi:3385 #: R-exts.texi:3554 #: R-exts.texi:3737 #: R-exts.texi:3738 #: R-exts.texi:3809 #: R-exts.texi:11163 #, no-wrap msgid "An example" msgstr "" # #. type: subsection #: R-exts.texi:3385 #: R-exts.texi:3737 #: R-exts.texi:3809 #: R-exts.texi:3810 #, no-wrap msgid "Namespaces with S4 classes and methods" msgstr "" # #. type: Plain text #: R-exts.texi:3393 msgid "" "Exports are specified using the @code{export} directive in the " "@file{NAMESPACE} file. A directive of the form" msgstr "" # #. type: findex #: R-exts.texi:3394 #, no-wrap msgid "export" msgstr "" # #. type: example #: R-exts.texi:3397 #, no-wrap msgid "export(f, g)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3403 msgid "" "specifies that the variables @code{f} and @code{g} are to be exported. " "(Note that variable names may be quoted, and reserved words and non-standard " "names such as @code{[<-.fractions} must be.)" msgstr "" # #. type: Plain text #: R-exts.texi:3407 msgid "" "For packages with many variables to export it may be more convenient to " "specify the names to export with a regular expression using " "@code{exportPattern}. The directive" msgstr "" # #. type: findex #: R-exts.texi:3408 #: R-exts.texi:3840 #, no-wrap msgid "exportPattern" msgstr "" # #. type: example #: R-exts.texi:3411 #, no-wrap msgid "exportPattern(\"^[^\\\\.]\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:3421 msgid "" "exports all variables that do not start with a period. However, such broad " "patterns are not recommended for production code: it is better to list all " "exports or use narrowly-defined groups. (This pattern applies to S4 " "classes.) Beware of patterns which include names starting with a period: " "some of these are internal-only variables and should never be exported, e.g." "@: @samp{.__S3MethodsTable__.} (and the code nowadays excludes known cases)." msgstr "" # #. type: Plain text #: R-exts.texi:3427 msgid "" "Packages implicitly import the base namespace. Variables exported from " "other packages with namespaces need to be imported explicitly using the " "directives @code{import} and @code{importFrom}. The @code{import} directive " "imports all exported variables from the specified package(s). Thus the " "directives" msgstr "" # #. type: findex #: R-exts.texi:3428 #, no-wrap msgid "import" msgstr "" # #. type: example #: R-exts.texi:3431 #, no-wrap msgid "import(foo, bar)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3438 msgid "" "specifies that all exported variables in the packages @pkg{foo} and " "@pkg{bar} are to be imported. If only some of the exported variables from a " "package are needed, then they can be imported using @code{importFrom}. The " "directive" msgstr "" # #. type: findex #: R-exts.texi:3439 #, no-wrap msgid "importFrom" msgstr "" # #. type: example #: R-exts.texi:3442 #, no-wrap msgid "importFrom(foo, f, g)\n" msgstr "" #. type: Plain text #: R-exts.texi:3449 msgid "" "specifies that the exported variables @code{f} and @code{g} of the package " "@pkg{foo} are to be imported. Using @code{importFrom} selectively rather " "than @code{import} is good practice and recommended notably when importing " "from packages with more than a dozen exports." msgstr "" # #. type: Plain text #: R-exts.texi:3453 msgid "" "It is possible to export variables from a namespace which it has imported " "from other namespaces: this has to be done explicitly and not @emph{via} " "@code{exportPattern}." msgstr "" # #. type: Plain text #: R-exts.texi:3464 msgid "" "If a package only needs a few objects from another package it can use a " "fully qualified variable reference in the code instead of a formal import. " "A fully qualified reference to the function @code{f} in package @pkg{foo} is " "of the form @code{foo::f}. This is slightly less efficient than a formal " "import and also loses the advantage of recording all dependencies in the " "@file{NAMESPACE} file (but they still need to be recorded in the " "@file{DESCRIPTION} file). Evaluating @code{foo::f} will cause package " "@pkg{foo} to be loaded, but not attached, if it was not loaded already---" "this can be an advantage in delaying the loading of a rarely used package." msgstr "" # #. type: Plain text #: R-exts.texi:3469 msgid "" "Using @code{foo:::f} instead of @code{foo::f} allows access to unexported " "objects. This is generally not recommended, as the semantics of unexported " "objects may be changed by the package author in routine maintenance." msgstr "" # #. type: Plain text #: R-exts.texi:3480 msgid "" "The standard method for S3-style @code{UseMethod} dispatching might fail to " "locate methods defined in a package that is imported but not attached to the " "search path. To ensure that these methods are available the packages " "defining the methods should ensure that the generics are imported and " "register the methods using @code{S3method} directives. If a package defines " "a function @code{print.foo} intended to be used as a @code{print} method for " "class @code{foo}, then the directive" msgstr "" # #. type: findex #: R-exts.texi:3481 #, no-wrap msgid "S3method" msgstr "" # #. type: example #: R-exts.texi:3484 #, no-wrap msgid "S3method(print, foo)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3491 msgid "" "ensures that the method is registered and available for @code{UseMethod} " "dispatch, and the function @code{print.foo} does not need to be exported. " "Since the generic @code{print} is defined in @pkg{base} it does not need to " "be imported explicitly." msgstr "" # #. type: Plain text #: R-exts.texi:3495 msgid "" "(Note that function and class names may be quoted, and reserved words and " "non-standard names such as @code{[<-} and @code{function} must be.)" msgstr "" # #. type: Plain text #: R-exts.texi:3498 msgid "" "It is possible to specify a third argument to S3method, the function to be " "used as the method, for example" msgstr "" # #. type: example #: R-exts.texi:3501 #, no-wrap msgid "S3method(print, check_so_symbols, .print.via.format)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3505 msgid "when @code{print.check_so_symbols} is not needed." msgstr "" # #. type: Plain text #: R-exts.texi:3508 msgid "" "There used to be a limit on the number of @code{S3method} directives: it was " "@code{500} prior to @R{} 3.0.2." msgstr "" # #. type: findex #: R-exts.texi:3512 #, no-wrap msgid ".onLoad" msgstr "" # #. type: findex #: R-exts.texi:3513 #, no-wrap msgid ".onAttach" msgstr "" # #. type: Plain text #: R-exts.texi:3516 msgid "" "There are a number of hooks called as packages are loaded, attached, " "detached, and unloaded. See @code{help(\".onLoad\")} for more details." msgstr "" # #. type: Plain text #: R-exts.texi:3523 msgid "" "Since loading and attaching are distinct operations, separate hooks are " "provided for each. These hook functions are called @code{.onLoad} and " "@code{.onAttach}. They both take arguments@footnote{they will be called " "with two unnamed arguments, in that order.} @code{libname} and " "@code{pkgname}; they should be defined in the namespace but not exported." msgstr "" # #. type: findex #: R-exts.texi:3524 #, no-wrap msgid ".onUnload" msgstr "" # #. type: findex #: R-exts.texi:3525 #, no-wrap msgid ".onDetach" msgstr "" # #. type: findex #: R-exts.texi:3526 #, no-wrap msgid ".Last.lib" msgstr "" # #. type: Plain text #: R-exts.texi:3537 msgid "" "Packages can use a @code{.onDetach} (as from @R{} 3.0.0) or @code{.Last.lib} " "function (provided the latter is exported from the namespace) when " "@code{detach} is called on the package. It is called with a single " "argument, the full path to the installed package. There is also a hook " "@code{.onUnload} which is called when the namespace is unloaded (@emph{via} " "a call to @code{unloadNamespace}, perhaps called by @code{detach(unload = " "TRUE)}) with argument the full path to the installed package's directory. " "@code{.onUnload} and @code{.onDetach} should be defined in the namespace and " "not exported, but @code{.Last.lib} does need to be exported." msgstr "" # #. type: Plain text #: R-exts.texi:3542 msgid "" "Packages are not likely to need @code{.onAttach} (except perhaps for a start-" "up banner); code to set options and load shared objects should be placed in " "a @code{.onLoad} function, or use made of the @code{useDynLib} directive " "described next." msgstr "" # #. type: Plain text #: R-exts.texi:3545 msgid "" "User-level hooks are also available: see the help on function @code{setHook}." msgstr "" # #. type: Plain text #: R-exts.texi:3553 msgid "" "These hooks are often used incorrectly. People forget to export @code{.Last." "lib}. Compiled code should be loaded in @code{.onLoad} (or @emph{via} a " "@code{useDynLb} directive: see below) and unloaded in @code{.onUnload}. Do " "remember that a package's namespace can be loaded without the namespace " "being attached (e.g. by @code{pkgname::fun}) and that a package can be " "detached and re-attached whilst its namespace remains loaded." msgstr "" # #. type: Plain text #: R-exts.texi:3561 msgid "" "A @file{NAMESPACE} file can contain one or more @code{useDynLib} directives " "which allows shared objects that need to be loaded.@footnote{NB: this will " "only be read in all versions of @R{} if the package contains @R{} code in a " "@file{R} directory.} The directive" msgstr "" # #. type: example #: R-exts.texi:3565 #, no-wrap msgid "useDynLib(foo)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3575 msgid "" "registers the shared object @code{foo}@footnote{Note that this is the " "basename of the shared object, and the appropriate extension (@file{.so} or " "@file{.dll}) will be added.} for loading with @code{library.dynam}. Loading " "of registered object(s) occurs after the package code has been loaded and " "before running the load hook function. Packages that would only need a load " "hook function to load a shared object can use the @code{useDynLib} directive " "instead." msgstr "" # #. type: Plain text #: R-exts.texi:3580 msgid "" "The @code{useDynLib} directive also accepts the names of the native routines " "that are to be used in @R{} @emph{via} the @code{.C}, @code{.Call}, @code{." "Fortran} and @code{.External} interface functions. These are given as " "additional arguments to the directive, for example," msgstr "" # #. type: example #: R-exts.texi:3583 #, no-wrap msgid "useDynLib(foo, myRoutine, myOtherRoutine)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3592 msgid "" "By specifying these names in the @code{useDynLib} directive, the native " "symbols are resolved when the package is loaded and @R{} variables " "identifying these symbols are added to the package's namespace with these " "names. These can be used in the @code{.C}, @code{.Call}, @code{.Fortran} " "and @code{.External} calls in place of the name of the routine and the " "@code{PACKAGE} argument. For instance, we can call the routine " "@code{myRoutine} from @R{} with the code" msgstr "" # #. type: example #: R-exts.texi:3595 #, no-wrap msgid " .Call(myRoutine, x, y)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3599 msgid "rather than" msgstr "" # #. type: example #: R-exts.texi:3602 #, no-wrap msgid " .Call(\"myRoutine\", x, y, PACKAGE = \"foo\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:3608 msgid "" "There are at least two benefits to this approach. Firstly, the symbol " "lookup is done just once for each symbol rather than each time the routine " "is invoked. Secondly, this removes any ambiguity in resolving symbols that " "might be present in several compiled DLLs." msgstr "" # #. type: Plain text #: R-exts.texi:3616 msgid "" "In some circumstances, there will already be an @R{} variable in the package " "with the same name as a native symbol. For example, we may have an @R{} " "function in the package named @code{myRoutine}. In this case, it is " "necessary to map the native symbol to a different @R{} variable name. This " "can be done in the @code{useDynLib} directive by using named arguments. For " "instance, to map the native symbol name @code{myRoutine} to the @R{} " "variable @code{myRoutine_sym}, we would use" msgstr "" # #. type: example #: R-exts.texi:3619 #, no-wrap msgid "useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3622 msgid "We could then call that routine from @R{} using the command" msgstr "" # #. type: example #: R-exts.texi:3625 #, no-wrap msgid " .Call(myRoutine_sym, x, y)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3629 msgid "" "Symbols without explicit names are assigned to the @R{} variable with that " "name." msgstr "" # #. type: Plain text #: R-exts.texi:3638 msgid "" "In some cases, it may be preferable not to create @R{} variables in the " "package's namespace that identify the native routines. It may be too costly " "to compute these for many routines when the package is loaded if many of " "these routines are not likely to be used. In this case, one can still " "perform the symbol resolution correctly using the DLL, but do this each time " "the routine is called. Given a reference to the DLL as an @R{} variable, " "say @code{dll}, we can call the routine @code{myRoutine} using the expression" msgstr "" # #. type: example #: R-exts.texi:3641 #, no-wrap msgid " .Call(dll$myRoutine, x, y)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3648 msgid "" "The @code{$} operator resolves the routine with the given name in the DLL " "using a call to @code{getNativeSymbol}. This is the same computation as " "above where we resolve the symbol when the package is loaded. The only " "difference is that this is done each time in the case of @code{dll" "$myRoutine}." msgstr "" # #. type: Plain text #: R-exts.texi:3656 msgid "" "In order to use this dynamic approach (e.g., @code{dll$myRoutine}), one " "needs the reference to the DLL as an @R{} variable in the package. The DLL " "can be assigned to a variable by using the @code{variable = dllName} format " "used above for mapping symbols to @R{} variables. For example, if we wanted " "to assign the DLL reference for the DLL @code{foo} in the example above to " "the variable @code{myDLL}, we would use the following directive in the " "@file{NAMESPACE} file:" msgstr "" # #. type: example #: R-exts.texi:3659 #, no-wrap msgid "myDLL = useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3664 msgid "" "Then, the @R{} variable @code{myDLL} is in the package's namespace and " "available for calls such as @code{myDLL$dynRoutine} to access routines that " "are not explicitly resolved at load time." msgstr "" # #. type: Plain text #: R-exts.texi:3675 msgid "" "If the package has registration information (see @ref{Registering native " "routines}), then we can use that directly rather than specifying the list of " "symbols again in the @code{useDynLib} directive in the @file{NAMESPACE} " "file. Each routine in the registration information is specified by giving a " "name by which the routine is to be specified along with the address of the " "routine and any information about the number and type of the parameters. " "Using the @code{.registration} argument of @code{useDynLib}, we can instruct " "the namespace mechanism to create @R{} variables for these symbols. For " "example, suppose we have the following registration information for a DLL " "named @code{myDLL}:" msgstr "" # #. type: example #: R-exts.texi:3680 #, no-wrap msgid "" "static R_NativePrimitiveArgType foo_t[] = @{\n" " REALSXP, INTSXP, STRSXP, LGLSXP\n" "@};\n" "\n" msgstr "" # #. type: example #: R-exts.texi:3686 #, no-wrap msgid "" "static R_CMethodDef cMethods[] = @{\n" " @{\"foo\", (DL_FUNC) &foo, 4, foo_t@},\n" " @{\"bar_sym\", (DL_FUNC) &bar, 0@},\n" " @{NULL, NULL, 0@}\n" "@};\n" "\n" msgstr "" # #. type: example #: R-exts.texi:3692 #, no-wrap msgid "" "static R_CallMethodDef callMethods[] = @{\n" " @{\"R_call_sym\", (DL_FUNC) &R_call, 4@},\n" " @{\"R_version_sym\", (DL_FUNC) &R_version, 0@},\n" " @{NULL, NULL, 0@}\n" "@};\n" msgstr "" # #. type: Plain text #: R-exts.texi:3695 msgid "Then, the directive in the @file{NAMESPACE} file" msgstr "" # #. type: example #: R-exts.texi:3698 #, no-wrap msgid "useDynLib(myDLL, .registration = TRUE)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3704 msgid "" "causes the DLL to be loaded and also for the @R{} variables @code{foo}, " "@code{bar_sym}, @code{R_call_sym} and @code{R_version_sym} to be defined in " "the package's namespace." msgstr "" # #. type: Plain text #: R-exts.texi:3711 msgid "" "Note that the names for the @R{} variables are taken from the entry in the " "registration information and do not need to be the same as the name of the " "native routine. This allows the creator of the registration information to " "map the native symbols to non-conflicting variable names in @R{}, e.g.@: " "@code{R_version} to @code{R_version_sym} for use in an @R{} function such as" msgstr "" # #. type: example #: R-exts.texi:3717 #, no-wrap msgid "" "R_version <- function()\n" "@{\n" " .Call(R_version_sym)\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:3722 msgid "" "Using argument @code{.fixes} allows an automatic prefix to be added to the " "registered symbols, which can be useful when working with an existing " "package. For example, package @CRANpkg{KernSmooth} has" msgstr "" # #. type: example #: R-exts.texi:3725 #, no-wrap msgid "useDynLib(KernSmooth, .registration = TRUE, .fixes = \"F_\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:3731 msgid "" "which makes the @R{} variables corresponding to the FORTRAN symbols " "@code{F_bkde} and so on, and so avoid clashes with @R{} code in the " "namespace." msgstr "" # #. type: Plain text #: R-exts.texi:3742 msgid "" "As an example consider two packages named @pkg{foo} and @pkg{bar}. The @R{} " "code for package @pkg{foo} in file @file{foo.R} is" msgstr "" # #. type: example #: R-exts.texi:3750 #, no-wrap msgid "" "x <- 1\n" "f <- function(y) c(x,y)\n" "foo <- function(x) .Call(\"foo\", x, PACKAGE=\"foo\")\n" "print.foo <- function(x, ...) cat(\"<a foo>\\n\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:3757 msgid "" "Some C code defines a C function compiled into DLL @code{foo} (with an " "appropriate extension). The @file{NAMESPACE} file for this package is" msgstr "" # #. type: example #: R-exts.texi:3764 #, no-wrap msgid "" "useDynLib(foo)\n" "export(f, foo)\n" "S3method(print, foo)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3770 msgid "The second package @pkg{bar} has code file @file{bar.R}" msgstr "" # #. type: example #: R-exts.texi:3777 #, no-wrap msgid "" "c <- function(...) sum(...)\n" "g <- function(y) f(c(y, 7))\n" "h <- function(y) y+9\n" msgstr "" # #. type: Plain text #: R-exts.texi:3783 msgid "and @file{NAMESPACE} file" msgstr "" # #. type: example #: R-exts.texi:3789 #, no-wrap msgid "" "import(foo)\n" "export(g, h)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3797 msgid "" "Calling @code{library(bar)} loads @pkg{bar} and attaches its exports to the " "search path. Package @pkg{foo} is also loaded but not attached to the " "search path. A call to @code{g} produces" msgstr "" # #. type: example #: R-exts.texi:3801 #, no-wrap msgid "" "> g(6)\n" "[1] 1 13\n" msgstr "" # #. type: Plain text #: R-exts.texi:3808 msgid "" "This is consistent with the definitions of @code{c} in the two settings: in " "@pkg{bar} the function @code{c} is defined to be equivalent to @code{sum}, " "but in @pkg{foo} the variable @code{c} refers to the standard function " "@code{c} in @pkg{base}." msgstr "" # #. type: Plain text #: R-exts.texi:3821 msgid "" "Some additional steps are needed for packages which make use of formal (S4-" "style) classes and methods (unless these are purely used internally). The " "package should have @code{Depends: methods} in its @file{DESCRIPTION} " "file@footnote{This was necessary at least prior to @R{} 3.0.2 as the " "@pkg{methods} package looked for its own @R{} code on the search path.} and " "@code{import(methods)} or @code{importFrom(methods, ...)} plus any classes " "and methods which are to be exported need to be declared in the " "@file{NAMESPACE} file. For example, the @pkg{stats4} package has" msgstr "" # #. type: findex #: R-exts.texi:3822 #, no-wrap msgid "exportClasses" msgstr "" # #. type: findex #: R-exts.texi:3823 #, no-wrap msgid "exportMethods" msgstr "" # #. type: example #: R-exts.texi:3838 #, no-wrap msgid "" "export(mle) # exporting methods implicitly exports the generic\n" "importFrom(\"graphics\", plot)\n" "importFrom(\"stats\", optim, qchisq)\n" "## For these, we define methods or (AIC, BIC, nobs) an implicit generic:\n" "importFrom(\"stats\", AIC, BIC, coef, confint, logLik, nobs, profile,\n" "\t update, vcov)\n" "exportClasses(mle, profile.mle, summary.mle)\n" "## All methods for imported generics:\n" "exportMethods(coef, confint, logLik, plot, profile, summary,\n" "\t show, update, vcov)\n" "## implicit generics which do not have any methods here\n" "export(AIC, BIC, nobs)\n" msgstr "" # #. type: findex #: R-exts.texi:3841 #, no-wrap msgid "exportClassPattern" msgstr "" # #. type: Plain text #: R-exts.texi:3850 msgid "" "All S4 classes to be used outside the package need to be listed in an " "@code{exportClasses} directive. Alternatively, they can be specified using " "@code{exportClassPattern}@footnote{This defaults to the same pattern as " "@code{exportPattern}: use something like @code{exportClassPattern(\"^$\")} " "to override this.} in the same style as for @code{exportPattern}. To export " "methods for generics from other packages an @code{exportMethods} directive " "can be used." msgstr "" # #. type: Plain text #: R-exts.texi:3866 msgid "" "Note that exporting methods on a generic in the namespace will also export " "the generic, and exporting a generic in the namespace will also export its " "methods. If the generic function is not local to this package, either " "because it was imported as a generic function or because the non-generic " "version has been made generic solely to add S4 methods to it (as for " "functions such as @code{plot} in the example above), it can be declared " "@emph{via} either or both of @code{export} or @code{exportMethods}, but the " "latter is clearer (and is used in the @pkg{stats4} example above). In " "particular, for primitive functions there is no generic function, so " "@code{export} would export the primitive, which makes no sense. On the " "other hand, if the generic is local to this package, it is more natural to " "export the function itself using @code{export()}, and this @emph{must} be " "done if an implicit generic is created without setting any methods for it " "(as is the case for @code{AIC} in @pkg{stats4})." msgstr "" # #. type: Plain text #: R-exts.texi:3872 msgid "" "A non-local generic function is only exported to ensure that calls to the " "function will dispatch the methods from this package (and that is not done " "or required when the methods are for primitive functions). For this reason, " "you do not need to document such implicitly created generic functions, and " "@code{undoc} in package @pkg{tools} will not report them." msgstr "" # #. type: Plain text #: R-exts.texi:3878 msgid "" "If a package uses S4 classes and methods exported from another package, but " "does not import the entire namespace of the other package@footnote{if it " "does, there will be opaque warnings about replacing imports if the classes/" "methods are also imported.}, it needs to import the classes and methods " "explicitly, with directives" msgstr "" # #. type: findex #: R-exts.texi:3879 #, no-wrap msgid "importClassesFrom" msgstr "" # #. type: findex #: R-exts.texi:3880 #, no-wrap msgid "importMethodsFrom" msgstr "" # #. type: example #: R-exts.texi:3885 #, no-wrap msgid "" "importClassesFrom(package, ...)\n" "importMethodsFrom(package, ...)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3891 msgid "" "listing the classes and functions with methods respectively. Suppose we had " "two small packages @pkg{A} and @pkg{B} with @pkg{B} using @pkg{A}. Then " "they could have @code{NAMESPACE} files" msgstr "" # #. type: example #: R-exts.texi:3898 #, no-wrap msgid "" "export(f1, ng1)\n" "exportMethods(\"[\")\n" "exportClasses(c1)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3904 #: R-exts.texi:11448 msgid "and" msgstr "" # #. type: example #: R-exts.texi:3914 #, no-wrap msgid "" "importFrom(A, ng1)\n" "importClassesFrom(A, c1)\n" "importMethodsFrom(A, f1)\n" "export(f4, f5)\n" "exportMethods(f6, \"[\")\n" "exportClasses(c1, c2)\n" msgstr "" # #. type: Plain text #: R-exts.texi:3920 msgid "respectively." msgstr "" # #. type: Plain text #: R-exts.texi:3923 msgid "" "Note that @code{importMethodsFrom} will also import any generics defined in " "the namespace on those methods." msgstr "" # #. type: Plain text #: R-exts.texi:3930 msgid "" "It is important if you export S4 methods that the corresponding generics are " "available. You may for example need to import @code{plot} from " "@pkg{graphics} to make visible a function to be converted into its implicit " "generic. But it is better practice to make use of the generics exported by " "@pkg{stats4} as this enables multiple packages to unambiguously set methods " "on those generics." msgstr "" # #. type: Plain text #: R-exts.texi:3937 msgid "" "This section contains advice on writing packages to be used on multiple " "platforms or for distribution (for example to be submitted to a package " "repository such as @acronym{CRAN})." msgstr "" # #. type: node #: R-exts.texi:3944 #: R-exts.texi:4276 #: R-exts.texi:4277 #: R-exts.texi:4334 #, no-wrap msgid "PDF size" msgstr "" # #. type: node #: R-exts.texi:3944 #: R-exts.texi:4276 #: R-exts.texi:4334 #: R-exts.texi:4335 #: R-exts.texi:4362 #, no-wrap msgid "Check timing" msgstr "" # #. type: node #: R-exts.texi:3944 #: R-exts.texi:4334 #: R-exts.texi:4362 #: R-exts.texi:4363 #: R-exts.texi:4429 #, no-wrap msgid "Encoding issues" msgstr "" # #. type: node #: R-exts.texi:3944 #: R-exts.texi:4362 #: R-exts.texi:4429 #: R-exts.texi:4430 #: R-exts.texi:4539 #, no-wrap msgid "Portable C and C++ code" msgstr "" # #. type: subsection #: R-exts.texi:3944 #: R-exts.texi:4429 #: R-exts.texi:4539 #: R-exts.texi:4540 #, no-wrap msgid "Binary distribution" msgstr "" # #. type: Plain text #: R-exts.texi:3949 msgid "" "Portable packages should have simple file names: use only alphanumeric " "@acronym{ASCII} characters and period (@code{.}), and avoid those names not " "allowed under Windows which are mentioned above." msgstr "" # #. type: Plain text #: R-exts.texi:3957 msgid "" "Many of the graphics devices are platform-specific: even @code{X11()} (aka " "@code{x11()}) which although emulated on Windows may not be available on a " "Unix-alike (and is not the preferred screen device on OS X). It is rarely " "necessary for package code or examples to open a new device, but if " "essential,@footnote{People use @code{dev.new()} to open a device at a " "particular size: that is not portable but using @code{dev.new(noRStudioGD = " "TRUE)} helps.} use @code{dev.new()}." msgstr "" # #. type: Plain text #: R-exts.texi:3959 msgid "Use @command{R CMD build} to make the release @file{.tar.gz} file." msgstr "" # #. type: Plain text #: R-exts.texi:3964 msgid "" "@command{R CMD check} provides a basic set of checks, but often further " "problems emerge when people try to install and use packages submitted to " "@acronym{CRAN} -- many of these involve compiled code. Here are some " "further checks that you can do to make your package more portable." msgstr "" # #. type: itemize #: R-exts.texi:3971 msgid "" "If your package has a @file{configure} script, provide a @file{configure." "win} script to be used on Windows (an empty file if no actions are needed)." msgstr "" # #. type: itemize #: R-exts.texi:3990 msgid "" "If your package has a @file{Makevars} or @file{Makefile} file, make sure " "that you use only portable make features. Such files should be LF-" "terminated@footnote{Solaris @command{make} does not accept CRLF-terminated " "Makefiles; Solaris warns about and some other @command{make}s ignore " "incomplete final lines.} (including the final line of the file) and not make " "use of GNU extensions. (The POSIX specification is available at " "@uref{http://pubs.opengroup.org/@/onlinepubs/@/9699919799/@/utilities/@/make." "html}; anything not documented there should be regarded as an extension to " "be avoided.) Commonly misused GNU extensions are conditional inclusions " "(@code{ifeq} and the like), @code{$@{shell ...@}} and @code{$@{wildcard ..." "@}}, and the use of @code{+=}@footnote{This was apparently introduced in " "SunOS 4, and is available elsewhere @emph{provided} it is surrounded by " "spaces.} and @code{:=}. Also, the use of @code{$<} other than in implicit " "rules is a GNU extension, as is the @code{$^} macro. Unfortunately " "makefiles which use GNU extensions often run on other platforms but do not " "have the intended results." msgstr "" # #. type: itemize #: R-exts.texi:3992 msgid "" "The use of @code{$@{shell ...@}} can be avoided by using backticks, e.g.@:" msgstr "" # #. type: example #: R-exts.texi:3995 #, no-wrap msgid "PKG_CPPFLAGS = `gsl-config --cflags`\n" msgstr "" # #. type: itemize #: R-exts.texi:4003 msgid "" "which works in all versions of @command{make} known@footnote{GNU make, BSD " "make formerly in FreeBSD and OS X, AT&T make as implemented on Solaris, " "@command{pmake} in FreeBSD, `Distributed Make' (@code{dmake}), part of " "Solaris Studio and available in other versions.} to be used with @R{}." msgstr "" # #. type: itemize #: R-exts.texi:4006 msgid "" "If you really must require GNU make, declare it in the @file{DESCRIPTION} " "file by" msgstr "" # #. type: example #: R-exts.texi:4009 #, no-wrap msgid "SystemRequirements: GNU make\n" msgstr "" # #. type: itemize #: R-exts.texi:4016 msgid "" "If you only need GNU make for parts of the package which are rarely needed " "(for example to create bibliography files under @file{vignettes}), use a " "file called @file{GNUmakefile} rather than @file{Makefile} as GNU make " "(only) will use the former." msgstr "" # #. type: itemize #: R-exts.texi:4019 msgid "" "Since the only viable make for Windows is GNU make, it is permissible to use " "GNU extensions in files @file{Makevars.win} or @file{Makefile.win}." msgstr "" #. type: itemize #: R-exts.texi:4032 msgid "" "Bash extensions also need to be avoided in shell scripts, including " "expressions in Makefiles (which are passed to the shell for processing). " "Some @R{} platforms use strict@footnote{For example, @command{test} options " "@option{-a} and @option{-e} are not portable, and not supported in the AT&T " "Bourne shell used on Solaris, even though they are in the POSIX standard.} " "Bourne shells: the @R{} toolset on Windows and some Unix-alike OSes use " "@command{ash} (@uref{https://en.wikipedia.org/@/wiki/@/Almquist_shell}), a " "rather minimal shell with few builtins. Beware of assuming that all the " "POSIX command-line utilities are available, especially on Windows where only " "a minimal set is provided for use with @R{}." msgstr "" # #. type: ifset #: R-exts.texi:4035 msgid "" "(@xref{The command line tools, , The command line tools, R-admin, R " "Installation and Administration}.)" msgstr "" # #. type: itemize #: R-exts.texi:4041 msgid "" "One particular issue is the use of @command{echo}, for which two behaviours " "are allowed (@uref{http://pubs.opengroup.org/@/onlinepubs/@/9699919799/@/" "utilities/@/echo.html}) and both occur as defaults on @R{} platforms: " "portable applications should not use @option{-n} (as the first argument) nor " "escape sequences." msgstr "" # #. type: itemize #: R-exts.texi:4051 msgid "" "Make use of the abilities of your compilers to check the standards-" "conformance of your code. For example, @command{gcc} can be used with " "options @option{-Wall -pedantic} to alert you to potential problems. This " "is particularly important for C++, where @code{g++ -Wall -pedantic} will " "alert you to the use of GNU extensions which fail to compile on most other C+" "+ compilers. If @R{} was not configured accordingly, one can achieve this " "@emph{via} personal @file{Makevars} files." msgstr "" # #. type: itemize #: R-exts.texi:4060 msgid "" "Although there is a 2011 version of the C++ standard, even partial " "implementations are not universally available. Portable C++ code needs to " "follow the 1998 standard (and not use features from C99). See also " "@ref{Using C++11 code} to specify a C++11 compiler." msgstr "" # #. type: itemize #: R-exts.texi:4064 msgid "" "If you use FORTRAN 77, @code{ftnchek} (@uref{http://www.dsm.fordham.edu/@/" "~ftnchek/}) provides thorough testing of conformance to the standard." msgstr "" # #. type: itemize #: R-exts.texi:4071 msgid "" "Not all common @R{} platforms conform to the expected standards, e.g.@: C99 " "for C code. One common area of problems is the @code{*printf} functions " "where Windows does not support @code{%lld}, @code{%Lf} and similar formats " "(and has its own formats such as @code{%I64d} for 64-bit integers). It is " "very rare to need to output such types, and 64-bit integers can usually be " "converted to doubles for output." msgstr "" # #. type: itemize #: R-exts.texi:4084 msgid "" "Do be very careful with passing arguments between @R{}, C and " "@acronym{FORTRAN} code. In particular, @code{long} in C will be 32-bit on " "some @R{} platforms (including 64-bit Windows), but 64-bit on most modern " "Unix and Linux platforms. It is rather unlikely that the use of @code{long} " "in C code has been thought through: if you need a longer type than " "@code{int} you should use a configure test for a C99 type such as " "@code{int_fast64_t} (and failing that, @code{long long} @footnote{but note " "that @code{long long} is not a standard C++ type, and C++ compilers set up " "for strict checking will reject it.}) and typedef your own type to be " "@code{long} or @code{long long}, or use another suitable type (such as " "@code{size_t})." msgstr "" # #. type: itemize #: R-exts.texi:4090 msgid "" "It is not safe to assume that @code{long} and pointer types are the same " "size, and they are not on 64-bit Windows. If you need to convert pointers " "to and from integers use the C99 integer types @code{intptr_t} and " "@code{uintptr_t} (which are defined in the header @code{<stdint.h>} and are " "not required to be implemented by the C99 standard)." msgstr "" # #. type: itemize #: R-exts.texi:4093 msgid "" "Note that @code{integer} in @acronym{FORTRAN} corresponds to @code{int} in C " "on all @R{} platforms." msgstr "" # #. type: itemize #: R-exts.texi:4106 msgid "" "Under no circumstances should your compiled code ever call @code{abort} or " "@code{exit}@footnote{or where supported the variants @code{_Exit} and " "@code{_exit}.}: these terminate the user's @R{} process, quite possibly " "including all his unsaved work. One usage that could call @code{abort} is " "the @code{assert} macro in C or C++ functions, which should never be active " "in production code. The normal way to ensure that is to define the macro " "@code{NDEBUG}, and @command{R CMD INSTALL} does so as part of the " "compilation flags. If you wish to use @code{assert} during development. you " "can include @code{-UNDEBUG} in @code{PKG_CPPFLAGS}. Note that your own " "@file{src/Makefile} or makefiles in sub-directories may also need to define " "@code{NDEBUG}." msgstr "" # #. type: itemize #: R-exts.texi:4109 msgid "" "This applies not only to your own code but to any external software you " "compile in or link to." msgstr "" # #. type: itemize #: R-exts.texi:4115 msgid "" "Compiled code should not write to @file{stdout} or @file{stderr} and C++ and " "Fortran I/O should not be used. As with the previous item such calls may " "come from external software and may never be called, but package authors are " "often mistaken about that." msgstr "" # #. type: itemize #: R-exts.texi:4124 msgid "" "Compiled code should not call the system random number generators such as " "@code{rand}, @code{drand48} and @code{random}@footnote{This and " "@code{srandom} are in any case not portable. They are in POSIX but not in " "the C99 standard, and not available on Windows.}, but rather use the " "interfaces to @R{}'s RNGs described in @ref{Random numbers}. In particular, " "if more than one package initializes the system RNG (e.g.@: @emph{via} " "@code{srand}), they will interfere with each other." msgstr "" # #. type: itemize #: R-exts.texi:4126 msgid "Nor should the C++11 random number library be used." msgstr "" # #. type: itemize #: R-exts.texi:4131 msgid "" "Errors in memory allocation and reading/writing outside arrays are very " "common causes of crashes (e.g., segfaults) on some machines. See " "@ref{Checking memory access} for tools which can be used to look for this." msgstr "" # #. type: itemize #: R-exts.texi:4136 msgid "" "Many platforms will allow unsatisfied entry points in compiled code, but " "will crash the application (here @R{}) if they are ever used. Some (notably " "Windows) will not. Looking at the output of" msgstr "" # #. type: example #: R-exts.texi:4139 #, no-wrap msgid "nm -pg mypkg.so\n" msgstr "" # #. type: itemize #: R-exts.texi:4144 msgid "" "and checking if any of the symbols marked @code{U} is unexpected is a good " "way to avoid this." msgstr "" # #. type: itemize #: R-exts.texi:4157 msgid "" "Linkers have a lot of freedom in how to resolve entry points in dynamically-" "loaded code, so the results may differ by platform. One area that has " "caused grief is packages including copies of standard system software such " "as @code{libz} (especially those already linked into @R{}). In the case in " "point, entry point @code{gzgets} was sometimes resolved against the old " "version compiled into the package, sometimes against the copy compiled into " "@R{} and sometimes against the system dynamic library. The only safe " "solution is to rename the entry points in the copy in the package. We have " "even seen problems with entry point name @code{myprintf}, which is a system " "entry point@footnote{in @file{libselinux}.} on some Linux systems." msgstr "" # #. type: itemize #: R-exts.texi:4165 msgid "" "Conflicts between symbols in DLLs are handled in very platform-specific " "ways. Good ways to avoid trouble are to make as many symbols as possible " "static (check with @code{nm -pg}), and to use names which are clearly tied " "to your package (which also helps users if anything does go wrong). Note " "that symbol names starting with @code{R_} are regarded as part of @R{}'s " "namespace and should not be used in packages." msgstr "" # #. type: itemize #: R-exts.texi:4172 msgid "" "It is not portable to call compiled code in @R{} or other packages " "@emph{via} @code{.Internal}, @code{.C}, @code{.Fortran}, @code{.Call} or " "@code{.External}, since such interfaces are subject to change without notice " "and will probably result in your code terminating the @R{} process." msgstr "" # #. type: itemize #: R-exts.texi:4176 msgid "" "Do not use (hard or symbolic) file links in your package sources. Where " "possible @command{R CMD build} will replace them by copies." msgstr "" # #. type: itemize #: R-exts.texi:4181 msgid "" "If you do not yourself have a Windows system, consider submitting your " "source package to WinBuilder (@uref{http://win-builder.r-project.org/}) " "before distribution." msgstr "" # #. type: itemize #: R-exts.texi:4187 msgid "" "It is bad practice for package code to alter the search path using " "@code{library}, @code{require} or @code{attach} and this often does not work " "as intended. For alternatives, see @ref{Suggested packages} and @code{with}." msgstr "" #. type: itemize #: R-exts.texi:4197 msgid "" "Examples can be run interactively @emph{via} @code{example} as well as in " "batch mode when checking. So they should behave appropriately in both " "scenarios, conditioning by @code{interactive()} the parts which need an " "operator or observer. For instance, progress bars@footnote{except perhaps " "the simplest kind as used by @code{download.file()} in non-interactive use.} " "are only appropriate in interactive use, as is displaying help pages or " "calling @code{View()} (see below)." msgstr "" #. type: itemize #: R-exts.texi:4207 msgid "" "Be careful with the order of entries in macros such as @code{PKG_LIBS}. " "Some linkers will re-order the entries, and behaviour can differ between " "dynamic and static libraries. Generally @option{-L} options should " "precede@footnote{Whereas the GNU linker reorders so @option{-L} options are " "processed first, the Solaris one does not.} the libraries (typically " "specified by @option{-l} options) to be found from those directories, and " "libraries are searched once in the order they are specified. Not all " "linkers allow a space after @option{-L} ." msgstr "" #. type: itemize #: R-exts.texi:4215 msgid "" "Some people have a need to set a locale. Locale names are not portable, and " "e.g.@: @samp{fr_FR.utf8} is common used on Linux but not accepted on either " "Solaris or OS X. @samp{fr_FR.UTF-8} is more portable, being accepted on " "recent Linux, AIX, FreBSD, OS X and Solaris (at least). However, some Linux " "distributions micro-package, so locales defined by @pkg{glibc} (including " "these examples) may not be installed." msgstr "" # #. type: Plain text #: R-exts.texi:4220 msgid "" "Do be careful in what your tests (and examples) actually test. Bad practice " "seen in distributed packages include:" msgstr "" # #. type: itemize #: R-exts.texi:4228 msgid "" "It is not reasonable to test the time taken by a command: you cannot know " "how fast or how heavily loaded an @R{} platform might be. At best you can " "test a ratio of times, and even that is fraught with difficulties." msgstr "" # #. type: itemize #: R-exts.texi:4232 msgid "" "Do not test the exact format of @R{} error messages: They change, and they " "can be translated." msgstr "" # #. type: itemize #: R-exts.texi:4235 msgid "" "Worse, packages have tested the exact format of system error messages, which " "are platform-dependent and perhaps locale-dependent." msgstr "" # #. type: itemize #: R-exts.texi:4239 msgid "" "If you use functions such as @code{View}, remember that in testing there is " "no one to look at the output. It is better to use something like one of" msgstr "" # #. type: example #: R-exts.texi:4242 #, no-wrap msgid "" "if(interactive()) View(obj) else print(head(obj))\n" "if(interactive()) View(obj) else str(obj)\n" msgstr "" # #. type: itemize #: R-exts.texi:4262 msgid "" "Only test the accuracy of results if you have done a formal error analysis. " "Things such as checking that probabilities numerically sum to one are silly: " "numerical tests should always have a tolerance. That the tests on your " "platform achieve a particular tolerance says little about other platforms. " "@R{} is configured by default to make use of long doubles where available, " "but they may not be available or be too slow for routine use. Most @R{} " "platforms use @cputype{ix86} or @cputype{x86_64} CPUs: these use extended " "precision registers on some but not all of their FPU instructions. Thus the " "achieved precision can depend on the compiler version and optimization " "flags---our experience is that 32-bit builds tend to be less precise than 64-" "bit ones. But not all platforms use those CPUs, and not all@footnote{Not " "doing so is the default on Windows, overridden for the @R{} executables. It " "is also the default on some Solaris compilers.} which use them configure " "them to allow the use of extended precision. In particular, ARM CPUs do not " "(currently) have extended precision nor long doubles, and long double was 64-" "bit on HP/PA Linux." msgstr "" # #. type: itemize #: R-exts.texi:4270 msgid "" "If you must try to establish a tolerance empirically, configure and build " "@R{} with @option{--disable-long-double} and use appropriate compiler flags " "(such as @option{-ffloat-store} and @option{-fexcess-precision=standard} for " "@command{gcc}, depending on the CPU type@footnote{These are not needed for " "the default compiler settings on @cputype{x86_64} but are likely to be " "needed on @cputype{ix86}.}) to mitigate the effects of extended-precision " "calculations." msgstr "" # #. type: itemize #: R-exts.texi:4273 msgid "" "Tests which involve random inputs or non-deterministic algorithms should " "normally set a seed or be tested for many seeds." msgstr "" # #. type: Plain text #: R-exts.texi:4283 msgid "" "There are a several tools available to reduce the size of PDF files: often " "the size can be reduced substantially with no or minimal loss in quality. " "Not only do large files take up space: they can stress the PDF viewer and " "take many minutes to print (if they can be printed at all)." msgstr "" #. type: Plain text #: R-exts.texi:4297 msgid "" "@command{qpdf} (@uref{http://qpdf.sourceforge.net/}) can compress " "losslessly. It is fairly readily available (e.g.@: it has binaries for " "Windows and packages in Debian/Ubuntu/Fedora, and is installed as part of " "the @acronym{CRAN} OS X distribution of @R{}). @command{R CMD build} has an " "option to run @command{qpdf} over PDF files under @file{inst/doc} and " "replace them if at least 10Kb and 10% is saved. The full path to the " "@command{qpdf} command can be supplied as environment variable @env{R_QPDF} " "(and is on the @acronym{CRAN} binary of @R{} for OS X). It seems MiKTeX " "does not use PDF object compression and so @command{qpdf} can reduce " "considerably the files it outputs: MiKTeX can be overridden by code in the " "preamble of an Sweave or @LaTeX{} file --- see how this is done for the @R{} " "reference manual at @uref{https://svn.r-project.org/@/R/@/trunk/@/doc/@/" "manual/@/refman.top}." msgstr "" # #. type: Plain text #: R-exts.texi:4306 msgid "" "Other tools can reduce the size of PDFs containing bitmap images at " "excessively high resolution. These are often best re-generated (for example " "@code{Sweave} defaults to 300 ppi, and 100--150 is more appropriate for a " "package manual). These tools include Adobe Acrobat (not Reader), Apple's " "Preview@footnote{Select `Save as', and select `Reduce file size' from the " "`Quartz filter' menu': this can be accessed in other ways, for example by " "Automator.} and Ghostscript (which converts PDF to PDF by" msgstr "" # #. type: example #: R-exts.texi:4309 #, no-wrap msgid "ps2pdf @var{options} -dAutoRotatePages=/None @var{in}.pdf @var{out}.pdf\n" msgstr "" # #. type: Plain text #: R-exts.texi:4313 msgid "and suitable options might be" msgstr "" # #. type: example #: R-exts.texi:4317 #, no-wrap msgid "" "-dPDFSETTINGS=/ebook\n" "-dPDFSETTINGS=/screen\n" msgstr "" #. type: Plain text #: R-exts.texi:4324 msgid "" "; see @uref{https://www.ghostscript.com/@/doc/@/current/@/Ps2pdf.htm} for " "more such and consider all the options for image downsampling). There have " "been examples in @acronym{CRAN} packages for which Ghostscript 9.06 and " "later produced much better reductions than 9.05 or earlier." msgstr "" # #. type: Plain text #: R-exts.texi:4328 msgid "" "We come across occasionally large PDF files containing excessively " "complicated figures using PDF vector graphics: such figures are often best " "redesigned or failing that, output as PNG files." msgstr "" # #. type: Plain text #: R-exts.texi:4333 msgid "" "Option @option{--compact-vignettes} to @command{R CMD build} defaults to " "value @samp{qpdf}: use @samp{both} to try harder to reduce the size, " "provided you have Ghostscript available (see the help for @code{tools::" "compactPDF})." msgstr "" # #. type: Plain text #: R-exts.texi:4344 msgid "" "There are several ways to find out where time is being spent in the check " "process. Start by setting the environment variable @env{_R_CHECK_TIMINGS_} " "to @samp{0}. This will report the total CPU times (not Windows) and elapsed " "times for installation and running examples, tests and vignettes, under each " "sub-architecture if appropriate. For tests and vignettes, it reports the " "time for each as well as the total." msgstr "" # #. type: Plain text #: R-exts.texi:4347 msgid "" "Setting @env{_R_CHECK_TIMINGS_} to a positive value sets a threshold (in " "seconds elapsed time) for reporting timings." msgstr "" #. type: Plain text #: R-exts.texi:4355 msgid "" "If you need to look in more detail at the timings for examples, use option " "@option{--timings} to @command{R CMD check} (this is set by @option{--as-" "cran}). This adds a summary to the check output for all the examples with " "CPU or elapsed time of more than 5 seconds. It produces a file " "@file{@var{mypkg}.Rcheck/@var{mypkg}-Ex.timings} containing timings for each " "help file: it is a tab-delimited file which can be read into @R{} for " "further analysis." msgstr "" # #. type: Plain text #: R-exts.texi:4360 msgid "" "Timings for the tests and vignette runs are given at the bottom of the " "corresponding log file: note that log files for successful vignette runs are " "only retained if environment variable " "@env{_R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_} is set to a true value." msgstr "" # #. type: Plain text #: R-exts.texi:4369 msgid "" "Care is needed if your package contains non-@acronym{ASCII} text, and in " "particular if it is intended to be used in more than one locale. It is " "possible to mark the encoding used in the @file{DESCRIPTION} file and in " "@file{.Rd} files, as discussed elsewhere in this manual." msgstr "" # #. type: Plain text #: R-exts.texi:4384 msgid "" "First, consider carefully if you really need non-@acronym{ASCII} text. Many " "users of @R{} will only be able to view correctly text in their native " "language group (e.g.@: Western European, Eastern European, Simplified " "Chinese) and @acronym{ASCII}.@footnote{except perhaps some special " "characters such as backslash and hash which may be taken over for currency " "symbols.}. Other characters may not be rendered at all, rendered " "incorrectly, or cause your @R{} code to give an error. For @file{.Rd} " "documentation, marking the encoding and including @acronym{ASCII} " "transliterations is likely to do a reasonable job. The set of characters " "which is commonly supported is wider than it used to be around 2000, but non-" "Latin alphabets (Greek, Russian, Georgian, @dots{}) are still often " "problematic and those with double-width characters (Chinese, Japanese, " "Korean) often need specialist fonts to render correctly." msgstr "" #. type: Plain text #: R-exts.texi:4388 msgid "" "Several @acronym{CRAN} packages have messages in their @R{} code in French " "(and a few in German). A better way to tackle this is to use the " "internationalization facilities discussed elsewhere in this manual." msgstr "" # #. type: Plain text #: R-exts.texi:4391 msgid "" "Function @code{showNonASCIIfile} in package @pkg{tools} can help in finding " "non-@acronym{ASCII} bytes in files." msgstr "" # #. type: Plain text #: R-exts.texi:4401 msgid "" "There is a portable way to have arbitrary text in character strings (only) " "in your @R{} code, which is to supply them in Unicode as @code{\\uxxxx} " "escapes. If there are any characters not in the current encoding the parser " "will encode the character string as UTF-8 and mark it as such. This applies " "also to character strings in datasets: they can be prepared using " "@code{\\uxxxx} escapes or encoded in UTF-8 in a UTF-8 locale, or even " "converted to UTF-8 via @samp{iconv()}. If you do this, make sure you have " "@samp{R (>= 2.10)} (or later) in the @samp{Depends} field of the " "@file{DESCRIPTION} file." msgstr "" # #. type: Plain text #: R-exts.texi:4412 msgid "" "@R{} sessions running in non-UTF-8 locales will if possible re-encode such " "strings for display (and this is done by @command{RGui} on Windows, for " "example). Suitable fonts will need to be selected or made " "available@footnote{Typically on a Unix-alike this is done by telling " "@command{fontconfig} where to find suitable fonts to select glyphs from.} " "both for the console/terminal and graphics devices such as @samp{X11()} and " "@samp{windows()}. Using @samp{postscript} or @samp{pdf} will choose a " "default 8-bit encoding depending on the language of the UTF-8 locale, and " "your users would need to be told how to select the @samp{encoding} argument." msgstr "" #. type: Plain text #: R-exts.texi:4418 msgid "" "If you want to run @command{R CMD check} on a Unix-alike over a package that " "sets a package encoding in its @file{DESCRIPTION} file @emph{and do not use " "a UTF-8 locale} you may need to specify a suitable locale @emph{via} " "environment variable @env{R_ENCODING_LOCALES}. The default is equivalent to " "the value" msgstr "" # #. type: example #: R-exts.texi:4421 #, no-wrap msgid "\"latin1=en_US:latin2=pl_PL:UTF-8=en_US.UTF-8:latin9=fr_FR.iso885915@@euro\"\n" msgstr "" #. type: Plain text #: R-exts.texi:4428 msgid "" "(which is appropriate for a system based on @code{glibc}: OS X requires " "@code{latin9=fr_FR.ISO8859-15}) except that if the current locale is UTF-8 " "then the package code is translated to UTF-8 for syntax checking, so it is " "strongly recommended to check in a UTF-8 locale." msgstr "" # #. type: Plain text #: R-exts.texi:4439 msgid "" "Writing portable C and C++ code is mainly a matter of observing the " "standards (C99, C++98 or where declared C++11) and testing that extensions " "(such as POSIX functions) are supported. However, some common errors are " "worth pointing out here. It can be helpful to look up functions at " "@uref{http://www.cplusplus.com/reference/} or @uref{http://en.cppreference." "com/w/} and compare what is defined in the various standards." msgstr "" # #. type: itemize #: R-exts.texi:4450 msgid "" "Mathematical functions such as @code{sqrt} are defined in C++ for floating-" "point arguments. It is legitimate in C++ to overload these with versions " "for types @code{float}, @code{double}, @code{long double} and possibly " "more. This means that calling @code{sqrt} on an integer type may have " "`overloading ambiguity' as it could be promoted to any of the supported " "floating-point types: this is commonly seen on Solaris, but for @code{pow} " "also seen on OS X. (C++11 requires additional overloads for integer types.)" msgstr "" # #. type: itemize #: R-exts.texi:4455 msgid "" "A not-uncommonly-seen problem is to mistakenly call @code{floor(x/y)} or " "@code{ceil(x/y)} for @code{int} arguments @code{x} and @code{y}. Since " "@code{x/y} does integer division, the result is an @code{int} and " "`overloading ambiguity' may be reported." msgstr "" #. type: itemize #: R-exts.texi:4465 msgid "" "Function @code{fabs} is defined only for floating-point types, except in C+" "+11 which has overloads for @code{std::fabs} in @file{<cmath>} for integer " "types. Function @code{abs} is defined in C99's @file{<stdlib.h>} for " "@code{int} and in C++98's @file{<cstdlib>} for integer types, overloaded in " "@file{<cmath>} for floating-point types. C++11 has additional overloads for " "@code{std::abs} in @file{<cmath>} for integer types. The effect of calling " "@code{abs} for a floating-point type is implementation-specific: it may " "truncate to an integer." msgstr "" # #. type: itemize #: R-exts.texi:4473 msgid "" "Functions/macros such as @code{isnan}, @code{isinf} and @code{isfinite} are " "not required by C++98: where compilers support them they may be only in the " "@code{std} namespace or only in the main namespace. There is no way to make " "use of these functions which works with all C++ compilers currently in use " "on @R{} platforms: use @R{}'s versions such as @code{ISNAN} and " "@code{R_FINITE} instead." msgstr "" # #. type: itemize #: R-exts.texi:4476 msgid "" "It is an error (and make little sense, although has been seen) to call these " "functions for integer arguments." msgstr "" # #. type: itemize #: R-exts.texi:4484 msgid "" "The GNU compilers have a large number of non-portable extensions. For " "example, @code{INFINITY} (which is in C99 but not C++98), for which @R{} " "provides the portable @code{R_PosInf} (and @code{R_NegInf} for @code{-" "INFINITY}). And @code{NAN} is just one NaN value: in @R{} code " "@code{NA_REAL} is usually what is intended, but @code{R_NaN} is also " "available." msgstr "" #. type: itemize #: R-exts.texi:4488 msgid "" "Some (but not all) extensions are listed at @uref{https://gcc.gnu.org/@/" "onlinedocs/@/gcc/@/C-Extensions.html} and @uref{https://gcc.gnu.org/@/" "onlinedocs/@/gcc/@/C_002b_002b-Extensions.html}." msgstr "" # #. type: itemize #: R-exts.texi:4497 msgid "" "Including C headers in C++ code is not portable. Including the C header " "@file{math.h} in C++ code often causes conflicts with @file{cmath} which may " "be included by other headers. This is particularly problematic with C++11 " "compilers, as functions like @code{sqrt} and @code{isnan} are defined for " "@code{double} arguments in @file{math.h} and for a range of types including " "@code{double} in @file{cmath}." msgstr "" # #. type: itemize #: R-exts.texi:4501 msgid "" "Variable-length arrays are C99, not supported by C++98 nor by the C++ " "compilers in use with @R{} on some platforms." msgstr "" #. type: itemize #: R-exts.texi:4511 msgid "" "Be careful to include the headers which define the functions you use. Some " "compilers/OSes include other system headers in their headers which are not " "required by the standards, and so code may compile on such systems and not " "on others. (A prominent example is the C++11 header @code{<random>} which " "is indirectly included by @code{<algorithm>} by @command{g++}. Another " "frequent issue is the C header @code{<time.h>} which is included by other " "headers on Linux and Windows but not OS X nor Solaris.)" msgstr "" # #. type: itemize #: R-exts.texi:4517 msgid "" "For C++ code, be careful to specify namespaces where needed. Many functions " "are defined by the standards to be in the @code{std} namespace, but " "@command{g++} puts many such also in the C++ main namespace. One way to do " "so is to use declarations such as" msgstr "" # #. type: example #: R-exts.texi:4519 #, no-wrap msgid "using std::floor;\n" msgstr "" #. type: itemize #: R-exts.texi:4533 msgid "" "Macros defined by the compiler/OS can cause problems. Identifiers starting " "with an underscore followed by an upper-case letter or another underscore " "are reserved for system macros and should not be used in portable code " "(including not as guards in C/C++ headers). Other macros, typically upper-" "case, may be defined by the compiler or system headers and can cause " "problems. The most common issue involves the names of the Intel CPU " "registers such as @code{CS}, @code{DS} and @code{SS} defined on i586/x64 " "Solaris in @file{<sys/regset.h>} and often included indirectly by " "@file{<stdlib.h>} and other core headers." msgstr "" #. type: Plain text #: R-exts.texi:4538 msgid "" "Some additional information for C++ is available at @uref{http://journal.r-" "project.org/@/archive/@/2011-2/@/RJournal_2011-2_Plummer.pdf} by Martyn " "Plummer." msgstr "" # #. type: Plain text #: R-exts.texi:4546 msgid "" "If you want to distribute a binary version of a package on Windows or OS X, " "there are further checks you need to do to check it is portable: it is all " "too easy to depend on external software on your own machine that other users " "will not have." msgstr "" # #. type: Plain text #: R-exts.texi:4560 msgid "" "For Windows, check what other DLLs your package's DLL depends on (`imports' " "from in the DLL tools' parlance). A convenient GUI-based tool to do so is " "`Dependency Walker' (@uref{http://www.dependencywalker.com/}) for both 32-" "bit and 64-bit DLLs -- note that this will report as missing links to @R{}'s " "own DLLs such as @file{R.dll} and @file{Rblas.dll}. For 32-bit DLLs only, " "the command-line tool @command{pedump.exe -i} (in @file{Rtools*.exe}) can be " "used, and for the brave, the @command{objdump} tool in the appropriate " "toolchain will also reveal what DLLs are imported from. If you use a " "toolchain other than one provided by the @R{} developers or use your own " "makefiles, watch out in particular for dependencies on the toolchain's " "runtime DLLs such as @file{libgfortran}, @file{libstdc++} and " "@file{libgcc_s}." msgstr "" # #. type: Plain text #: R-exts.texi:4566 msgid "" "For OS X, using @code{R CMD otool -L} on the package's shared object(s) in " "the @file{libs} directory will show what they depend on: watch for any " "dependencies in @file{/usr/local/lib}, notably @file{libgfortran.2.dylib}, " "@file{libgfortran.3.dylib} or @file{libquadmath.0.dylib}." msgstr "" # #. type: Plain text #: R-exts.texi:4571 msgid "" "Many people (including the @acronym{CRAN} package repository) will not " "accept source packages containing binary files as the latter are a security " "risk. If you want to distribute a source package which needs external " "software on Windows or OS X, options include" msgstr "" # #. type: itemize #: R-exts.texi:4575 msgid "" "To arrange for installation of the package to download the additional " "software from a URL, as e.g.@: package @CRANpkg{Cairo} does." msgstr "" #. type: itemize #: R-exts.texi:4583 msgid "" "(For @acronym{CRAN}.) To negotiate with Uwe Ligges to host the additional " "components on WinBuilder, and write a @file{configure.win} file to install " "them. There used to be many examples, e.g.@: package @CRANpkg{rgdal} " "(however nowadays @acronym{CRAN} prefers to use a uniform cross-compilation " "approach for software such as GDAL)." msgstr "" # #. type: Plain text #: R-exts.texi:4590 msgid "" "Be aware that license requirements will need to be met so you may need to " "supply the sources for the additional components (and will if your package " "has a GPL-like license)." msgstr "" # #. type: Plain text #: R-exts.texi:4600 msgid "" "Diagnostic messages can be made available for translation, so it is " "important to write them in a consistent style. Using the tools described in " "the next section to extract all the messages can give a useful overview of " "your consistency (or lack of it). Some guidelines follow." msgstr "" # #. type: itemize #: R-exts.texi:4606 msgid "" "Messages are sentence fragments, and not viewed in isolation. So it is " "conventional not to capitalize the first word and not to end with a period " "(or other punctuation)." msgstr "" # #. type: itemize #: R-exts.texi:4610 msgid "" "Try not to split up messages into small pieces. In C error messages use a " "single format string containing all English words in the messages." msgstr "" # #. type: itemize #: R-exts.texi:4614 msgid "" "In @R{} error messages do not construct a message with @code{paste} (such " "messages will not be translated) but @emph{via} multiple arguments to " "@code{stop} or @code{warning}, or @emph{via} @code{gettextf}." msgstr "" # #. type: itemize #: R-exts.texi:4617 msgid "Do not use colloquialisms such as ``can't'' and ``don't''." msgstr "" # #. type: itemize #: R-exts.texi:4620 msgid "Conventionally single quotation marks are used for quotations such as" msgstr "" # #. type: example #: R-exts.texi:4623 #, no-wrap msgid "'ord' must be a positive integer, at most the number of knots\n" msgstr "" # #. type: itemize #: R-exts.texi:4628 msgid "" "and double quotation marks when referring to an @R{} character string or a " "class, such as" msgstr "" # #. type: example #: R-exts.texi:4631 #, no-wrap msgid "'format' must be \"normal\" or \"short\" - using \"normal\"\n" msgstr "" # #. type: itemize #: R-exts.texi:4641 msgid "" "Since @acronym{ASCII} does not contain directional quotation marks, it is " "best to use @samp{'} and let the translator (including automatic " "translation) use directional quotations where available. The range of " "quotation styles is immense: unfortunately we cannot reproduce them in a " "portable @code{texinfo} document. But as a taster, some languages use `up' " "and `down' (comma) quotes rather than left or right quotes, and some use " "guillemets (and some use what Adobe calls `guillemotleft' to start and " "others use it to end)." msgstr "" # #. type: itemize #: R-exts.texi:4643 msgid "" "In @R{} messages it is also possible to use @code{sQuote} or @code{dQuote} " "as in" msgstr "" # #. type: example #: R-exts.texi:4648 #, no-wrap msgid "" "\tstop(gettextf(\"object must be of class %s or %s\",\n" "\t\t dQuote(\"manova\"), dQuote(\"maov\")),\n" "\t domain = NA)\n" msgstr "" # #. type: itemize #: R-exts.texi:4655 msgid "" "Occasionally messages need to be singular or plural (and in other languages " "there may be no such concept or several plural forms -- Slovenian has " "four). So avoid constructions such as was once used in @code{library}" msgstr "" # #. type: example #: R-exts.texi:4666 #, no-wrap msgid "" "if((length(nopkgs) > 0) && !missing(lib.loc)) @{\n" " if(length(nopkgs) > 1)\n" "\twarning(\"libraries \",\n" "\t\tpaste(sQuote(nopkgs), collapse = \", \"),\n" "\t\t\" contain no packages\")\n" " else\n" "\twarning(\"library \", paste(sQuote(nopkgs)),\n" "\t\t\" contains no package\")\n" "@}\n" msgstr "" # #. type: itemize #: R-exts.texi:4670 msgid "and was replaced by" msgstr "" # #. type: example #: R-exts.texi:4681 #, no-wrap msgid "" "if((length(nopkgs) > 0) && !missing(lib.loc)) @{\n" " pkglist <- paste(sQuote(nopkgs), collapse = \", \")\n" " msg <- sprintf(ngettext(length(nopkgs),\n" "\t\t\t \"library %s contains no packages\",\n" "\t\t\t \"libraries %s contain no packages\",\n" "\t\t\t domain = \"R-base\"),\n" "\t\t pkglist)\n" " warning(msg, domain=NA)\n" "@}\n" msgstr "" # #. type: itemize #: R-exts.texi:4688 msgid "" "Note that it is much better to have complete clauses as here, since in " "another language one might need to say `There is no package in library %s' " "or `There are no packages in libraries %s'." msgstr "" # #. type: Plain text #: R-exts.texi:4698 msgid "" "There are mechanisms to translate the @R{}- and C-level error and warning " "messages. There are only available if @R{} is compiled with NLS support " "(which is requested by @command{configure} option @option{--enable-nls}, the " "default)." msgstr "" #. type: Plain text #: R-exts.texi:4703 msgid "" "The procedures make use of @code{msgfmt} and @code{xgettext} which are part " "of @acronym{GNU} @code{gettext} and this will need to be installed: Windows " "users can find pre-compiled binaries at @uref{https://www.stats.ox.ac.uk/@/" "pub/@/Rtools/@/goodies/@/gettext-tools.zip}." msgstr "" # #. type: node #: R-exts.texi:4708 #: R-exts.texi:4710 #: R-exts.texi:4711 #: R-exts.texi:4768 #, no-wrap msgid "C-level messages" msgstr "" # #. type: node #: R-exts.texi:4708 #: R-exts.texi:4710 #: R-exts.texi:4768 #: R-exts.texi:4769 #: R-exts.texi:4795 #, no-wrap msgid "R messages" msgstr "" # #. type: subsection #: R-exts.texi:4708 #: R-exts.texi:4768 #: R-exts.texi:4795 #: R-exts.texi:4796 #, no-wrap msgid "Preparing translations" msgstr "" # #. type: Plain text #: R-exts.texi:4714 msgid "The process of enabling translations is" msgstr "" # #. type: itemize #: R-exts.texi:4719 msgid "" "In a header file that will be included in all the C (or C++ or Objective C/C+" "+) files containing messages that should be translated, declare" msgstr "" # #. type: example #: R-exts.texi:4722 #, no-wrap msgid "" "#include <R.h> /* to include Rconfig.h */\n" "\n" msgstr "" # #. type: example #: R-exts.texi:4730 #, no-wrap msgid "" "#ifdef ENABLE_NLS\n" "#include <libintl.h>\n" "#define _(String) dgettext (\"@var{pkg}\", String)\n" "/* replace @var{pkg} as appropriate */\n" "#else\n" "#define _(String) (String)\n" "#endif\n" msgstr "" # #. type: itemize #: R-exts.texi:4735 msgid "" "For each message that should be translated, wrap it in @code{_(...)}, for " "example" msgstr "" # #. type: example #: R-exts.texi:4738 #, no-wrap msgid "error(_(\"'ord' must be a positive integer\"));\n" msgstr "" # #. type: itemize #: R-exts.texi:4742 msgid "" "If you want to use different messages for singular and plural forms, you " "need to add" msgstr "" # #. type: example #: R-exts.texi:4747 #, no-wrap msgid "" "#ifndef ENABLE_NLS\n" "#define dngettext(pkg, String, StringP, N) (N > 1 ? StringP : String)\n" "#endif\n" msgstr "" # #. type: itemize #: R-exts.texi:4751 msgid "and mark strings by" msgstr "" # #. type: example #: R-exts.texi:4754 #, no-wrap msgid "dngettext((\"@var{pkg}\", @var{<singular string>}, @var{<plural string>}, n)\n" msgstr "" # #. type: itemize #: R-exts.texi:4758 msgid "In the package's @file{src} directory run" msgstr "" # #. type: example #: R-exts.texi:4761 #, no-wrap msgid "xgettext --keyword=_ -o @var{pkg}.pot *.c\n" msgstr "" # #. type: Plain text #: R-exts.texi:4767 msgid "" "The file @file{src/@var{pkg}.pot} is the template file, and conventionally " "this is shipped as @file{po/@var{pkg}.pot}." msgstr "" # #. type: Plain text #: R-exts.texi:4779 msgid "" "Mechanisms are also available to support the automatic translation of @R{} " "@code{stop}, @code{warning} and @code{message} messages. They make use of " "message catalogs in the same way as C-level messages, but using domain " "@code{R-@var{pkg}} rather than @code{@var{pkg}}. Translation of character " "strings inside @code{stop}, @code{warning} and @code{message} calls is " "automatically enabled, as well as other messages enclosed in calls to " "@code{gettext} or @code{gettextf}. (To suppress this, use argument " "@code{domain=NA}.)" msgstr "" # #. type: Plain text #: R-exts.texi:4787 msgid "" "Tools to prepare the @file{R-@var{pkg}.pot} file are provided in package " "@pkg{tools}: @code{xgettext2pot} will prepare a file from all strings " "occurring inside @code{gettext}/@code{gettextf}, @code{stop}, @code{warning} " "and @code{message} calls. Some of these are likely to be spurious and so " "the file is likely to need manual editing. @code{xgettext} extracts the " "actual calls and so is more useful when tidying up error messages." msgstr "" # #. type: Plain text #: R-exts.texi:4793 msgid "" "The @R{} function @code{ngettext} provides an interface to the C function of " "the same name: see example in the previous section. It is safest to use " "@code{domain=\"R-@var{pkg}\"} explicitly in calls to @code{ngettext}, and " "necessary for earlier versions of @R{} unless they are calls directly from a " "function in the package." msgstr "" # #. type: Plain text #: R-exts.texi:4803 msgid "" "Once the template files have been created, translations can be made. " "Conventional translations have file extension @file{.po} and are placed in " "the @file{po} subdirectory of the package with a name that is either " "@samp{@var{ll}.po} or @samp{R-@var{ll}.po} for translations of the C and " "@R{} messages respectively to language with code @samp{@var{ll}}." msgstr "" # #. type: ifset #: R-exts.texi:4807 msgid "" "@xref{Localization of messages, , Localization of messages, R-admin, R " "Installation and Administration}, for details of language codes." msgstr "" # #. type: ifclear #: R-exts.texi:4811 msgid "" "See `Localization of messages' in `R Installation and Administration', for " "details of language codes." msgstr "" # #. type: Plain text #: R-exts.texi:4816 msgid "" "There is an @R{} function, @code{update_pkg_po} in package @pkg{tools}, to " "automate much of the maintenance of message translations. See its help for " "what it does in detail." msgstr "" # #. type: Plain text #: R-exts.texi:4823 msgid "" "If this is called on a package with no existing translations, it creates the " "directory @file{@var{pkgdir}/po}, creates a template file of @R{} messages, " "@file{@var{pkgdir}/po/R-@var{pkg}.pot}, within it, creates the " "@samp{en@@quot} translation and installs that. (The @samp{en@@quot} pseudo-" "language interprets quotes in their directional forms in suitable (e.g.@: " "UTF-8) locales.)" msgstr "" # #. type: Plain text #: R-exts.texi:4826 msgid "" "If the package has C source files in its @file{src} directory that are " "marked for translation, use" msgstr "" # #. type: example #: R-exts.texi:4829 #, no-wrap msgid "touch @var{pkgdir}/po/@var{pkg}.pot\n" msgstr "" # #. type: Plain text #: R-exts.texi:4834 msgid "" "to create a dummy template file, then call @code{update_pkg_po} again (this " "can also be done before it is called for the first time)." msgstr "" # #. type: Plain text #: R-exts.texi:4838 msgid "" "When translations to new languages are added in the @file{@var{pkgdir}/po} " "directory, running the same command will check and then install the " "translations." msgstr "" # #. type: Plain text #: R-exts.texi:4845 msgid "" "If the package sources are updated, the same command will update the " "template files, merge the changes into the translation @file{.po} files and " "then installed the updated translations. You will often see that merging " "marks translations as `fuzzy' and this is reported in the coverage " "statistics. As fuzzy translations are @emph{not} used, this is an " "indication that the translation files need human attention." msgstr "" # #. type: Plain text #: R-exts.texi:4849 msgid "" "The merged translations are run through @code{tools::checkPofile} to check " "that C-style formats are used correctly: if not the mismatches are reported " "and the broken translations are not installed." msgstr "" # #. type: Plain text #: R-exts.texi:4852 msgid "" "This function needs the GNU @command{gettext-tools} installed and on the " "path: see its help page." msgstr "" #. type: Plain text #: R-exts.texi:4862 msgid "" "An installed file named @file{CITATION} will be used by the " "@code{citation()} function. (It should be in the @file{inst} subdirectory " "of the package sources.)" msgstr "" # #. type: Plain text #: R-exts.texi:4871 msgid "" "The @file{CITATION} file is parsed as @R{} code (in the package's declared " "encoding, or in @acronym{ASCII} if none is declared). If no such file is " "present, @code{citation} auto-generates citation information from the " "package @file{DESCRIPTION} metadata, and an example of what that would look " "like as a @file{CITATION} file can be seen in recommended package " "@CRANpkg{nlme} (see below): recommended packages @CRANpkg{boot}, " "@CRANpkg{cluster} and @CRANpkg{mgcv} have further examples." msgstr "" # #. type: Plain text #: R-exts.texi:4873 msgid "A @file{CITATION} file will contain calls to function @code{bibentry}." msgstr "" # #. type: Plain text #: R-exts.texi:4875 msgid "Here is that for @CRANpkg{nlme}:" msgstr "" # #. type: example #: R-exts.texi:4879 #, no-wrap msgid "" "year <- sub(\"-.*\", \"\", meta$Date)\n" "note <- sprintf(\"R package version %s\", meta$Version)\n" "\n" msgstr "" #. type: example #: R-exts.texi:4890 #, no-wrap msgid "" "bibentry(bibtype = \"Manual\",\n" " title = \"@{nlme@}: Linear and Nonlinear Mixed Effects Models\",\n" " author = c(person(\"Jose\", \"Pinheiro\"),\n" " person(\"Douglas\", \"Bates\"),\n" " person(\"Saikat\", \"DebRoy\"),\n" " person(\"Deepayan\", \"Sarkar\"),\n" " person(\"R Core Team\")),\n" " year = year,\n" " note = note,\n" " url = \"https://CRAN.R-project.org/package=nlme\")\n" msgstr "" #. type: Plain text #: R-exts.texi:4900 msgid "" "Note the way that information that may need to be updated is picked up from " "object @code{meta}, a parsed version of the @file{DESCRIPTION} " "file@footnote{this object is available since @R{} 2.8.0, so the " "@samp{Depends} field in the @file{DESCRIPTION} file should contain something " "at least as restrictive as @samp{R (>= 2.8}.} -- it is tempting to hardcode " "such information, but it normally then gets outdated. See @code{?bibentry} " "for further details of the information which can be provided." msgstr "" # #. type: Plain text #: R-exts.texi:4906 msgid "" "In case a bibentry contains @LaTeX{} markup (e.g., for accented characters " "or mathematical symbols), it may be necessary to provide a text " "representation to be used for printing via the @code{textVersion} argument " "to @code{bibentry}. E.g., earlier versions of @CRANpkg{nlme} additionally " "used" msgstr "" # #. type: example #: R-exts.texi:4914 #, no-wrap msgid "" " textVersion =\n" " paste0(\"Jose Pinheiro, Douglas Bates, Saikat DebRoy,\",\n" " \"Deepayan Sarkar and the R Core Team (\",\n" " year,\n" " \"). nlme: Linear and Nonlinear Mixed Effects Models. \",\n" " note, \".\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:4918 msgid "" "The @file{CITATION} file should itself produce no output when @code{source}-" "d." msgstr "" #. type: Plain text #: R-exts.texi:4923 msgid "" "It is desirable (and essential for @acronym{CRAN}) that the @file{CITATION} " "file does not contain calls to functions such as @code{packageDescription} " "which assume the package is installed in a library tree on the package " "search path." msgstr "" # #. type: Plain text #: R-exts.texi:4931 msgid "" "The @file{DESCRIPTION} file has an optional field @code{Type} which if " "missing is assumed to be @samp{Package}, the sort of extension discussed so " "far in this chapter. Currently one other type is recognized; there used " "also to be a @samp{Translation} type." msgstr "" # #. type: subsection #: R-exts.texi:4934 #: R-exts.texi:4936 #: R-exts.texi:4937 #, no-wrap msgid "Frontend" msgstr "" # #. type: Plain text #: R-exts.texi:4946 msgid "" "This is a rather general mechanism, designed for adding new front-ends such " "as the former @pkg{gnomeGUI} package (see the @file{Archive} area on " "@acronym{CRAN}). If a @file{configure} file is found in the top-level " "directory of the package it is executed, and then if a @file{Makefile} is " "found (often generated by @file{configure}), @code{make} is called. If " "@code{R CMD INSTALL --clean} is used @code{make clean} is called. No other " "action is taken." msgstr "" # #. type: Plain text #: R-exts.texi:4949 msgid "" "@code{R CMD build} can package up this type of extension, but @code{R CMD " "check} will check the type and skip it." msgstr "" # #. type: Plain text #: R-exts.texi:4952 msgid "" "Many packages of this type need write permission for the @R{} installation " "directory." msgstr "" # #. type: Plain text #: R-exts.texi:4959 msgid "" "Several members of the @R{} project have set up services to assist those " "writing @R{} packages, particularly those intended for public distribution." msgstr "" # #. type: Plain text #: R-exts.texi:4963 msgid "" "@uref{http://win-builder.r-project.org, win-builder.r-project.org} offers " "the automated preparation of (32/64-bit) Windows binaries from well-tested " "source packages." msgstr "" #. type: Plain text #: R-exts.texi:4974 msgid "" "R-Forge (@uref{https://R-Forge.r-project.org, R-Forge.r-project.org}) and " "RForge (@uref{https://www.rforge.net, www.rforge.net}) are similar services " "with similar names. Both provide source-code management through SVN, daily " "building and checking, mailing lists and a repository that can be accessed " "@emph{via} @code{install.packages} (they can be selected by " "@code{setRepositories} and the GUI menus that use it). Package developers " "have the opportunity to present their work on the basis of project websites " "or news announcements. Mailing lists, forums or wikis provide useRs with " "convenient instruments for discussions and for exchanging information " "between developers and/or interested useRs." msgstr "" # #. type: cindex #: R-exts.texi:4978 #, no-wrap msgid "Documentation, writing" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:4999 #: R-exts.texi:5000 #: R-exts.texi:5126 #: R-exts.texi:5472 #: R-exts.texi:5545 #: R-exts.texi:5599 #: R-exts.texi:5626 #, no-wrap msgid "Rd format" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:4999 #: R-exts.texi:5626 #: R-exts.texi:5627 #: R-exts.texi:5667 #, no-wrap msgid "Sectioning" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:5626 #: R-exts.texi:5667 #: R-exts.texi:5668 #: R-exts.texi:5815 #, no-wrap msgid "Marking text" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:5667 #: R-exts.texi:5815 #: R-exts.texi:5816 #: R-exts.texi:5875 #, no-wrap msgid "Lists and tables" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:5815 #: R-exts.texi:5875 #: R-exts.texi:5876 #: R-exts.texi:5927 #, no-wrap msgid "Cross-references" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:5875 #: R-exts.texi:5927 #: R-exts.texi:5928 #: R-exts.texi:5991 #, no-wrap msgid "Mathematics" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:5927 #: R-exts.texi:5991 #: R-exts.texi:5992 #: R-exts.texi:6033 #, no-wrap msgid "Figures" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:5991 #: R-exts.texi:6033 #: R-exts.texi:6034 #: R-exts.texi:6079 #, no-wrap msgid "Insertions" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:6033 #: R-exts.texi:6079 #: R-exts.texi:6080 #: R-exts.texi:6081 #: R-exts.texi:6115 #, no-wrap msgid "Indices" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:6079 #: R-exts.texi:6115 #: R-exts.texi:6152 #, no-wrap msgid "Platform-specific sections" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:6115 #: R-exts.texi:6152 #: R-exts.texi:6153 #: R-exts.texi:6186 #, no-wrap msgid "Conditional text" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:6152 #: R-exts.texi:6186 #: R-exts.texi:6187 #: R-exts.texi:6286 #, no-wrap msgid "Dynamic pages" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:6186 #: R-exts.texi:6286 #: R-exts.texi:6287 #: R-exts.texi:6371 #, no-wrap msgid "User-defined macros" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:6286 #: R-exts.texi:6371 #: R-exts.texi:6372 #: R-exts.texi:6437 #, no-wrap msgid "Encoding" msgstr "" # #. type: node #: R-exts.texi:4997 #: R-exts.texi:6371 #: R-exts.texi:6437 #: R-exts.texi:6438 #: R-exts.texi:6474 #, no-wrap msgid "Processing documentation files" msgstr "" # #. type: cindex #: R-exts.texi:4997 #: R-exts.texi:6437 #: R-exts.texi:6474 #: R-exts.texi:6475 #: R-exts.texi:6476 #, no-wrap msgid "Editing Rd files" msgstr "" # #. type: Plain text #: R-exts.texi:5009 msgid "" "@R{} objects are documented in files written in ``@R{} documentation'' (Rd) " "format, a simple markup language much of which closely resembles (La)@TeX{}, " "which can be processed into a variety of formats, including @LaTeX{}, " "@HTML{} and plain text. The translation is carried out by functions in the " "@pkg{tools} package called by the script @command{Rdconv} in " "@file{@var{R_HOME}/bin} and by the installation scripts for packages." msgstr "" # #. type: Plain text #: R-exts.texi:5015 msgid "" "The @R{} distribution contains more than 1300 such files which can be found " "in the @file{src/library/@var{pkg}/man} directories of the @R{} source tree, " "where @var{pkg} stands for one of the standard packages which are included " "in the @R{} distribution." msgstr "" # #. type: Plain text #: R-exts.texi:5019 msgid "" "As an example, let us look at a simplified version of @file{src/library/base/" "man/load.Rd} which documents the @R{} function @code{load}." msgstr "" # #. type: smallexample #: R-exts.texi:5046 #, no-wrap msgid "" "% File src/library/base/man/load.Rd\n" "\\name@{load@}\n" "\\alias@{load@}\n" "\\title@{Reload Saved Datasets@}\n" "\\description@{\n" " Reload the datasets written to a file with the function\n" " \\code@{save@}.\n" "@}\n" "\\usage@{\n" "load(file, envir = parent.frame())\n" "@}\n" "\\arguments@{\n" " \\item@{file@}@{a connection or a character string giving the\n" " name of the file to load.@}\n" " \\item@{envir@}@{the environment where the data should be\n" " loaded.@}\n" "@}\n" "\\seealso@{\n" " \\code@{\\link@{save@}@}.\n" "@}\n" "\\examples@{\n" "## save all data\n" "save(list = ls(), file= \"all.RData\")\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:5049 #, no-wrap msgid "" "## restore the saved values to the current environment\n" "load(\"all.RData\")\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:5054 #, no-wrap msgid "" "## restore the saved values to the workspace\n" "load(\"all.RData\", .GlobalEnv)\n" "@}\n" "\\keyword@{file@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:5065 msgid "" "An @file{Rd} file consists of three parts. The header gives basic " "information about the name of the file, the topics documented, a title, a " "short textual description and @R{} usage information for the objects " "documented. The body gives further information (for example, on the " "function's arguments and return value, as in the above example). Finally, " "there is an optional footer with keyword information. The header is " "mandatory." msgstr "" # #. type: Plain text #: R-exts.texi:5072 msgid "" "Information is given within a series of @emph{sections} with standard names " "(and user-defined sections are also allowed). Unless otherwise " "specified@footnote{e.g.@: @code{\\alias}, @code{\\keyword} and @code{\\note} " "sections.} these should occur only once in an @file{Rd} file (in any order), " "and the processing software will retain only the first occurrence of a " "standard section in the file, with a warning." msgstr "" #. type: Plain text #: R-exts.texi:5076 msgid "" "See @uref{https://developer.r-project.org/Rds.html, ``Guidelines for Rd " "files''} for guidelines for writing documentation in @file{Rd} format which " "should be useful for package writers." msgstr "" # #. type: findex #: R-exts.texi:5076 #, no-wrap msgid "prompt" msgstr "" # #. type: Plain text #: R-exts.texi:5084 msgid "" "The @R{} generic function @code{prompt} is used to construct a bare-bones " "@file{Rd} file ready for manual editing. Methods are defined for " "documenting functions (which fill in the proper function and argument names) " "and data frames. There are also functions @code{promptData}, " "@code{promptPackage}, @code{promptClass}, and @code{promptMethods} for other " "types of @file{Rd} file." msgstr "" #. type: Plain text #: R-exts.texi:5088 msgid "" "The general syntax of @file{Rd} files is summarized below. For a detailed " "technical discussion of current @file{Rd} syntax, see @uref{https://" "developer.r-project.org/parseRd.pdf, ``Parsing Rd files''}." msgstr "" #. type: Plain text #: R-exts.texi:5103 msgid "" "@file{Rd} files consist of four types of text input. The most common is " "@LaTeX{}-like, with the backslash used as a prefix on markup (e.g. " "@code{\\alias}), and braces used to indicate arguments (e.g. " "@code{@{load@}}). The least common type of text is `verbatim' text, where " "no markup other than the comment marker (@code{%}) is processed. There is " "also a rare variant of `verbatim' text (used in @code{\\eqn}, @code{\\deqn}, " "@code{\\figure}, and @code{\\newcommand}) where comment markers need not be " "escaped. The final type is @R{}-like, intended for @R{} code, but allowing " "some embedded macros. Quoted strings within @R{}-like text are handled " "specially: regular character escapes such as @code{\\n} may be entered as-" "is. Only markup starting with @code{\\l} (e.g. @code{\\link}) or " "@code{\\v} (e.g. @code{\\var}) will be recognized within quoted strings. " "The rarely used vertical tab @code{\\v} must be entered as @code{\\\\v}." msgstr "" #. type: Plain text #: R-exts.texi:5111 msgid "" "Each macro defines the input type for its argument. For example, the file " "initially uses @LaTeX{}-like syntax, and this is also used in the " "@code{\\description} section, but the @code{\\usage} section uses @R{}-like " "syntax, and the @code{\\alias} macro uses `verbatim' syntax. Comments run " "from a percent symbol @code{%} to the end of the line in all types of text " "except the rare `verbatim' variant (as on the first line of the @code{load} " "example)." msgstr "" #. type: Plain text #: R-exts.texi:5118 msgid "" "Because backslashes, braces and percent symbols have special meaning, to " "enter them into text sometimes requires escapes using a backslash. In " "general balanced braces do not need to be escaped, but percent symbols " "always do, except in the `verbatim' variant. For the complete list of " "macros and rules for escapes, see @uref{https://developer.r-project.org/" "parseRd.pdf, ``Parsing Rd files''}." msgstr "" # #. type: node #: R-exts.texi:5124 #: R-exts.texi:5126 #: R-exts.texi:5127 #: R-exts.texi:5472 #, no-wrap msgid "Documenting functions" msgstr "" # #. type: node #: R-exts.texi:5124 #: R-exts.texi:5126 #: R-exts.texi:5472 #: R-exts.texi:5473 #: R-exts.texi:5545 #, no-wrap msgid "Documenting data sets" msgstr "" # #. type: node #: R-exts.texi:5124 #: R-exts.texi:5472 #: R-exts.texi:5545 #: R-exts.texi:5546 #: R-exts.texi:5599 #, no-wrap msgid "Documenting S4 classes and methods" msgstr "" # #. type: subsection #: R-exts.texi:5124 #: R-exts.texi:5545 #: R-exts.texi:5599 #: R-exts.texi:5600 #, no-wrap msgid "Documenting packages" msgstr "" # #. type: Plain text #: R-exts.texi:5131 msgid "" "The basic markup commands used for documenting @R{} objects (in particular, " "functions) are given in this subsection." msgstr "" # #. type: item #: R-exts.texi:5133 #, no-wrap msgid "\\name@{@var{name}@}" msgstr "" # #. type: findex #: R-exts.texi:5134 #, no-wrap msgid "\\name" msgstr "" # #. type: table #: R-exts.texi:5151 msgid "" "@var{name} typically@footnote{There can be exceptions: for example @file{Rd} " "files are not allowed to start with a dot, and have to be uniquely named on " "a case-insensitive file system.} is the basename of the @file{Rd} file " "containing the documentation. It is the ``name'' of the @file{Rd} object " "represented by the file and has to be unique in a package. To avoid " "problems with indexing the package manual, it may not contain @samp{!} " "@samp{|} nor @samp{@@}, and to avoid possible problems with the @HTML{} help " "system it should not contain @samp{/} nor a space. (@LaTeX{} special " "characters are allowed, but may not be collated correctly in the index.) " "There can only be one @code{\\name} entry in a file, and it must not contain " "any markup. Entries in the package manual will be in alphabetic@footnote{in " "the current locale, and with special treatment for @LaTeX{} special " "characters and with any @samp{@var{pkgname}-package} topic moved to the top " "of the list.} order of the @code{\\name} entries." msgstr "" # #. type: item #: R-exts.texi:5152 #, no-wrap msgid "\\alias@{@var{topic}@}" msgstr "" # #. type: findex #: R-exts.texi:5153 #, no-wrap msgid "\\alias" msgstr "" # #. type: table #: R-exts.texi:5160 msgid "" "The @code{\\alias} sections specify all ``topics'' the file documents. This " "information is collected into index data bases for lookup by the on-line " "(plain text and @HTML{}) help systems. The @var{topic} can contain spaces, " "but (for historical reasons) leading and trailing spaces will be stripped. " "Percent and left brace need to be escaped by a backslash." msgstr "" # #. type: table #: R-exts.texi:5166 msgid "" "There may be several @code{\\alias} entries. Quite often it is convenient " "to document several @R{} objects in one file. For example, file " "@file{Normal.Rd} documents the density, distribution function, quantile " "function and generation of random variates for the normal distribution, and " "hence starts with" msgstr "" # #. type: group #: R-exts.texi:5175 #, no-wrap msgid "" "\\name@{Normal@}\n" "\\alias@{Normal@}\n" "\\alias@{dnorm@}\n" "\\alias@{pnorm@}\n" "\\alias@{qnorm@}\n" "\\alias@{rnorm@}\n" msgstr "" # #. type: table #: R-exts.texi:5182 msgid "" "Also, it is often convenient to have several different ways to refer to an " "@R{} object, and an @code{\\alias} does not need to be the name of an object." msgstr "" # #. type: table #: R-exts.texi:5186 msgid "" "Note that the @code{\\name} is not necessarily a topic documented, and if so " "desired it needs to have an explicit @code{\\alias} entry (as in this " "example)." msgstr "" # #. type: item #: R-exts.texi:5187 #, no-wrap msgid "\\title@{@var{Title}@}" msgstr "" # #. type: findex #: R-exts.texi:5188 #, no-wrap msgid "\\title" msgstr "" # #. type: table #: R-exts.texi:5192 msgid "" "Title information for the @file{Rd} file. This should be capitalized and " "not end in a period; try to limit its length to at most 65 characters for " "widest compatibility." msgstr "" # #. type: table #: R-exts.texi:5195 msgid "" "Markup is supported in the text, but use of characters other than English " "text and punctuation (e.g., @samp{<}) may limit portability." msgstr "" # #. type: table #: R-exts.texi:5197 msgid "There must be one (and only one) @code{\\title} section in a help file." msgstr "" # #. type: item #: R-exts.texi:5198 #, no-wrap msgid "\\description@{@dots{}@}" msgstr "" # #. type: findex #: R-exts.texi:5199 #, no-wrap msgid "\\description" msgstr "" # #. type: table #: R-exts.texi:5204 msgid "" "A short description of what the function(s) do(es) (one paragraph, a few " "lines only). (If a description is too long and cannot easily be shortened, " "the file probably tries to document too much at once.) This is mandatory " "except for package-overview files." msgstr "" # #. type: item #: R-exts.texi:5205 #, no-wrap msgid "\\usage@{@var{fun}(@var{arg1}, @var{arg2}, @dots{})@}" msgstr "" # #. type: findex #: R-exts.texi:5206 #, no-wrap msgid "\\usage" msgstr "" # #. type: table #: R-exts.texi:5210 msgid "" "One or more lines showing the synopsis of the function(s) and variables " "documented in the file. These are set in typewriter font. This is an @R{}-" "like command." msgstr "" # #. type: table #: R-exts.texi:5214 msgid "" "The usage information specified should match the function definition " "@emph{exactly} (such that automatic checking for consistency between code " "and documentation is possible)." msgstr "" # #. type: table #: R-exts.texi:5221 msgid "" "It is no longer advisable to use @code{\\synopsis} for the actual synopsis " "and show modified synopses in the @code{\\usage}. Support for " "@code{\\synopsis} will be removed in \\R 3.1.0. To indicate that a function " "can be used in several different ways, depending on the named arguments " "specified, use section @code{\\details}. E.g., @file{abline.Rd} contains" msgstr "" # #. type: group #: R-exts.texi:5229 #, no-wrap msgid "" "\\details@{\n" " Typical usages are\n" "\\preformatted@{abline(a, b, untf = FALSE, \\dots)\n" "......\n" "@}\n" msgstr "" # #. type: findex #: R-exts.texi:5232 #, no-wrap msgid "\\method" msgstr "" # #. type: table #: R-exts.texi:5239 msgid "" "Use @code{\\method@{@var{generic}@}@{@var{class}@}} to indicate the name of " "an S3 method for the generic function @var{generic} for objects inheriting " "from class @code{\"@var{class}\"}. In the printed versions, this will come " "out as @var{generic} (reflecting the understanding that methods should not " "be invoked directly but @emph{via} method dispatch), but @code{codoc()} and " "other QC tools always have access to the full name." msgstr "" # #. type: table #: R-exts.texi:5241 msgid "For example, @file{print.ts.Rd} contains" msgstr "" # #. type: group #: R-exts.texi:5247 #, no-wrap msgid "" "\\usage@{\n" "\\method@{print@}@{ts@}(x, calendar, \\dots)\n" "@}\n" msgstr "" # #. type: table #: R-exts.texi:5252 #: R-exts.texi:5288 msgid "which will print as" msgstr "" # #. type: group #: R-exts.texi:5256 #: R-exts.texi:5292 #, no-wrap msgid "" "Usage:\n" "\n" msgstr "" # #. type: group #: R-exts.texi:5259 #, no-wrap msgid "" " ## S3 method for class 'ts':\n" " print(x, calendar, ...)\n" msgstr "" # #. type: table #: R-exts.texi:5269 msgid "" "Usage for replacement functions should be given in the style of @code{dim(x) " "<- value} rather than explicitly indicating the name of the replacement " "function (@w{@code{\"dim<-\"}} in the above). Similarly, one can use " "@code{\\method@{@var{generic}@}@{@var{class}@}(@var{arglist}) <- value} to " "indicate the usage of an S3 replacement method for the generic replacement " "function @code{\"@var{generic}<-\"} for objects inheriting from class " "@code{\"@var{class}\"}." msgstr "" # #. type: table #: R-exts.texi:5275 msgid "" "Usage for S3 methods for extracting or replacing parts of an object, S3 " "methods for members of the Ops group, and S3 methods for user-defined " "(binary) infix operators (@samp{%@var{xxx}%}) follows the above rules, using " "the appropriate function names. E.g., @file{Extract.factor.Rd} contains" msgstr "" # #. type: group #: R-exts.texi:5283 #, no-wrap msgid "" "\\usage@{\n" "\\method@{[@}@{factor@}(x, \\dots, drop = FALSE)\n" "\\method@{[[@}@{factor@}(x, \\dots)\n" "\\method@{[@}@{factor@}(x, \\dots) <- value\n" "@}\n" msgstr "" # #. type: group #: R-exts.texi:5299 #, no-wrap msgid "" " ## S3 method for class 'factor':\n" " x[..., drop = FALSE]\n" " ## S3 method for class 'factor':\n" " x[[...]]\n" " ## S3 replacement method for class 'factor':\n" " x[...] <- value\n" msgstr "" # #. type: findex #: R-exts.texi:5302 #, no-wrap msgid "\\S3method" msgstr "" # #. type: table #: R-exts.texi:5304 msgid "@code{\\S3method} is accepted as an alternative to @code{\\method}." msgstr "" # #. type: item #: R-exts.texi:5305 #, no-wrap msgid "\\arguments@{@dots{}@}" msgstr "" # #. type: findex #: R-exts.texi:5306 #, no-wrap msgid "\\arguments" msgstr "" # #. type: table #: R-exts.texi:5308 msgid "Description of the function's arguments, using an entry of the form" msgstr "" # #. type: example #: R-exts.texi:5311 #, no-wrap msgid "\\item@{@var{arg_i}@}@{@var{Description of arg_i}.@}\n" msgstr "" # #. type: table #: R-exts.texi:5317 msgid "" "no whitespace between the three parts of the entry.) There may be optional " "text outside the @code{\\item} entries, for example to give general " "information about groups of parameters." msgstr "" # #. type: item #: R-exts.texi:5319 #, no-wrap msgid "\\details@{@dots{}@}" msgstr "" # #. type: findex #: R-exts.texi:5320 #, no-wrap msgid "\\details" msgstr "" # #. type: table #: R-exts.texi:5324 msgid "" "A detailed if possible precise description of the functionality provided, " "extending the basic information in the @code{\\description} slot." msgstr "" # #. type: item #: R-exts.texi:5325 #, no-wrap msgid "\\value@{@dots{}@}" msgstr "" # #. type: findex #: R-exts.texi:5326 #, no-wrap msgid "\\value" msgstr "" # #. type: table #: R-exts.texi:5328 msgid "Description of the function's return value." msgstr "" # #. type: table #: R-exts.texi:5331 msgid "" "If a list with multiple values is returned, you can use entries of the form" msgstr "" # #. type: example #: R-exts.texi:5334 #, no-wrap msgid "\\item@{@var{comp_i}@}@{@var{Description of comp_i}.@}\n" msgstr "" # #. type: table #: R-exts.texi:5343 msgid "" "for each component of the list returned. Optional text may " "precede@footnote{Text between or after list items is discouraged.} this list " "(see for example the help for @code{rle}). Note that @code{\\value} is " "implicitly a @code{\\describe} environment, so that environment should not " "be used for listing components, just individual @code{\\item@{@}@{@}} " "entries." msgstr "" # #. type: item #: R-exts.texi:5344 #, no-wrap msgid "\\references@{@dots{}@}" msgstr "" # #. type: findex #: R-exts.texi:5345 #, no-wrap msgid "\\references" msgstr "" # #. type: table #: R-exts.texi:5348 msgid "" "A section with references to the literature. Use @code{\\url@{@}} or " "@code{\\href@{@}@{@}} for web pointers." msgstr "" # #. type: item #: R-exts.texi:5349 #, no-wrap msgid "\\note@{...@}" msgstr "" # #. type: findex #: R-exts.texi:5350 #, no-wrap msgid "\\note" msgstr "" # #. type: table #: R-exts.texi:5353 msgid "" "Use this for a special note you want to have pointed out. Multiple " "@code{\\note} sections are allowed, but might be confusing to the end users." msgstr "" # #. type: table #: R-exts.texi:5355 msgid "For example, @file{pie.Rd} contains" msgstr "" # #. type: group #: R-exts.texi:5364 #, no-wrap msgid "" "\\note@{\n" " Pie charts are a very bad way of displaying information.\n" " The eye is good at judging linear measures and bad at\n" " judging relative areas.\n" " ......\n" "@}\n" msgstr "" # #. type: item #: R-exts.texi:5367 #, no-wrap msgid "\\author@{@dots{}@}" msgstr "" # #. type: findex #: R-exts.texi:5368 #, no-wrap msgid "\\author" msgstr "" # #. type: table #: R-exts.texi:5373 msgid "" "Information about the author(s) of the @file{Rd} file. Use " "@code{\\email@{@}} without extra delimiters (such as @samp{( )} or @samp{< " ">}) to specify email addresses, or @code{\\url@{@}} or @code{\\href@{@}@{@}} " "for web pointers." msgstr "" # #. type: item #: R-exts.texi:5374 #, no-wrap msgid "\\seealso@{@dots{}@}" msgstr "" # #. type: findex #: R-exts.texi:5375 #, no-wrap msgid "\\seealso" msgstr "" # #. type: table #: R-exts.texi:5380 msgid "" "Pointers to related @R{} objects, using @code{\\code@{\\link@{...@}@}} to " "refer to them (@code{\\code} is the correct markup for @R{} object names, " "and @code{\\link} produces hyperlinks in output formats which support this. " "@xref{Marking text}, and @ref{Cross-references})." msgstr "" # #. type: findex #: R-exts.texi:5381 #, no-wrap msgid "\\examples" msgstr "" # #. type: item #: R-exts.texi:5382 #, no-wrap msgid "\\examples@{@dots{}@}" msgstr "" # #. type: table #: R-exts.texi:5386 msgid "" "Examples of how to use the function. Code in this section is set in " "typewriter font without reformatting and is run by @code{example()} unless " "marked otherwise (see below)." msgstr "" # #. type: table #: R-exts.texi:5392 msgid "" "Examples are not only useful for documentation purposes, but also provide " "test code used for diagnostic checking of @R{} code. By default, text " "inside @code{\\examples@{@}} will be displayed in the output of the help " "page and run by @code{example()} and by @code{R CMD check}. You can use " "@code{\\dontrun@{@}}" msgstr "" # #. type: findex #: R-exts.texi:5392 #, no-wrap msgid "\\dontrun" msgstr "" # #. type: table #: R-exts.texi:5395 msgid "" "for text that should only be shown, but not run, and @code{\\dontshow@{@}}" msgstr "" # #. type: findex #: R-exts.texi:5395 #, no-wrap msgid "\\dontshow" msgstr "" # #. type: table #: R-exts.texi:5399 msgid "" "for extra commands for testing that should not be shown to users, but will " "be run by @code{example()}. (Previously this was called @code{\\testonly}, " "and that is still accepted.)" msgstr "" #. type: table #: R-exts.texi:5402 msgid "" "Text inside @code{\\dontrun@{@}} is `verbatim', but the other parts of the " "@code{\\examples} section are @R{}-like text." msgstr "" # #. type: Plain text #: R-exts.texi:5404 #: R-exts.texi:9163 msgid "For example," msgstr "" # #. type: group #: R-exts.texi:5410 #, no-wrap msgid "" "x <- runif(10) # @r{Shown and run.}\n" "\\dontrun@{plot(x)@} # @r{Only shown.}\n" "\\dontshow@{log(x)@} # @r{Only run.}\n" msgstr "" #. type: table #: R-exts.texi:5420 msgid "" "Thus, example code not included in @code{\\dontrun} must be executable! In " "addition, it should not use any system-specific features or require special " "facilities (such as Internet access or write permission to specific " "directories). Text included in @code{\\dontrun} is indicated by comments in " "the processed help files: it need not be valid @R{} code but the escapes " "must still be used for @code{%}, @code{\\} and unpaired braces as in other " "`verbatim' text." msgstr "" # #. type: table #: R-exts.texi:5424 msgid "" "Example code must be capable of being run by @code{example}, which uses " "@code{source}. This means that it should not access @file{stdin}, e.g.@: to " "@code{scan()} data from the example file." msgstr "" # #. type: table #: R-exts.texi:5429 msgid "" "Data needed for making the examples executable can be obtained by random " "number generation (for example, @code{x <- rnorm(100)}), or by using " "standard data sets listed by @code{data()} (see @code{?data} for more info)." msgstr "" #. type: table #: R-exts.texi:5444 msgid "" "Finally, there is @code{\\donttest}, used (at the beginning of a separate " "line) to mark code that should be run by @code{example()} but not by @code{R " "CMD check} (by default: as from @R{} 3.2.0 the option @option{--run-" "donttest} can be used). This should be needed only occasionally but can be " "used for code which might fail in circumstances that are hard to test for, " "for example in some locales. (Use e.g. @code{capabilities()} or " "@code{nzchar(Sys.which(\"someprogram\"))} to test for features needed in the " "examples wherever possible, and you can also use @code{try()} or " "@code{tryCatch()}. Use @code{interactive()} to condition examples which " "need someone to interact with.) Note that code included in " "@code{\\donttest} must be correct @R{} code, and any packages used should be " "declared in the @file{DESCRIPTION} file. It is good practice to include a " "comment in the @code{\\donttest} section explaining why it is needed." msgstr "" # #. type: findex #: R-exts.texi:5445 #, no-wrap msgid "\\keyword" msgstr "" # #. type: item #: R-exts.texi:5446 #, no-wrap msgid "\\keyword@{@var{key}@}" msgstr "" # #. type: table #: R-exts.texi:5454 msgid "" "There can be zero or more @code{\\keyword} sections per file. Each " "@code{\\keyword} section should specify a single keyword, preferably one of " "the standard keywords as listed in file @file{KEYWORDS} in the @R{} " "documentation directory (default @file{@var{R_HOME}/doc}). Use e.g.@: " "@code{RShowDoc(\"KEYWORDS\")} to inspect the standard keywords from within " "@R{}. There can be more than one @code{\\keyword} entry if the @R{} object " "being documented falls into more than one category, or none." msgstr "" # #. type: table #: R-exts.texi:5458 msgid "" "Do strongly consider using @code{\\concept} (@pxref{Indices}) instead of " "@code{\\keyword} if you are about to use more than very few non-standard " "keywords." msgstr "" # #. type: table #: R-exts.texi:5464 msgid "" "The special keyword @samp{internal} marks a page of internal objects that " "are not part of the package's API. If the help page for object @code{foo} " "has keyword @samp{internal}, then @code{help(foo)} gives this help page, but " "@code{foo} is excluded from several object indices, including the " "alphabetical list of objects in the @HTML{} help system." msgstr "" # #. type: table #: R-exts.texi:5469 msgid "" "@code{help.search()} can search by keyword, including user-defined values: " "however the `Search Engine & Keywords' @HTML{} page accessed @emph{via} " "@code{help.start()} provides single-click access only to a pre-defined list " "of keywords." msgstr "" # #. type: Plain text #: R-exts.texi:5478 msgid "" "The structure of @file{Rd} files which document @R{} data sets is slightly " "different. Sections such as @code{\\arguments} and @code{\\value} are not " "needed but the format and source of the data should be explained." msgstr "" # #. type: Plain text #: R-exts.texi:5481 msgid "" "As an example, let us look at @file{src/library/datasets/man/rivers.Rd} " "which documents the standard @R{} data set @code{rivers}." msgstr "" # #. type: smallexample #: R-exts.texi:5502 #, no-wrap msgid "" "\\name@{rivers@}\n" "\\docType@{data@}\n" "\\alias@{rivers@}\n" "\\title@{Lengths of Major North American Rivers@}\n" "\\description@{\n" " This data set gives the lengths (in miles) of 141 \\dQuote@{major@}\n" " rivers in North America, as compiled by the US Geological\n" " Survey.\n" "@}\n" "\\usage@{rivers@}\n" "\\format@{A vector containing 141 observations.@}\n" "\\source@{World Almanac and Book of Facts, 1975, page 406.@}\n" "\\references@{\n" " McNeil, D. R. (1977) \\emph@{Interactive Data Analysis@}.\n" " New York: Wiley.\n" "@}\n" "\\keyword@{datasets@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:5507 msgid "This uses the following additional markup commands." msgstr "" # #. type: item #: R-exts.texi:5509 #, no-wrap msgid "\\docType@{@dots{}@}" msgstr "" # #. type: table #: R-exts.texi:5515 msgid "" "Indicates the ``type'' of the documentation object. Always @samp{data} for " "data sets, and @samp{package} for @file{@var{pkg}-package.Rd} overview " "files. Documentation for S4 methods and classes uses @samp{methods} (from " "@code{promptMethods()}) and @samp{class} (from @code{promptClass()})." msgstr "" # #. type: item #: R-exts.texi:5516 #, no-wrap msgid "\\format@{@dots{}@}" msgstr "" # #. type: findex #: R-exts.texi:5517 #, no-wrap msgid "\\format" msgstr "" # #. type: table #: R-exts.texi:5522 msgid "" "A description of the format of the data set (as a vector, matrix, data " "frame, time series, @dots{}). For matrices and data frames this should give " "a description of each column, preferably as a list or table. @xref{Lists " "and tables}, for more information." msgstr "" # #. type: item #: R-exts.texi:5523 #, no-wrap msgid "\\source@{@dots{}@}" msgstr "" # #. type: findex #: R-exts.texi:5524 #, no-wrap msgid "\\source" msgstr "" #. type: table #: R-exts.texi:5528 msgid "" "Details of the original source (a reference or @acronym{URL}, " "@pxref{Specifying URLs}). In addition, section @code{\\references} could " "give secondary sources and usages." msgstr "" # #. type: Plain text #: R-exts.texi:5531 msgid "Note also that when documenting data set @var{bar}," msgstr "" # #. type: itemize #: R-exts.texi:5537 msgid "" "The @code{\\usage} entry is always @code{@var{bar}} or (for packages which " "do not use lazy-loading of data) @code{data(@var{bar})}. (In particular, " "only document a @emph{single} data object per @file{Rd} file.)" msgstr "" # #. type: itemize #: R-exts.texi:5539 msgid "The @code{\\keyword} entry should always be @samp{datasets}." msgstr "" # #. type: Plain text #: R-exts.texi:5544 msgid "" "If @code{@var{bar}} is a data frame, documenting it as a data set can be " "initiated @emph{via} @code{prompt(@var{bar})}. Otherwise, the " "@code{promptData} function may be used." msgstr "" # #. type: Plain text #: R-exts.texi:5554 msgid "" "There are special ways to use the @samp{?} operator, namely @samp{class?" "@var{topic}} and @samp{methods?@var{topic}}, to access documentation for S4 " "classes and methods, respectively. This mechanism depends on conventions " "for the topic names used in @code{\\alias} entries. The topic names for S4 " "classes and methods respectively are of the form" msgstr "" # #. type: example #: R-exts.texi:5558 #, no-wrap msgid "" "@var{class}-class\n" "@var{generic},@var{signature_list}-method\n" msgstr "" # #. type: Plain text #: R-exts.texi:5568 msgid "" "where @var{signature_list} contains the names of the classes in the " "signature of the method (without quotes) separated by @samp{,} (without " "whitespace), with @samp{ANY} used for arguments without an explicit " "specification. E.g., @samp{genericFunction-class} is the topic name for " "documentation for the S4 class @code{\"genericFunction\"}, and @samp{coerce," "ANY,NULL-method} is the topic name for documentation for the S4 method for " "@code{coerce} for signature @code{c(\"ANY\", \"NULL\")}." msgstr "" # #. type: Plain text #: R-exts.texi:5575 msgid "" "Skeletons of documentation for S4 classes and methods can be generated by " "using the functions @code{promptClass()} and @code{promptMethods()} from " "package @pkg{methods}. If it is necessary or desired to provide an explicit " "function declaration (in a @code{\\usage} section) for an S4 method (e.g., " "if it has ``surprising arguments'' to be mentioned explicitly), one can use " "the special markup" msgstr "" # #. type: example #: R-exts.texi:5578 #, no-wrap msgid "\\S4method@{@var{generic}@}@{@var{signature_list}@}(@var{argument_list})\n" msgstr "" # #. type: Plain text #: R-exts.texi:5582 msgid "(e.g., @samp{\\S4method@{coerce@}@{ANY,NULL@}(from, to)})." msgstr "" # #. type: Plain text #: R-exts.texi:5590 msgid "" "To make full use of the potential of the on-line documentation system, all " "user-visible S4 classes and methods in a package should at least have a " "suitable @code{\\alias} entry in one of the package's @file{Rd} files. If a " "package has methods for a function defined originally somewhere else, and " "does not change the underlying default method for the function, the package " "is responsible for documenting the methods it creates, but not for the " "function itself or the default method." msgstr "" # #. type: Plain text #: R-exts.texi:5593 msgid "" "An S4 replacement method is documented in the same way as an S3 one: see the " "description of @code{\\method} in @ref{Documenting functions}." msgstr "" # #. type: Plain text #: R-exts.texi:5598 msgid "" "See @kbd{help(\"Documentation\", package = \"methods\")} for more " "information on using and creating on-line documentation for S4 classes and " "methods." msgstr "" # #. type: Plain text #: R-exts.texi:5608 msgid "" "Packages may have an overview help page with an @code{\\alias} " "@code{@var{pkgname}-package}, e.g.@: @samp{utils-package} for the " "@pkg{utils} package, when @code{package?@var{pkgname}} will open that help " "page. If a topic named @code{@var{pkgname}} does not exist in another " "@file{Rd} file, it is helpful to use this as an additional @code{\\alias}." msgstr "" # #. type: Plain text #: R-exts.texi:5615 msgid "" "Skeletons of documentation for a package can be generated using the function " "@code{promptPackage()}. If the @code{final = LIBS} argument is used, then " "the @file{Rd} file will be generated in final form, containing the " "information that would be produced up to @code{library(help = " "@var{pkgname})}. Otherwise (the default) comments will be inserted giving " "suggestions for content." msgstr "" # #. type: Plain text #: R-exts.texi:5625 msgid "" "Apart from the mandatory @code{\\name} and @code{\\title} and the " "@code{@var{pkgname}-package} alias, the only requirement for the package " "overview page is that it include a @code{\\docType@{package@}} statement. " "All other content is optional. We suggest that it should be a short " "overview, to give a reader unfamiliar with the package enough information to " "get started. More extensive documentation is better placed into a package " "vignette (@pxref{Writing package vignettes}) and referenced from this page, " "or into individual man pages for the functions, datasets, or classes." msgstr "" # #. type: Plain text #: R-exts.texi:5632 msgid "" "To begin a new paragraph or leave a blank line in an example, just insert an " "empty line (as in (La)@TeX{}). To break a line, use @code{\\cr}." msgstr "" # #. type: findex #: R-exts.texi:5632 #, no-wrap msgid "\\cr" msgstr "" # #. type: Plain text #: R-exts.texi:5637 msgid "" "In addition to the predefined sections (such as @code{\\description@{@}}, " "@code{\\value@{@}}, etc.), you can ``define'' arbitrary ones by " "@code{\\section@{@var{section_title}@}@{@dots{}@}}." msgstr "" # #. type: findex #: R-exts.texi:5637 #, no-wrap msgid "\\section" msgstr "" # #. type: Plain text #: R-exts.texi:5639 msgid "For example" msgstr "" # #. type: example #: R-exts.texi:5644 #, no-wrap msgid "" "\\section@{Warning@}@{\n" " You must not call this function unless @dots{}\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:5653 msgid "" "For consistency with the pre-assigned sections, the section name (the first " "argument to @code{\\section}) should be capitalized (but not all upper " "case). Whitespace between the first and second braced expressions is not " "allowed. Markup (e.g.@: @code{\\code}) within the section title may cause " "problems with the latex conversion (depending on the version of macro " "packages such as @samp{hyperref}) and so should be avoided." msgstr "" # #. type: Plain text #: R-exts.texi:5660 msgid "" "The @code{\\subsection} macro takes arguments in the same format as " "@code{\\section}, but is used within a section, so it may be used to nest " "subsections within sections or other subsections. There is no predefined " "limit on the nesting level, but formatting is not designed for more than 3 " "levels (i.e. subsections within subsections within sections)." msgstr "" # #. type: Plain text #: R-exts.texi:5665 msgid "" "Note that additional named sections are always inserted at a fixed position " "in the output (before @code{\\note}, @code{\\seealso} and the examples), no " "matter where they appear in the input (but in the same order amongst " "themselves as in the input)." msgstr "" # #. type: cindex #: R-exts.texi:5669 #, no-wrap msgid "Marking text in documentation" msgstr "" # #. type: Plain text #: R-exts.texi:5673 msgid "" "The following logical markup commands are available for emphasizing or " "quoting text." msgstr "" # #. type: item #: R-exts.texi:5675 #, no-wrap msgid "\\emph@{@var{text}@}" msgstr "" # #. type: findex #: R-exts.texi:5676 #, no-wrap msgid "\\emph" msgstr "" # #. type: itemx #: R-exts.texi:5677 #, no-wrap msgid "\\strong@{@var{text}@}" msgstr "" # #. type: findex #: R-exts.texi:5678 #, no-wrap msgid "\\strong" msgstr "" # #. type: table #: R-exts.texi:5681 msgid "" "Emphasize @var{text} using @emph{italic} and @strong{bold} font if possible; " "@code{\\strong} is regarded as stronger (more emphatic)." msgstr "" # #. type: item #: R-exts.texi:5682 #, no-wrap msgid "\\bold@{@var{text}@}" msgstr "" # #. type: findex #: R-exts.texi:5683 #, no-wrap msgid "\\bold" msgstr "" #. type: table #: R-exts.texi:5685 msgid "Set @var{text} in @b{bold} font where possible." msgstr "" # #. type: item #: R-exts.texi:5686 #, no-wrap msgid "\\sQuote@{@var{text}@}" msgstr "" # #. type: findex #: R-exts.texi:5687 #, no-wrap msgid "\\sQuote" msgstr "" # #. type: itemx #: R-exts.texi:5688 #, no-wrap msgid "\\dQuote@{@var{text}@}" msgstr "" # #. type: findex #: R-exts.texi:5689 #, no-wrap msgid "\\dQuote" msgstr "" # #. type: table #: R-exts.texi:5692 msgid "" "Portably single or double quote @var{text} (without hard-wiring the " "characters used for quotation marks)." msgstr "" # #. type: Plain text #: R-exts.texi:5696 msgid "" "Each of the above commands takes @LaTeX{}-like input, so other macros may be " "used within @var{text}." msgstr "" #. type: Plain text #: R-exts.texi:5701 msgid "" "The following logical markup commands are available for indicating specific " "kinds of text. Except as noted, these take `verbatim' text input, and so " "other macros may not be used within them. Some characters will need to be " "escaped (@pxref{Insertions})." msgstr "" # #. type: item #: R-exts.texi:5703 #, no-wrap msgid "\\code@{@var{text}@}" msgstr "" # #. type: findex #: R-exts.texi:5704 #, no-wrap msgid "\\code" msgstr "" #. type: table #: R-exts.texi:5710 msgid "" "Indicate text that is a literal example of a piece of an @R{} program, e.g., " "a fragment of @R{} code or the name of an @R{} object. Text is entered in " "@R{}-like syntax, and displayed using @code{typewriter} font where " "possible. Macros @code{\\var} and @code{\\link} are interpreted within " "@var{text}." msgstr "" # #. type: item #: R-exts.texi:5711 #, no-wrap msgid "\\preformatted@{@var{text}@}" msgstr "" # #. type: findex #: R-exts.texi:5712 #, no-wrap msgid "\\preformatted" msgstr "" #. type: table #: R-exts.texi:5718 msgid "" "Indicate text that is a literal example of a piece of a program. Text is " "displayed using @code{typewriter} font where possible. Formatting, e.g.@: " "line breaks, is preserved. (Note that this includes a line break after the " "initial @{, so typically text should start on the same line as the command.)" msgstr "" # #. type: table #: R-exts.texi:5722 msgid "" "Due to limitations in @LaTeX{} as of this writing, this macro may not be " "nested within other markup macros other than @code{\\dQuote} and " "@code{\\sQuote}, as errors or bad formatting may result." msgstr "" # #. type: item #: R-exts.texi:5723 #, no-wrap msgid "\\kbd@{@var{keyboard-characters}@}" msgstr "" # #. type: findex #: R-exts.texi:5724 #, no-wrap msgid "\\kbd" msgstr "" #. type: table #: R-exts.texi:5728 msgid "" "Indicate keyboard input, using @kbd{slanted typewriter} font if possible, so " "users can distinguish the characters they are supposed to type from computer " "output. Text is entered `verbatim'." msgstr "" # #. type: item #: R-exts.texi:5729 #, no-wrap msgid "\\samp@{@var{text}@}" msgstr "" # #. type: findex #: R-exts.texi:5730 #, no-wrap msgid "\\samp" msgstr "" #. type: table #: R-exts.texi:5734 msgid "" "Indicate text that is a literal example of a sequence of characters, entered " "`verbatim'. No wrapping or reformatting will occur. Displayed using " "@code{typewriter} font where possible." msgstr "" # #. type: item #: R-exts.texi:5736 #, no-wrap msgid "\\verb@{@var{text}@}" msgstr "" # #. type: findex #: R-exts.texi:5737 #, no-wrap msgid "\\verb" msgstr "" # #. type: table #: R-exts.texi:5742 msgid "" "Indicate text that is a literal example of a sequence of characters, with no " "interpretation of e.g.@: @code{\\var}, but which will be included within " "word-wrapped text. Displayed using @code{typewriter} font if possible." msgstr "" # #. type: item #: R-exts.texi:5743 #, no-wrap msgid "\\pkg@{@var{package_name}@}" msgstr "" # #. type: findex #: R-exts.texi:5744 #, no-wrap msgid "\\pkg" msgstr "" # #. type: table #: R-exts.texi:5746 msgid "Indicate the name of an @R{} package. @LaTeX{}-like." msgstr "" # #. type: item #: R-exts.texi:5747 #, no-wrap msgid "\\file@{@var{file_name}@}" msgstr "" # #. type: findex #: R-exts.texi:5748 #, no-wrap msgid "\\file" msgstr "" #. type: table #: R-exts.texi:5751 msgid "" "Indicate the name of a file. Text is @LaTeX{}-like, so backslash needs to " "be escaped. Displayed using a distinct font where possible." msgstr "" # #. type: item #: R-exts.texi:5752 #, no-wrap msgid "\\email@{@var{email_address}@}" msgstr "" # #. type: findex #: R-exts.texi:5753 #, no-wrap msgid "\\email" msgstr "" #. type: table #: R-exts.texi:5757 msgid "" "Indicate an electronic mail address. @LaTeX{}-like, will be rendered as a " "hyperlink in @HTML{} and PDF conversion. Displayed using @code{typewriter} " "font where possible." msgstr "" # #. type: item #: R-exts.texi:5758 #, no-wrap msgid "\\url@{@var{uniform_resource_locator}@}" msgstr "" # #. type: findex #: R-exts.texi:5759 #, no-wrap msgid "\\url" msgstr "" #. type: table #: R-exts.texi:5766 msgid "" "Indicate a uniform resource locator (@acronym{URL}) for the World Wide Web. " "The argument is handled as `verbatim' text (with percent and braces escaped " "by backslash), and rendered as a hyperlink in @HTML{} and PDF conversion. " "Linefeeds are removed, and as from @R{} 3.2.0 leading and trailing " "whitespace@footnote{as defined by the @R{} function @code{trimws}.} is " "removed. @xref{Specifying URLs}." msgstr "" #. type: table #: R-exts.texi:5768 msgid "Displayed using @code{typewriter} font where possible." msgstr "" # #. type: item #: R-exts.texi:5769 #, no-wrap msgid "\\href@{@var{uniform_resource_locator}@}@{@var{text}@}" msgstr "" # #. type: findex #: R-exts.texi:5770 #, no-wrap msgid "\\href" msgstr "" #. type: table #: R-exts.texi:5777 msgid "" "Indicate a hyperlink to the World Wide Web. The first argument is handled as " "`verbatim' text (with percent and braces escaped by backslash) and is used " "as the @acronym{URL} in the hyperlink, with the second argument of @LaTeX{}-" "like text displayed to the user. Linefeeds are removed from the first " "argument, and as from @R{} 3.2.0 leading and trailing whitespace is removed." msgstr "" #. type: table #: R-exts.texi:5782 msgid "" "Note that RFC3986-encoded URLs (e.g.@: using @samp{\\%28VS.85\\%29} in place " "of @samp{(VS.85)}) may not work correctly in versions of @R{} before 3.1.3 " "and are best avoided---use @code{URLdecode()} to decode them." msgstr "" # #. type: item #: R-exts.texi:5783 #, no-wrap msgid "\\var@{@var{metasyntactic_variable}@}" msgstr "" # #. type: findex #: R-exts.texi:5784 #, no-wrap msgid "\\var" msgstr "" # #. type: table #: R-exts.texi:5789 msgid "" "Indicate a metasyntactic variable. In some cases this will be rendered " "distinctly, e.g.@: in italic, but not in all@footnote{Currently it is " "rendered differently only in @HTML{} conversions, and @LaTeX{} conversion " "outside @samp{\\usage} and @samp{\\examples} environments.}. @LaTeX{}-like." msgstr "" # #. type: item #: R-exts.texi:5789 #, no-wrap msgid "\\env@{@var{environment_variable}@}" msgstr "" # #. type: findex #: R-exts.texi:5790 #, no-wrap msgid "\\env" msgstr "" #. type: table #: R-exts.texi:5793 msgid "" "Indicate an environment variable. `Verbatim'. Displayed using " "@code{typewriter} font where possible" msgstr "" # #. type: item #: R-exts.texi:5793 #, no-wrap msgid "\\option@{@var{option}@}" msgstr "" # #. type: findex #: R-exts.texi:5794 #, no-wrap msgid "\\option" msgstr "" #. type: table #: R-exts.texi:5797 msgid "" "Indicate a command-line option. `Verbatim'. Displayed using " "@code{typewriter} font where possible." msgstr "" # #. type: item #: R-exts.texi:5797 #, no-wrap msgid "\\command@{@var{command_name}@}" msgstr "" # #. type: findex #: R-exts.texi:5798 #, no-wrap msgid "\\command" msgstr "" #. type: table #: R-exts.texi:5801 msgid "" "Indicate the name of a command. @LaTeX{}-like, so @code{\\var} is " "interpreted. Displayed using @code{typewriter} font where possible." msgstr "" # #. type: item #: R-exts.texi:5801 #, no-wrap msgid "\\dfn@{@var{term}@}" msgstr "" # #. type: findex #: R-exts.texi:5802 #, no-wrap msgid "\\dfn" msgstr "" # #. type: table #: R-exts.texi:5804 msgid "Indicate the introductory or defining use of a term. @LaTeX{}-like." msgstr "" # #. type: item #: R-exts.texi:5804 #, no-wrap msgid "\\cite@{@var{reference}@}" msgstr "" # #. type: findex #: R-exts.texi:5805 #, no-wrap msgid "\\cite" msgstr "" # #. type: table #: R-exts.texi:5808 msgid "" "Indicate a reference without a direct cross-reference @emph{via} " "@code{\\link} (@pxref{Cross-references}), such as the name of a book. " "@LaTeX{}-like." msgstr "" # #. type: item #: R-exts.texi:5808 #, no-wrap msgid "\\acronym@{@var{acronym}@}" msgstr "" # #. type: findex #: R-exts.texi:5809 #, no-wrap msgid "\\acronym" msgstr "" # #. type: table #: R-exts.texi:5812 msgid "" "Indicate an acronym (an abbreviation written in all capital letters), such " "as @acronym{GNU}. @LaTeX{}-like." msgstr "" # #. type: cindex #: R-exts.texi:5817 #, no-wrap msgid "Lists and tables in documentation" msgstr "" # #. type: findex #: R-exts.texi:5819 #, no-wrap msgid "\\itemize" msgstr "" # #. type: findex #: R-exts.texi:5820 #, no-wrap msgid "\\enumerate" msgstr "" # #. type: Plain text #: R-exts.texi:5826 msgid "" "The @code{\\itemize} and @code{\\enumerate} commands take a single argument, " "within which there may be one or more @code{\\item} commands. The text " "following each @code{\\item} is formatted as one or more paragraphs, " "suitably indented and with the first paragraph marked with a bullet point " "(@code{\\itemize}) or a number (@code{\\enumerate})." msgstr "" # #. type: Plain text #: R-exts.texi:5829 msgid "" "Note that unlike argument lists, @code{\\item} in these formats is followed " "by a space and the text (not enclosed in braces). For example" msgstr "" # #. type: example #: R-exts.texi:5837 #, no-wrap msgid "" " \\enumerate@{\n" " \\item A database consists of one or more records, each with one or\n" " more named fields.\n" " \\item Regular lines start with a non-whitespace character.\n" " \\item Records are separated by one or more empty lines.\n" " @}\n" msgstr "" # #. type: Plain text #: R-exts.texi:5840 msgid "@code{\\itemize} and @code{\\enumerate} commands may be nested." msgstr "" # #. type: findex #: R-exts.texi:5841 #, no-wrap msgid "\\describe" msgstr "" # #. type: Plain text #: R-exts.texi:5847 msgid "" "The @code{\\describe} command is similar to @code{\\itemize} but allows " "initial labels to be specified. Each @code{\\item} takes two arguments, the " "label and the body of the item, in exactly the same way as an argument or " "value @code{\\item}. @code{\\describe} commands are mapped to @code{<DL>} " "lists in @HTML{} and @code{\\description} lists in @LaTeX{}." msgstr "" # #. type: findex #: R-exts.texi:5848 #, no-wrap msgid "\\tabular" msgstr "" # #. type: Plain text #: R-exts.texi:5855 msgid "" "The @code{\\tabular} command takes two arguments. The first gives for each " "of the columns the required alignment (@samp{l} for left-justification, " "@samp{r} for right-justification or @samp{c} for centring.) The second " "argument consists of an arbitrary number of lines separated by @code{\\cr}, " "and with fields separated by @code{\\tab}. For example:" msgstr "" # #. type: group #: R-exts.texi:5866 #, no-wrap msgid "" " \\tabular@{rlll@}@{\n" " [,1] \\tab Ozone \\tab numeric \\tab Ozone (ppb)\\cr\n" " [,2] \\tab Solar.R \\tab numeric \\tab Solar R (lang)\\cr\n" " [,3] \\tab Wind \\tab numeric \\tab Wind (mph)\\cr\n" " [,4] \\tab Temp \\tab numeric \\tab Temperature (degrees F)\\cr\n" " [,5] \\tab Month \\tab numeric \\tab Month (1--12)\\cr\n" " [,6] \\tab Day \\tab numeric \\tab Day of month (1--31)\n" " @}\n" msgstr "" # #. type: Plain text #: R-exts.texi:5874 msgid "" "There must be the same number of fields on each line as there are alignments " "in the first argument, and they must be non-empty (but can contain only " "spaces). (There is no whitespace between @code{\\tabular} and the first " "argument, nor between the two arguments.)" msgstr "" # #. type: cindex #: R-exts.texi:5877 #, no-wrap msgid "Cross-references in documentation" msgstr "" # #. type: findex #: R-exts.texi:5879 #, no-wrap msgid "\\link" msgstr "" # #. type: Plain text #: R-exts.texi:5887 msgid "" "The markup @code{\\link@{@var{foo}@}} (usually in the combination " "@code{\\code@{\\link@{@var{foo}@}@}}) produces a hyperlink to the help for " "@var{foo}. Here @var{foo} is a @emph{topic}, that is the argument of " "@code{\\alias} markup in another @file{Rd} file (possibly in another " "package). Hyperlinks are supported in some of the formats to which " "@file{Rd} files are converted, for example @HTML{} and PDF, but ignored in " "others, e.g.@: the text format." msgstr "" # #. type: Plain text #: R-exts.texi:5890 msgid "" "One main usage of @code{\\link} is in the @code{\\seealso} section of the " "help page, @pxref{Rd format}." msgstr "" # #. type: Plain text #: R-exts.texi:5894 msgid "" "Note that whereas leading and trailing spaces are stripped when extracting a " "topic from a @code{\\alias}, they are not stripped when looking up the topic " "of a @code{\\link}." msgstr "" # #. type: cindex #: R-exts.texi:5895 #, no-wrap msgid "\\linkS4class" msgstr "" # #. type: Plain text #: R-exts.texi:5906 msgid "" "You can specify a link to a different topic than its name by " "@code{\\link[=@var{dest}]@{@var{name}@}} which links to topic @var{dest} " "with name @var{name}. This can be used to refer to the documentation for " "S3/4 classes, for example @code{\\code@{\"\\link[=abc-class]@{abc@}\"@}} " "would be a way to refer to the documentation of an S4 class @code{\"abc\"} " "defined in your package, and @code{\\code@{\"\\link[=terms." "object]@{terms@}\"@}} to the S3 @code{\"terms\"} class (in package " "@pkg{stats}). To make these easy to read in the source file, " "@code{\\code@{\"\\linkS4class@{abc@}\"@}} expands to the form given above." msgstr "" # #. type: Plain text #: R-exts.texi:5926 msgid "" "There are two other forms of optional argument specified as " "@code{\\link[@var{pkg}]@{@var{foo}@}} and @code{\\link[@var{pkg:" "bar}]@{@var{foo}@}} to link to the package @pkg{@var{pkg}}, to @emph{files} " "@file{@var{foo}.html} and @file{@var{bar}.html} respectively. These are " "rarely needed, perhaps to refer to not-yet-installed packages (but there the " "@HTML{} help system will resolve the link at run time) or in the normally " "undesirable event that more than one package offers help on a " "topic@footnote{a common example in @acronym{CRAN} packages is " "@code{\\link[mgcv]@{gam@}}.} (in which case the present package has " "precedence so this is only needed to refer to other packages). They are " "currently only used in @HTML{} help (and ignored for hyperlinks in @LaTeX{} " "conversions of help pages), and link to the file rather than the topic " "(since there is no way to know which topics are in which files in an " "uninstalled package). The @strong{only} reason to use these forms for base " "and recommended packages is to force a reference to a package that might be " "further down the search path. Because they have been frequently misused, " "the @HTML{} help system looks for topic @code{@var{foo}} in package " "@pkg{@var{pkg}} if it does not find file @file{@var{foo}.html}." msgstr "" # #. type: cindex #: R-exts.texi:5929 #, no-wrap msgid "Mathematics in documentation" msgstr "" # #. type: findex #: R-exts.texi:5930 #, no-wrap msgid "\\eqn" msgstr "" # #. type: findex #: R-exts.texi:5931 #, no-wrap msgid "\\deqn" msgstr "" #. type: Plain text #: R-exts.texi:5942 msgid "" "Mathematical formulae should be set beautifully for printed documentation " "yet we still want something useful for text and @HTML{} online help. To " "this end, the two commands @code{\\eqn@{@var{latex}@}@{@var{ascii}@}} and " "@code{\\deqn@{@var{latex}@}@{@var{ascii}@}} are used. Whereas @code{\\eqn} " "is used for ``inline'' formulae (corresponding to @TeX{}'s " "@code{$@dots{}$}), @code{\\deqn} gives ``displayed equations'' (as in " "@LaTeX{}'s @code{displaymath} environment, or @TeX{}'s @code{$$@dots{}$$}). " "Both arguments are treated as `verbatim' text." msgstr "" # #. type: Plain text #: R-exts.texi:5947 msgid "" "Both commands can also be used as @code{\\eqn@{@var{latexascii}@}} (only " "@emph{one} argument) which then is used for both @var{latex} and " "@var{ascii}. No whitespace is allowed between command and the first " "argument, nor between the first and second arguments." msgstr "" # #. type: Plain text #: R-exts.texi:5949 msgid "The following example is from @file{Poisson.Rd}:" msgstr "" # #. type: group #: R-exts.texi:5955 #, no-wrap msgid "" " \\deqn@{p(x) = \\frac@{\\lambda^x e^@{-\\lambda@}@}@{x!@}@}@{%\n" "\tp(x) = \\lambda^x exp(-\\lambda)/x!@}\n" " for \\eqn@{x = 0, 1, 2, \\ldots@}.\n" msgstr "" # #. type: iftex #: R-exts.texi:5962 msgid "For the @LaTeX{} manual, this becomes" msgstr "" # #. type: tex #: R-exts.texi:5967 #, no-wrap msgid "" "$$ p(x) = \\lambda^x\\ {e^{-\\lambda} \\over x!} $$\n" "for $x = 0, 1, 2, \\ldots$.\n" msgstr "" # #. type: Plain text #: R-exts.texi:5973 msgid "For text on-line help we get" msgstr "" # #. type: example #: R-exts.texi:5978 #, no-wrap msgid "" " p(x) = lambda^x exp(-lambda)/x!\n" "\n" msgstr "" # #. type: example #: R-exts.texi:5980 #, no-wrap msgid "for x = 0, 1, 2, ....\n" msgstr "" # #. type: Plain text #: R-exts.texi:5987 msgid "" "Greek letters (both cases) will be rendered in @HTML{} if preceded by a " "backslash, @code{\\dots} and @code{\\ldots} will be rendered as ellipses and " "@code{\\sqrt}, @code{\\ge} and @code{\\le} as mathematical symbols." msgstr "" # #. type: Plain text #: R-exts.texi:5990 msgid "" "Note that only basic @LaTeX{} can be used, there being no provision to " "specify @LaTeX{} style files such as the AMS extensions." msgstr "" # #. type: cindex #: R-exts.texi:5993 #, no-wrap msgid "Figures in documentation" msgstr "" # #. type: findex #: R-exts.texi:5994 #, no-wrap msgid "\\figure" msgstr "" # #. type: Plain text #: R-exts.texi:5998 msgid "" "To include figures in help pages, use the @code{\\figure} markup. There are " "three forms." msgstr "" # #. type: Plain text #: R-exts.texi:6006 msgid "" "The two commonly used simple forms are @code{\\figure@{@var{filename}@}} and " "@code{\\figure@{@var{filename}@}@{@var{alternate text}@}}. This will " "include a copy of the figure in either @HTML{} or @LaTeX{} output. In text " "output, the alternate text will be displayed instead. (When the second " "argument is omitted, the filename will be used.) Both the filename and the " "alternate text will be parsed verbatim, and should not include special " "characters that are significant in @HTML{} or @LaTeX{}." msgstr "" # #. type: Plain text #: R-exts.texi:6019 msgid "" "The expert form is @code{\\figure@{@var{filename}@}@{options: @var{string}" "@}}. (The word @samp{options:} must be typed exactly as shown and followed " "by at least one space.) In this form, the @var{string} is copied into the " "@HTML{} @code{img} tag as attributes following the @code{src} attribute, or " "into the second argument of the @code{\\Figure} macro in @LaTeX{}, which by " "default is used as options to an @code{\\includegraphics} call. As it is " "unlikely that any single string would suffice for both display modes, the " "expert form would normally be wrapped in conditionals. It is up to the " "author to make sure that legal @HTML{}/@LaTeX{} is used. For example, to " "include a logo in both @HTML{} (using the simple form) and @LaTeX{} (using " "the expert form), the following could be used:" msgstr "" # #. type: example #: R-exts.texi:6023 #, no-wrap msgid "" "\\if@{html@}@{\\figure@{logo.jpg@}@{Our logo@}@}\n" "\\if@{latex@}@{\\figure@{logo.jpg@}@{options: width=0.5in@}@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:6032 msgid "" "The files containing the figures should be stored in the directory @file{man/" "figures}. Files with extensions @file{.jpg}, @file{.jpeg}, @file{.pdf}, " "@file{.png} and @file{.svg} from that directory will be copied to the " "@file{help/figures} directory at install time. (Figures in PDF format will " "not display in most @HTML{} browsers, but might be the best choice in " "reference manuals.) Specify the filename relative to @file{man/figures} in " "the @code{\\figure} directive." msgstr "" # #. type: findex #: R-exts.texi:6036 #, no-wrap msgid "\\R" msgstr "" # #. type: Plain text #: R-exts.texi:6038 msgid "Use @code{\\R} for the @R{} system itself. Use @code{\\dots}" msgstr "" # #. type: findex #: R-exts.texi:6038 #, no-wrap msgid "\\dots" msgstr "" # #. type: Plain text #: R-exts.texi:6041 msgid "" "for the dots in function argument lists @samp{@dots{}}, and @code{\\ldots}" msgstr "" # #. type: findex #: R-exts.texi:6041 #, no-wrap msgid "\\ldots" msgstr "" # #. type: Plain text #: R-exts.texi:6049 msgid "" "for ellipsis dots in ordinary text.@footnote{There is only a fine " "distinction between @code{\\dots} and @code{\\ldots}. It is technically " "incorrect to use @code{\\ldots} in code blocks and @code{tools::checkRd} " "will warn about this---on the other hand the current converters treat them " "the same way in code blocks, and elsewhere apart from the small distinction " "between the two in @LaTeX{}.} These can be followed by @code{@{@}}, and " "should be unless followed by whitespace." msgstr "" # #. type: Plain text #: R-exts.texi:6054 msgid "" "After an unescaped @samp{%}, you can put your own comments regarding the " "help text. The rest of the line (but not the newline at the end) will be " "completely disregarded. Therefore, you can also use it to make part of the " "``help'' invisible." msgstr "" # #. type: Plain text #: R-exts.texi:6057 msgid "" "You can produce a backslash (@samp{\\}) by escaping it by another " "backslash. (Note that @code{\\cr} is used for generating line breaks.)" msgstr "" #. type: Plain text #: R-exts.texi:6066 msgid "" "The ``comment'' character @samp{%} and unpaired braces@footnote{See the " "examples section in the file @file{Paren.Rd} for an example.} @emph{almost " "always} need to be escaped by @samp{\\}, and @samp{\\\\} can be used for " "backslash and needs to be when there two or more adjacent backslashes). In " "@R{}-like code quoted strings are handled slightly differently; see " "@uref{https://developer.r-project.org/parseRd.pdf, ``Parsing Rd files''} for " "details -- in particular braces should not be escaped in quoted strings." msgstr "" # #. type: Plain text #: R-exts.texi:6068 msgid "All of @samp{% @{ @} \\} should be escaped in @LaTeX{}-like text." msgstr "" # #. type: findex #: R-exts.texi:6069 #, no-wrap msgid "\\enc" msgstr "" # #. type: Plain text #: R-exts.texi:6078 msgid "" "Text which might need to be represented differently in different encodings " "should be marked by @code{\\enc}, e.g.@: @code{\\enc@{J@\"oreskog@}" "@{Joreskog@}} (with no whitespace between the braces) where the first " "argument will be used where encodings are allowed and the second should be " "@acronym{ASCII} (and is used for e.g.@: the text conversion in locales that " "cannot represent the encoded form). (This is intended to be used for " "individual words, not whole sentences or paragraphs.)" msgstr "" # #. type: Plain text #: R-exts.texi:6089 msgid "" "The @code{\\alias} command (@pxref{Documenting functions}) is used to " "specify the ``topics'' documented, which should include @emph{all} @R{} " "objects in a package such as functions and variables, data sets, and S4 " "classes and methods (@pxref{Documenting S4 classes and methods}). The on-" "line help system searches the index data base consisting of all alias topics." msgstr "" # #. type: findex #: R-exts.texi:6090 #, no-wrap msgid "\\concept" msgstr "" # #. type: Plain text #: R-exts.texi:6095 msgid "" "In addition, it is possible to provide ``concept index entries'' using " "@code{\\concept}, which can be used for @code{help.search()} lookups. E.g., " "file @file{cor.test.Rd} in the standard package @pkg{stats} contains" msgstr "" # #. type: example #: R-exts.texi:6100 #, no-wrap msgid "" "\\concept@{Kendall correlation coefficient@}\n" "\\concept@{Pearson correlation coefficient@}\n" "\\concept@{Spearman correlation coefficient@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:6106 msgid "" "so that e.g.@: @kbd{??Spearman} will succeed in finding the help page for " "the test for association between paired samples using Spearman's @eqn{\\rho, " "rho}." msgstr "" # #. type: Plain text #: R-exts.texi:6110 msgid "" "(Note that @code{help.search()} only uses ``sections'' of documentation " "objects with no additional markup.)" msgstr "" # #. type: Plain text #: R-exts.texi:6113 msgid "" "If you want to cross reference such items from other help files @emph{via} " "@code{\\link}, you need to use @code{\\alias} and not @code{\\concept}." msgstr "" # #. type: cindex #: R-exts.texi:6116 #: R-exts.texi:6117 #, no-wrap msgid "Platform-specific documentation" msgstr "" # #. type: Plain text #: R-exts.texi:6122 msgid "" "Sometimes the documentation needs to differ by platform. Currently two OS-" "specific options are available, @samp{unix} and @samp{windows}, and lines in " "the help source file can be enclosed in" msgstr "" # #. type: group #: R-exts.texi:6128 #, no-wrap msgid "" "#ifdef @var{OS}\n" " ...\n" "#endif\n" msgstr "" # #. type: Plain text #: R-exts.texi:6133 msgid "or" msgstr "" # #. type: group #: R-exts.texi:6139 #, no-wrap msgid "" "#ifndef @var{OS}\n" " ...\n" "#endif\n" msgstr "" # #. type: Plain text #: R-exts.texi:6147 msgid "" "for OS-specific inclusion or exclusion. Such blocks should not be nested, " "and should be entirely within a block (that, is between the opening and " "closing brace of a section or item), or at top-level contain one or more " "complete sections." msgstr "" # #. type: Plain text #: R-exts.texi:6151 msgid "" "If the differences between platforms are extensive or the @R{} objects " "documented are only relevant to one platform, platform-specific @file{Rd} " "files can be put in a @file{unix} or @file{windows} subdirectory." msgstr "" # #. type: cindex #: R-exts.texi:6154 #, no-wrap msgid "conditionals" msgstr "" # #. type: findex #: R-exts.texi:6155 #, no-wrap msgid "\\if" msgstr "" # #. type: findex #: R-exts.texi:6156 #, no-wrap msgid "\\ifelse" msgstr "" # #. type: findex #: R-exts.texi:6157 #, no-wrap msgid "\\out" msgstr "" # #. type: Plain text #: R-exts.texi:6167 msgid "" "Occasionally the best content for one output format is different from the " "best content for another. For this situation, the @code{\\if@{@var{format}@}" "@{@var{text}@}} or @code{\\ifelse@{@var{format}@}@{@var{text}@}" "@{@var{alternate}@}} markup is used. Here @var{format} is a comma separated " "list of formats in which the @var{text} should be rendered. The " "@var{alternate} will be rendered if the format does not match. Both " "@var{text} and @var{alternate} may be any sequence of text and markup." msgstr "" # #. type: Plain text #: R-exts.texi:6175 msgid "" "Currently the following formats are recognized: @code{example}, @code{html}, " "@code{latex} and @code{text}. These select output for the corresponding " "targets. (Note that @code{example} refers to extracted example code rather " "than the displayed example in some other format.) Also accepted are " "@code{TRUE} (matching all formats) and @code{FALSE} (matching no formats). " "These could be the output of the @code{\\Sexpr} macro (@pxref{Dynamic " "pages})." msgstr "" # #. type: Plain text #: R-exts.texi:6182 msgid "" "The @code{\\out@{@var{literal}@}} macro would usually be used within the " "@var{text} part of @code{\\if@{@var{format}@}@{@var{text}@}}. It causes the " "renderer to output the literal text exactly, with no attempt to escape " "special characters. For example, use the following to output the markup " "necessary to display the Greek letter in @LaTeX{} or @HTML{}, and the text " "string @code{alpha} in other formats:" msgstr "" # #. type: example #: R-exts.texi:6184 #, no-wrap msgid "\\if@{latex@}@{\\out@{\\alpha@}@}\\ifelse@{html@}@{\\out@{α@}@}@{alpha@}\n" msgstr "" # #. type: cindex #: R-exts.texi:6188 #, no-wrap msgid "dynamic pages" msgstr "" # #. type: findex #: R-exts.texi:6189 #, no-wrap msgid "\\Sexpr" msgstr "" # #. type: findex #: R-exts.texi:6190 #, no-wrap msgid "\\RdOpts" msgstr "" # #. type: Plain text #: R-exts.texi:6195 msgid "" "Two macros supporting dynamically generated man pages are @code{\\Sexpr} and " "@code{\\RdOpts}. These are modelled after Sweave, and are intended to " "contain executable @R{} expressions in the @file{Rd} file." msgstr "" # #. type: Plain text #: R-exts.texi:6200 msgid "" "The main argument to @code{\\Sexpr} must be valid @R{} code that can be " "executed. It may also take options in square brackets before the main " "argument. Depending on the options, the code may be executed at package " "build time, package install time, or man page rendering time." msgstr "" # #. type: Plain text #: R-exts.texi:6203 msgid "" "The options follow the same format as in Sweave, but different options are " "supported. Currently the allowed options and their defaults are:" msgstr "" # #. type: code{#1} #: R-exts.texi:6205 #, no-wrap msgid "eval=TRUE" msgstr "" # #. type: itemize #: R-exts.texi:6207 msgid "Whether the @R{} code should be evaluated." msgstr "" # #. type: code{#1} #: R-exts.texi:6208 #, no-wrap msgid "echo=FALSE" msgstr "" # #. type: itemize #: R-exts.texi:6212 msgid "" "Whether the @R{} code should be echoed. If @code{TRUE}, a display will be " "given in a preformatted block. For example, @code{\\Sexpr[echo=TRUE]@{ x <- " "1 @}} will be displayed as" msgstr "" # #. type: example #: R-exts.texi:6214 #, no-wrap msgid "> x <- 1\n" msgstr "" # #. type: code{#1} #: R-exts.texi:6216 #, no-wrap msgid "keep.source=TRUE" msgstr "" # #. type: itemize #: R-exts.texi:6219 msgid "" "Whether to keep the author's formatting when displaying the code, or throw " "it away and use a deparsed version." msgstr "" # #. type: code{#1} #: R-exts.texi:6220 #: R-exts.texi:6225 #, no-wrap msgid "results=text" msgstr "" # #. type: itemize #: R-exts.texi:6223 msgid "How should the results be displayed? The possibilities are:" msgstr "" # #. type: itemize #: R-exts.texi:6228 msgid "" "Apply @code{as.character()} to the result of the code, and insert it as a " "text element." msgstr "" # #. type: code{#1} #: R-exts.texi:6229 #, no-wrap msgid "results=verbatim" msgstr "" # #. type: itemize #: R-exts.texi:6232 msgid "" "Print the results of the code just as if it was executed at the console, and " "include the printed results verbatim. (Invisible results will not print.)" msgstr "" # #. type: code{#1} #: R-exts.texi:6233 #, no-wrap msgid "results=rd" msgstr "" # #. type: itemize #: R-exts.texi:6240 msgid "" "The result is assumed to be a character vector containing markup to be " "passed to @code{parse_Rd()}, with the result inserted in place. This could " "be used to insert computed aliases, for instance. @code{parse_Rd()} is " "called first with @code{fragment = FALSE} to allow a single Rd section macro " "to be inserted. If that fails, it is called again with @code{fragment = " "TRUE}, the older behavior." msgstr "" # #. type: code{#1} #: R-exts.texi:6241 #, no-wrap msgid "results=hide" msgstr "" # #. type: itemize #: R-exts.texi:6243 msgid "Insert no output." msgstr "" # #. type: code{#1} #: R-exts.texi:6245 #, no-wrap msgid "strip.white=TRUE" msgstr "" # #. type: itemize #: R-exts.texi:6249 msgid "" "Remove leading and trailing white space from each line of output if " "@code{strip.white=TRUE}. With @code{strip.white=all}, also remove blank " "lines." msgstr "" # #. type: code{#1} #: R-exts.texi:6250 #: R-exts.texi:6256 #, no-wrap msgid "stage=install" msgstr "" # #. type: itemize #: R-exts.texi:6252 msgid "Control when this macro is run. Possible values are" msgstr "" # #. type: code{#1} #: R-exts.texi:6253 #, no-wrap msgid "stage=build" msgstr "" # #. type: itemize #: R-exts.texi:6255 msgid "The macro is run when building a source tarball." msgstr "" # #. type: itemize #: R-exts.texi:6258 msgid "The macro is run when installing from source." msgstr "" # #. type: code{#1} #: R-exts.texi:6259 #, no-wrap msgid "stage=render" msgstr "" # #. type: itemize #: R-exts.texi:6261 msgid "The macro is run when displaying the help page." msgstr "" # #. type: itemize #: R-exts.texi:6271 msgid "" "Conditionals such as @code{#ifdef} (@pxref{Platform-specific sections}) are " "applied after the @code{build} macros but before the @code{install} macros. " "In some situations (e.g. installing directly from a source directory without " "a tarball, or building a binary package) the above description is not " "literally accurate, but authors can rely on the sequence being @code{build}, " "@code{#ifdef}, @code{install}, @code{render}, with all stages executed." msgstr "" # #. type: itemize #: R-exts.texi:6275 msgid "" "Code is only run once in each stage, so a @code{\\Sexpr[results=rd]} macro " "can output an @code{\\Sexpr} macro designed for a later stage, but not for " "the current one or any earlier stage." msgstr "" # #. type: code{#1} #: R-exts.texi:6276 #, no-wrap msgid "width, height, fig" msgstr "" # #. type: itemize #: R-exts.texi:6278 msgid "These options are currently allowed but ignored." msgstr "" # #. type: Plain text #: R-exts.texi:6282 msgid "" "The @code{\\RdOpts} macro is used to set new defaults for options to apply " "to following uses of @code{\\Sexpr}." msgstr "" #. type: Plain text #: R-exts.texi:6285 msgid "" "For more details, see the online document @uref{https://developer.r-project." "org/parseRd.pdf, ``Parsing Rd files''}." msgstr "" # #. type: cindex #: R-exts.texi:6288 #, no-wrap msgid "user-defined macros" msgstr "" # #. type: findex #: R-exts.texi:6289 #, no-wrap msgid "\\newcommand" msgstr "" # #. type: findex #: R-exts.texi:6290 #, no-wrap msgid "\\renewcommand" msgstr "" # #. type: Plain text #: R-exts.texi:6295 msgid "" "The @code{\\newcommand} and @code{\\renewcommand} macros allow new macros to " "be defined within an Rd file. These are similar but not identical to the " "same-named @LaTeX{} macros." msgstr "" # #. type: Plain text #: R-exts.texi:6304 msgid "" "They each take two arguments which are parsed verbatim. The first is the " "name of the new macro including the initial backslash, and the second is the " "macro definition. As in @LaTeX{}, @code{\\newcommand} requires that the new " "macro not have been previously defined, whereas @code{\\renewcommand} allows " "existing macros (including all built-in ones) to be replaced. (As from " "version 3.2.0, this test is disabled by default, but may be enabled by " "setting the environment variable @env{_WARN_DUPLICATE_RD_MACROS_} to a true " "value.)" msgstr "" # #. type: Plain text #: R-exts.texi:6317 msgid "" "Also as in @LaTeX{}, the new macro may be defined to take arguments, and " "numeric placeholders such as @code{#1} are used in the macro definition. " "However, unlike @LaTeX{}, the number of arguments is determined " "automatically from the highest placeholder number seen in the macro " "definition. For example, a macro definition containing @code{#1} and " "@code{#3} (but no other placeholders) will define a three argument macro " "(whose second argument will be ignored). As in @LaTeX{}, at most 9 arguments " "may be defined. If the @code{#} character is followed by a non-digit it will " "have no special significance. All arguments to user-defined macros will be " "parsed as verbatim text, and simple text-substitution will be used to " "replace the place-holders, after which the replacement text will be parsed." msgstr "" # #. type: Plain text #: R-exts.texi:6322 msgid "" "As of @R{} version 3.2.0, a number of macros are defined in the file " "@file{share/Rd/macros/system.Rd} of the @R{} source or home directory, and " "these will normally be available in all @file{.Rd} files. For example, that " "file contains the definition" msgstr "" # #. type: example #: R-exts.texi:6324 #, no-wrap msgid "\\newcommand@{\\PR@}@{\\Sexpr[results=rd]@{tools:::Rd_expr_PR(#1)@}@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:6328 msgid "" "which defines @code{\\PR} to be a single argument macro; then code " "(typically used in the @file{NEWS.Rd} file) like" msgstr "" # #. type: example #: R-exts.texi:6330 #, no-wrap msgid "\\PR@{1234@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:6333 msgid "will expand to" msgstr "" # #. type: example #: R-exts.texi:6335 #, no-wrap msgid "\\Sexpr[results=rd]@{tools:::Rd_expr_PR(1234)@}\n" msgstr "" #. type: Plain text #: R-exts.texi:6338 msgid "when parsed." msgstr "" #. type: Plain text #: R-exts.texi:6341 msgid "Some macros that might be of general use are: @ftable @code" msgstr "" #. type: item #: R-exts.texi:6341 #, no-wrap msgid "\\CRANpkg@{pkg@}" msgstr "" #. type: Plain text #: R-exts.texi:6343 msgid "A package on CRAN" msgstr "" #. type: item #: R-exts.texi:6344 #, no-wrap msgid "\\sspace" msgstr "" #. type: Plain text #: R-exts.texi:6346 msgid "A single space (used after a period that does not end a sentence)." msgstr "" #. type: item #: R-exts.texi:6347 #, no-wrap msgid "\\doi@{numbers@}" msgstr "" #. type: Plain text #: R-exts.texi:6349 msgid "A digital object identifier (DOI)." msgstr "" #. type: Plain text #: R-exts.texi:6354 msgid "" "See the @file{system.Rd} file in @file{share/Rd/macros} for more details and " "macro definitions, including macros @code{\\packageTitle}, " "@code{\\packageDescription}, @code{\\packageAuthor}, " "@code{\\packageMaintainer}, @code{\\packageDESCRIPTION} and " "@code{\\packageIndices}." msgstr "" #. type: code{#1} #: R-exts.texi:6354 #, no-wrap msgid "\\packageTitle" msgstr "" #. type: code{#1} #: R-exts.texi:6355 #, no-wrap msgid "\\packageDescription" msgstr "" #. type: code{#1} #: R-exts.texi:6356 #, no-wrap msgid "\\packageAuthor" msgstr "" #. type: code{#1} #: R-exts.texi:6357 #, no-wrap msgid "\\packageMaintainer" msgstr "" #. type: code{#1} #: R-exts.texi:6358 #, no-wrap msgid "\\packageDESCRIPTION" msgstr "" #. type: code{#1} #: R-exts.texi:6359 #, no-wrap msgid "\\packageIndices" msgstr "" # #. type: Plain text #: R-exts.texi:6368 msgid "" "Packages may also define their own common macros; these would be stored in " "an @file{.Rd} file in @file{man/macros} in the package source and will be " "installed into @file{help/macros} when the package is installed. A package " "may also use the macros from a different package by listing the other " "package in the @samp{RdMacros} field in the @file{DESCRIPTION} file." msgstr "" # #. type: cindex #: R-exts.texi:6373 #, no-wrap msgid "encoding" msgstr "" # #. type: Plain text #: R-exts.texi:6385 msgid "" "Rd files are text files and so it is impossible to deduce the encoding they " "are written in unless @acronym{ASCII}: files with 8-bit characters could be " "UTF-8, Latin-1, Latin-9, KOI8-R, EUC-JP, @emph{etc}. So an " "@code{\\encoding@{@}} section must be used to specify the encoding if it is " "not @acronym{ASCII}. (The @code{\\encoding@{@}} section must be on a line " "by itself, and in particular one containing no non-@acronym{ASCII} " "characters. The encoding declared in the @file{DESCRIPTION} file will be " "used if none is declared in the file.) The @file{Rd} files are converted to " "UTF-8 before parsing and so the preferred encoding for the files themselves " "is now UTF-8." msgstr "" #. type: Plain text #: R-exts.texi:6392 msgid "" "Wherever possible, avoid non-@acronym{ASCII} chars in @file{Rd} files, and " "even symbols such as @samp{<}, @samp{>}, @samp{$}, @samp{^}, @samp{&}, " "@samp{|}, @samp{@@}, @samp{~}, and @samp{*} outside `verbatim' environments " "(since they may disappear in fonts designed to render text). (Function " "@code{showNonASCIIfile} in package @pkg{tools} can help in finding non-" "@acronym{ASCII} bytes in the files.)" msgstr "" # #. type: Plain text #: R-exts.texi:6403 msgid "" "For convenience, encoding names @samp{latin1} and @samp{latin2} are always " "recognized: these and @samp{UTF-8} are likely to work fairly widely. " "However, this does not mean that all characters in UTF-8 will be recognized, " "and the coverage of non-Latin characters@footnote{@R{} 2.9.0 added support " "for UTF-8 Cyrillic characters in @LaTeX{}, but on some OSes this will need " "Cyrillic support added to @LaTeX{}, so environment variable " "@env{_R_CYRILLIC_TEX_} may need to be set to a non-empty value to enable " "this.} is fairly low. Using @LaTeX{} @code{inputenx} (see @code{?Rd2pdf} in " "@R{}) will give greater coverage of UTF-8." msgstr "" # #. type: Plain text #: R-exts.texi:6407 msgid "" "The @code{\\enc} command (@pxref{Insertions}) can be used to provide " "transliterations which will be used in conversions that do not support the " "declared encoding." msgstr "" # #. type: Plain text #: R-exts.texi:6410 msgid "" "The @LaTeX{} conversion converts the file to UTF-8 from the declared " "encoding, and includes a" msgstr "" # #. type: example #: R-exts.texi:6413 #, no-wrap msgid "\\inputencoding@{utf8@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:6420 msgid "" "command, and this needs to be matched by a suitable invocation of the " "@command{\\usepackage@{inputenc@}} command. The @R{} utility @command{R CMD " "Rd2pdf} looks at the converted code and includes the encodings used: it " "might for example use" msgstr "" # #. type: Plain text #: R-exts.texi:6431 msgid "" "(Use of @code{utf8} as an encoding requires @LaTeX{} dated 2003/12/01 or " "later. Also, the use of Cyrillic characters in @samp{UTF-8} appears to also " "need @samp{\\usepackage[T2A]@{fontenc@}}, and @command{R CMD Rd2pdf} " "includes this conditionally on the file @file{t2aenc.def} being present and " "environment variable @env{_R_CYRILLIC_TEX_} being set.)" msgstr "" # #. type: Plain text #: R-exts.texi:6434 msgid "" "Note that this mechanism works best with Latin letters: the coverage of " "UTF-8 in @LaTeX{} is quite low." msgstr "" # #. type: cindex #: R-exts.texi:6439 #, no-wrap msgid "Processing Rd format" msgstr "" # #. type: Plain text #: R-exts.texi:6443 msgid "" "There are several commands to process Rd files from the system command line." msgstr "" # #. type: findex #: R-exts.texi:6444 #, no-wrap msgid "R CMD Rdconv" msgstr "" # #. type: Plain text #: R-exts.texi:6449 msgid "" "Using @code{R CMD Rdconv} one can convert @R{} documentation format to other " "formats, or extract the executable examples for run-time testing. The " "currently supported conversions are to plain text, @HTML{} and @LaTeX{} as " "well as extraction of the examples." msgstr "" # #. type: findex #: R-exts.texi:6450 #, no-wrap msgid "R CMD Rd2pdf" msgstr "" # #. type: Plain text #: R-exts.texi:6456 msgid "" "@code{R CMD Rd2pdf} generates PDF output from documentation in @file{Rd} " "files, which can be specified either explicitly or by the path to a " "directory with the sources of a package. In the latter case, a reference " "manual for all documented objects in the package is created, including the " "information in the @file{DESCRIPTION} files." msgstr "" # #. type: findex #: R-exts.texi:6457 #, no-wrap msgid "R CMD Sweave" msgstr "" # #. type: findex #: R-exts.texi:6458 #, no-wrap msgid "R CMD Stangle" msgstr "" # #. type: Plain text #: R-exts.texi:6463 msgid "" "@code{R CMD Sweave} and @code{R CMD Stangle} process vignette-like " "documentation files (e.g. Sweave vignettes with extension @samp{.Snw} or " "@samp{.Rnw}, or other non-Sweave vignettes). @code{R CMD Stangle} is used " "to extract the @R{} code fragments." msgstr "" # #. type: Plain text #: R-exts.texi:6468 msgid "" "The exact usage and a detailed list of available options for all of these " "commands can be obtained by running @code{R CMD @var{command} --help}, e.g., " "@kbd{R CMD Rdconv --help}. All available commands can be listed using " "@kbd{R --help} (or @kbd{Rcmd --help} under Windows)." msgstr "" # #. type: Plain text #: R-exts.texi:6473 msgid "" "All of these work under Windows. You may need to have installed the the " "tools to build packages from source as described in the ``R Installation and " "Administration'' manual, although typically all that is needed is a @LaTeX{} " "installation." msgstr "" # #. type: Plain text #: R-exts.texi:6481 msgid "" "It can be very helpful to prepare @file{.Rd} files using a editor which " "knows about their syntax and will highlight commands, indent to show the " "structure and detect mis-matched braces, and so on." msgstr "" # #. type: Plain text #: R-exts.texi:6487 msgid "" "The system most commonly used for this is some version of @command{Emacs} " "(including @command{XEmacs}) with the @acronym{ESS} package (@uref{http://" "ess.r-project.org/}: it is often is installed with @command{Emacs} but may " "need to be loaded, or even installed, separately)." msgstr "" #. type: Plain text #: R-exts.texi:6491 msgid "" "Another is the Eclipse IDE with the Stat-ET plugin (@uref{http://www.walware." "de/goto/statet}), and (on Windows only) Tinn-R (@uref{http://sourceforge." "net/@/projects/@/tinn-r/})." msgstr "" # #. type: Plain text #: R-exts.texi:6494 msgid "" "People have also used @LaTeX{} mode in a editor, as @file{.Rd} files are " "rather similar to @LaTeX{} files." msgstr "" #. type: Plain text #: R-exts.texi:6497 msgid "" "Some @R{} front-ends provide editing support for @file{.Rd} files, for " "example RStudio (@uref{https://rstudio.org/})." msgstr "" # #. type: node #: R-exts.texi:6506 #: R-exts.texi:6513 #: R-exts.texi:6514 #: R-exts.texi:6515 #: R-exts.texi:6579 #, no-wrap msgid "Tidying R code" msgstr "" # #. type: node #: R-exts.texi:6506 #: R-exts.texi:6513 #: R-exts.texi:6579 #: R-exts.texi:6580 #: R-exts.texi:6693 #, no-wrap msgid "Profiling R code for speed" msgstr "" # #. type: node #: R-exts.texi:6506 #: R-exts.texi:6579 #: R-exts.texi:6693 #: R-exts.texi:6694 #: R-exts.texi:6756 #: R-exts.texi:6777 #: R-exts.texi:6800 #: R-exts.texi:6851 #, no-wrap msgid "Profiling R code for memory use" msgstr "" # #. type: node #: R-exts.texi:6506 #: R-exts.texi:6693 #: R-exts.texi:6851 #: R-exts.texi:6852 #: R-exts.texi:6867 #: R-exts.texi:7077 #: R-exts.texi:7083 #, no-wrap msgid "Profiling compiled code" msgstr "" # #. type: Plain text #: R-exts.texi:6512 msgid "" "@R{} code which is worth preserving in a package and perhaps making " "available for others to use is worth documenting, tidying up and perhaps " "optimizing. The last two of these activities are the subject of this chapter." msgstr "" # #. type: Plain text #: R-exts.texi:6523 msgid "" "@R{} treats function code loaded from packages and code entered by users " "differently. By default code entered by users has the source code stored " "internally, and when the function is listed, the original source is " "reproduced. Loading code from a package (by default) discards the source " "code, and the function listing is re-created from the parse tree of the " "function." msgstr "" # #. type: Plain text #: R-exts.texi:6531 msgid "" "Normally keeping the source code is a good idea, and in particular it avoids " "comments being removed from the source. However, we can make use of the " "ability to re-create a function listing from its parse tree to produce a " "tidy version of the function, for example with consistent indentation and " "spaces around operators. If the original source does not follow the " "standard format this tidied version can be much easier to read." msgstr "" # #. type: Plain text #: R-exts.texi:6533 msgid "We can subvert the keeping of source in two ways." msgstr "" # #. type: enumerate #: R-exts.texi:6538 msgid "" "The option @code{keep.source} can be set to @code{FALSE} before the code is " "loaded into @R{}." msgstr "" # #. type: enumerate #: R-exts.texi:6541 msgid "" "The stored source code can be removed by calling the @code{removeSource()} " "function, for example by" msgstr "" # #. type: example #: R-exts.texi:6544 #, no-wrap msgid "myfun <- removeSource(myfun)\n" msgstr "" # #. type: Plain text #: R-exts.texi:6551 msgid "" "In each case if we then list the function we will get the standard layout." msgstr "" # #. type: Plain text #: R-exts.texi:6554 msgid "" "Suppose we have a file of functions @file{myfuns.R} that we want to tidy " "up. Create a file @file{tidy.R} containing" msgstr "" # #. type: group #: R-exts.texi:6559 #, no-wrap msgid "" "source(\"myfuns.R\", keep.source = FALSE)\n" "dump(ls(all = TRUE), file = \"new.myfuns.R\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:6567 msgid "" "and run @R{} with this as the source file, for example by @kbd{R --vanilla < " "tidy.R} or by pasting into an @R{} session. Then the file @file{new.myfuns." "R} will contain the functions in alphabetical order in the standard layout. " "Warning: comments in your functions will be lost." msgstr "" # #. type: Plain text #: R-exts.texi:6576 msgid "" "The standard format provides a good starting point for further tidying. " "Although the deparsing cannot do so, we recommend the consistent use of the " "preferred assignment operator @samp{<-} (rather than @samp{=}) for " "assignment. Many package authors use a version of Emacs (on a Unix-alike or " "Windows) to edit @R{} code, using the ESS[S] mode of the @acronym{ESS} Emacs " "package. See @ref{R coding standards, , R coding standards, R-ints, R " "Internals} for style options within the ESS[S] mode recommended for the " "source code of @R{} itself." msgstr "" # #. type: cindex #: R-exts.texi:6581 #: R-exts.texi:6695 #: R-exts.texi:6853 #, no-wrap msgid "Profiling" msgstr "" # #. type: findex #: R-exts.texi:6582 #: R-exts.texi:6758 #, no-wrap msgid "Rprof" msgstr "" # #. type: Plain text #: R-exts.texi:6588 msgid "" "It is possible to profile @R{} code on Windows and most@footnote{@R{} has to " "be built to enable this, but the option @option{--enable-R-profiling} is the " "default.} Unix-alike versions of @R{}." msgstr "" # #. type: Plain text #: R-exts.texi:6598 msgid "" "The command @command{Rprof} is used to control profiling, and its help page " "can be consulted for full details. Profiling works by recording at fixed " "intervals@footnote{For Unix-alikes these are intervals of CPU time, and for " "Windows of elapsed time.} (by default every 20 msecs) which line in which " "@R{} function is being used, and recording the results in a file (default " "@file{Rprof.out} in the working directory). Then the function " "@code{summaryRprof} or the command-line utility @code{R CMD Rprof @var{Rprof." "out}} can be used to summarize the activity." msgstr "" # #. type: Plain text #: R-exts.texi:6601 msgid "" "As an example, consider the following code (from Venables & Ripley, 2002, " "pp. 225--6)." msgstr "" # #. type: group #: R-exts.texi:6618 #, no-wrap msgid "" "library(MASS); library(boot)\n" "storm.fm <- nls(Time ~ b*Viscosity/(Wt - c), stormer,\n" "\t\tstart = c(b=30.401, c=2.2183))\n" "st <- cbind(stormer, fit=fitted(storm.fm))\n" "storm.bf <- function(rs, i) @{\n" " st$Time <- st$fit + rs[i]\n" " tmp <- nls(Time ~ (b * Viscosity)/(Wt - c), st,\n" "\t start = coef(storm.fm))\n" " tmp$m$getAllPars()\n" "@}\n" "rs <- scale(resid(storm.fm), scale = FALSE) # remove the mean\n" "Rprof(\"boot.out\")\n" "storm.boot <- boot(rs, storm.bf, R = 4999) # slow enough to profile\n" "Rprof(NULL)\n" msgstr "" # #. type: Plain text #: R-exts.texi:6623 msgid "Having run this we can summarize the results by" msgstr "" # #. type: group #: R-exts.texi:6627 #, no-wrap msgid "" "R CMD Rprof boot.out\n" "\n" msgstr "" # #. type: group #: R-exts.texi:6630 #, no-wrap msgid "" "Each sample represents 0.02 seconds.\n" "Total run time: 22.52 seconds.\n" "\n" msgstr "" # #. type: group #: R-exts.texi:6633 #, no-wrap msgid "" "Total seconds: time spent in function and callees.\n" "Self seconds: time spent in function alone.\n" msgstr "" # #. type: group #: R-exts.texi:6652 #, no-wrap msgid "" " % total % self\n" " total seconds self seconds name\n" " 100.0 25.22 0.2 0.04 \"boot\"\n" " 99.8 25.18 0.6 0.16 \"statistic\"\n" " 96.3 24.30 4.0 1.02 \"nls\"\n" " 33.9 8.56 2.2 0.56 \"<Anonymous>\"\n" " 32.4 8.18 1.4 0.36 \"eval\"\n" " 31.8 8.02 1.4 0.34 \".Call\"\n" " 28.6 7.22 0.0 0.00 \"eval.parent\"\n" " 28.5 7.18 0.3 0.08 \"model.frame\"\n" " 28.1 7.10 3.5 0.88 \"model.frame.default\"\n" " 17.4 4.38 0.7 0.18 \"sapply\"\n" " 15.0 3.78 3.2 0.80 \"nlsModel\"\n" " 12.5 3.16 1.8 0.46 \"lapply\"\n" " 12.3 3.10 2.7 0.68 \"assign\"\n" " ...\n" msgstr "" # #. type: group #: R-exts.texi:6670 #, no-wrap msgid "" " % self % total\n" " self seconds total seconds name\n" " 5.7 1.44 7.5 1.88 \"inherits\"\n" " 4.0 1.02 96.3 24.30 \"nls\"\n" " 3.6 0.92 3.6 0.92 \"$\"\n" " 3.5 0.88 28.1 7.10 \"model.frame.default\"\n" " 3.2 0.80 15.0 3.78 \"nlsModel\"\n" " 2.8 0.70 9.8 2.46 \"qr.coef\"\n" " 2.7 0.68 12.3 3.10 \"assign\"\n" " 2.5 0.64 2.5 0.64 \".Fortran\"\n" " 2.5 0.62 7.1 1.80 \"qr.default\"\n" " 2.2 0.56 33.9 8.56 \"<Anonymous>\"\n" " 2.1 0.54 5.9 1.48 \"unlist\"\n" " 2.1 0.52 7.9 2.00 \"FUN\"\n" " ...\n" msgstr "" # #. type: Plain text #: R-exts.texi:6677 msgid "" "This often produces surprising results and can be used to identify " "bottlenecks or pieces of @R{} code that could benefit from being replaced by " "compiled code." msgstr "" # #. type: Plain text #: R-exts.texi:6681 msgid "" "Two warnings: profiling does impose a small performance penalty, and the " "output files can be very large if long runs are profiled at the default " "sampling interval." msgstr "" # #. type: Plain text #: R-exts.texi:6688 msgid "" "Profiling short runs can sometimes give misleading results. @R{} from time " "to time performs @emph{garbage collection} to reclaim unused memory, and " "this takes an appreciable amount of time which profiling will charge to " "whichever function happens to provoke it. It may be useful to compare " "profiling code immediately after a call to @code{gc()} with a profiling run " "without a preceding call to @code{gc}." msgstr "" # #. type: Plain text #: R-exts.texi:6692 msgid "" "More detailed analysis of the output can be achieved by the tools in the " "@acronym{CRAN} packages @CRANpkg{proftools} and @CRANpkg{profr}: in " "particular these allow call graphs to be studied." msgstr "" # #. type: cindex #: R-exts.texi:6696 #, no-wrap msgid "Memory use" msgstr "" # #. type: Plain text #: R-exts.texi:6705 msgid "" "Measuring memory use in @R{} code is useful either when the code takes more " "memory than is conveniently available or when memory allocation and copying " "of objects is responsible for slow code. There are three ways to profile " "memory use over time in @R{} code. All three require @R{} to have been " "compiled with @option{--enable-memory-profiling}, which is not the default, " "but is currently used for the OS X and Windows binary distributions. All can " "be misleading, for different reasons." msgstr "" # #. type: Plain text #: R-exts.texi:6715 msgid "" "In understanding the memory profiles it is useful to know a little more " "about @R{}'s memory allocation. Looking at the results of @code{gc()} shows " "a division of memory into @code{Vcells} used to store the contents of " "vectors and @code{Ncells} used to store everything else, including all the " "administrative overhead for vectors such as type and length information. In " "fact the vector contents are divided into two pools. Memory for small " "vectors (by default 128 bytes or less) is obtained in large chunks and then " "parcelled out by @R{}; memory for larger vectors is obtained directly from " "the operating system." msgstr "" # #. type: Plain text #: R-exts.texi:6717 msgid "Some memory allocation is obvious in interpreted code, for example," msgstr "" # #. type: smallexample #: R-exts.texi:6720 #, no-wrap msgid "y <- x + 1\n" msgstr "" # #. type: Plain text #: R-exts.texi:6729 msgid "" "allocates memory for a new vector @code{y}. Other memory allocation is less " "obvious and occurs because @code{R} is forced to make good on its promise of " "`call-by-value' argument passing. When an argument is passed to a function " "it is not immediately copied. Copying occurs (if necessary) only when the " "argument is modified. This can lead to surprising memory use. For example, " "in the `survey' package we have" msgstr "" # #. type: smallexample #: R-exts.texi:6738 #, no-wrap msgid "" "print.svycoxph <- function (x, ...)\n" "@{\n" " print(x$survey.design, varnames = FALSE, design.summaries = FALSE,\n" "\t...)\n" " x$call <- x$printcall\n" " NextMethod()\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:6745 msgid "" "It may not be obvious that the assignment to @code{x$call} will cause the " "entire object @code{x} to be copied. This copying to preserve the call-by-" "value illusion is usually done by the internal C function @code{duplicate}." msgstr "" # #. type: Plain text #: R-exts.texi:6749 msgid "" "The main reason that memory-use profiling is difficult is garbage " "collection. Memory is allocated at well-defined times in an @R{} program, " "but is freed whenever the garbage collector happens to run." msgstr "" # #. type: node #: R-exts.texi:6754 #: R-exts.texi:6756 #: R-exts.texi:6777 #, no-wrap msgid "Memory statistics from Rprof" msgstr "" # #. type: node #: R-exts.texi:6754 #: R-exts.texi:6756 #: R-exts.texi:6777 #: R-exts.texi:6778 #: R-exts.texi:6800 #, no-wrap msgid "Tracking memory allocations" msgstr "" # #. type: subsection #: R-exts.texi:6754 #: R-exts.texi:6777 #: R-exts.texi:6800 #: R-exts.texi:6801 #, no-wrap msgid "Tracing copies of an object" msgstr "" # #. type: subsection #: R-exts.texi:6757 #, no-wrap msgid "Memory statistics from @code{Rprof}" msgstr "" # #. type: findex #: R-exts.texi:6759 #, no-wrap msgid "summaryRprof" msgstr "" # #. type: Plain text #: R-exts.texi:6776 msgid "" "The sampling profiler @code{Rprof} described in the previous section can be " "given the option @code{memory.profiling=TRUE}. It then writes out the total " "@R{} memory allocation in small vectors, large vectors, and cons cells or " "nodes at each sampling interval. It also writes out the number of calls to " "the internal function @code{duplicate}, which is called to copy @R{} " "objects. @code{summaryRprof} provides summaries of this information. The " "main reason that this can be misleading is that the memory use is attributed " "to the function running at the end of the sampling interval. A second reason " "is that garbage collection can make the amount of memory in use decrease, so " "a function appears to use little memory. Running under @code{gctorture} " "helps with both problems: it slows down the code to effectively increase the " "sampling frequency and it makes each garbage collection release a smaller " "amount of memory. Changing the memory limits with @code{mem.limits()} may " "also be useful, to see how the code would run under different memory " "conditions." msgstr "" # #. type: findex #: R-exts.texi:6779 #, no-wrap msgid "Rprofmem" msgstr "" # #. type: Plain text #: R-exts.texi:6787 msgid "" "The second method of memory profiling uses a memory-allocation profiler, " "@code{Rprofmem()}, which writes out a stack trace to an output file every " "time a large vector is allocated (with a user-specified threshold for " "`large') or a new page of memory is allocated for the @R{} heap. Summary " "functions for this output are still being designed." msgstr "" # #. type: Plain text #: R-exts.texi:6789 msgid "Running the example from the previous section with" msgstr "" # #. type: smallexample #: R-exts.texi:6794 #, no-wrap msgid "" "> Rprofmem(\"boot.memprof\",threshold=1000)\n" "> storm.boot <- boot(rs, storm.bf, R = 4999)\n" "> Rprofmem(NULL)\n" msgstr "" # #. type: Plain text #: R-exts.texi:6799 msgid "" "shows that apart from some initial and final work in @code{boot} there are " "no vector allocations over 1000 bytes." msgstr "" # #. type: findex #: R-exts.texi:6802 #, no-wrap msgid "tracemem" msgstr "" # #. type: findex #: R-exts.texi:6803 #, no-wrap msgid "untracemem" msgstr "" # #. type: Plain text #: R-exts.texi:6813 msgid "" "The third method of memory profiling involves tracing copies made of a " "specific (presumably large) @R{} object. Calling @code{tracemem} on an " "object marks it so that a message is printed to standard output when the " "object is copied @emph{via} @code{duplicate} or coercion to another type, or " "when a new object of the same size is created in arithmetic operations. The " "main reason that this can be misleading is that copying of subsets or " "components of an object is not tracked. It may be helpful to use " "@code{tracemem} on these components." msgstr "" # #. type: Plain text #: R-exts.texi:6817 msgid "" "In the example above we can run @code{tracemem} on the data frame @code{st}" msgstr "" # #. type: smallexample #: R-exts.texi:6837 #, no-wrap msgid "" "> tracemem(st)\n" "[1] \"<0x9abd5e0>\"\n" "> storm.boot <- boot(rs, storm.bf, R = 4)\n" "memtrace[0x9abd5e0->0x92a6d08]: statistic boot\n" "memtrace[0x92a6d08->0x92a6d80]: $<-.data.frame $<- statistic boot\n" "memtrace[0x92a6d80->0x92a6df8]: $<-.data.frame $<- statistic boot\n" "memtrace[0x9abd5e0->0x9271318]: statistic boot\n" "memtrace[0x9271318->0x9271390]: $<-.data.frame $<- statistic boot\n" "memtrace[0x9271390->0x9271408]: $<-.data.frame $<- statistic boot\n" "memtrace[0x9abd5e0->0x914f558]: statistic boot\n" "memtrace[0x914f558->0x914f5f8]: $<-.data.frame $<- statistic boot\n" "memtrace[0x914f5f8->0x914f670]: $<-.data.frame $<- statistic boot\n" "memtrace[0x9abd5e0->0x972cbf0]: statistic boot\n" "memtrace[0x972cbf0->0x972cc68]: $<-.data.frame $<- statistic boot\n" "memtrace[0x972cc68->0x972cd08]: $<-.data.frame $<- statistic boot\n" "memtrace[0x9abd5e0->0x98ead98]: statistic boot\n" "memtrace[0x98ead98->0x98eae10]: $<-.data.frame $<- statistic boot\n" "memtrace[0x98eae10->0x98eae88]: $<-.data.frame $<- statistic boot\n" msgstr "" # #. type: Plain text #: R-exts.texi:6842 msgid "" "The object is duplicated fifteen times, three times for each of the @code{R" "+1} calls to @code{storm.bf}. This is surprising, since none of the " "duplications happen inside @code{nls}. Stepping through @code{storm.bf} in " "the debugger shows that all three happen in the line" msgstr "" # #. type: smallexample #: R-exts.texi:6845 #, no-wrap msgid "st$Time <- st$fit + rs[i]\n" msgstr "" # #. type: Plain text #: R-exts.texi:6850 msgid "" "Data frames are slower than matrices and this is an example of why. Using " "@code{tracemem(st$Viscosity)} does not reveal any additional copying." msgstr "" # #. type: Plain text #: R-exts.texi:6860 msgid "" "Profiling compiled code is highly system-specific, but this section contains " "some hints gleaned from various @R{} users. Some methods need to be " "different for a compiled executable and for dynamic/shared libraries/objects " "as used by @R{} packages. We know of no good way to profile DLLs on Windows." msgstr "" # #. type: node #: R-exts.texi:6865 #: R-exts.texi:6867 #: R-exts.texi:6868 #: R-exts.texi:7077 #, no-wrap msgid "Linux" msgstr "" # #. type: node #: R-exts.texi:6865 #: R-exts.texi:6867 #: R-exts.texi:7077 #: R-exts.texi:7078 #: R-exts.texi:7083 #, no-wrap msgid "Solaris" msgstr "" # #. type: subsection #: R-exts.texi:6865 #: R-exts.texi:7077 #: R-exts.texi:7083 #: R-exts.texi:7084 #, no-wrap msgid "OS X" msgstr "" # #. type: Plain text #: R-exts.texi:6875 msgid "" "Options include using @command{sprof} for a shared object, and " "@command{oprofile} (see @uref{http://oprofile.sourceforge.net/}) and " "@command{perf} (see @uref{https://perf.wiki.kernel.org/@/index.php/@/" "Tutorial}) for any executable or shared object." msgstr "" # #. type: subsubsection #: R-exts.texi:6876 #, no-wrap msgid "sprof" msgstr "" # #. type: Plain text #: R-exts.texi:6880 msgid "" "You can select shared objects to be profiled with @command{sprof} by setting " "the environment variable @env{LD_PROFILE}. For example" msgstr "" # #. type: example #: R-exts.texi:6887 #, no-wrap msgid "" "% setenv LD_PROFILE /path/to/R_HOME/library/stats/libs/stats.so\n" "R\n" "... run the boot example\n" "% sprof /path/to/R_HOME/library/stats/libs/stats.so \\\n" " /var/tmp/path/to/R_HOME/library/stats/libs/stats.so.profile\n" "\n" msgstr "" # #. type: example #: R-exts.texi:6889 #, no-wrap msgid "" "Flat profile:\n" "\n" msgstr "" # #. type: example #: R-exts.texi:6896 #, no-wrap msgid "" "Each sample counts as 0.01 seconds.\n" " % cumulative self self total\n" " time seconds seconds calls us/call us/call name\n" " 76.19 0.32 0.32 0 0.00 numeric_deriv\n" " 16.67 0.39 0.07 0 0.00 nls_iter\n" " 7.14 0.42 0.03 0 0.00 getListElement\n" "\n" msgstr "" # #. type: example #: R-exts.texi:6899 #, no-wrap msgid "" "rm /var/tmp/path/to/R_HOME/library/stats/libs/stats.so.profile\n" "... to clean up ...\n" msgstr "" # #. type: Plain text #: R-exts.texi:6903 msgid "" "It is possible that root access is needed to create the directories used for " "the profile data." msgstr "" # #. type: subsubsection #: R-exts.texi:6904 #, no-wrap msgid "oprofile and operf" msgstr "" # #. type: Plain text #: R-exts.texi:6912 msgid "" "The @command{oprofile} project has two modes of operation. In what is now " "called `legacy' mode, it is uses a daemon to collect information on a " "process (see below). Since version 0.9.8 (August 2012), the preferred mode " "is to use @command{operf}, so we discuss that first. The modes differ in " "how the profiling data is collected: it is analysed by tools such as " "@command{opreport} and @command{oppannote} in both." msgstr "" # #. type: Plain text #: R-exts.texi:6916 msgid "" "Here is an example on @code{x86_64} Linux using @R{} 3.0.2. File @file{pvec." "R} contains the part of the examples from @code{pvec} in package " "@pkg{parallel}:" msgstr "" # #. type: example #: R-exts.texi:6922 #, no-wrap msgid "" "library(parallel)\n" "N <- 1e6\n" "dates <- sprintf('%04d-%02d-%02d', as.integer(2000+rnorm(N)),\n" " as.integer(runif(N, 1, 12)), as.integer(runif(N, 1, 28)))\n" "system.time(a <- as.POSIXct(dates, format = \"%Y-%m-%d\"))\n" msgstr "" # #. type: Plain text #: R-exts.texi:6924 msgid "with timings from the final step" msgstr "" #. type: example #: R-exts.texi:6927 #, no-wrap msgid "" " user system elapsed\n" " 0.371 0.237 0.612\n" msgstr "" # #. type: Plain text #: R-exts.texi:6930 msgid "@R{}-level profiling by @code{Rprof} shows" msgstr "" # #. type: example #: R-exts.texi:6936 #, no-wrap msgid "" " self.time self.pct total.time total.pct\n" "\"strptime\" 1.70 41.06 1.70 41.06\n" "\"as.POSIXct.POSIXlt\" 1.40 33.82 1.42 34.30\n" "\"sprintf\" 0.74 17.87 0.98 23.67\n" "...\n" msgstr "" # #. type: Plain text #: R-exts.texi:6939 msgid "" "so the conversion from character to @code{POSIXlt} takes most of the time." msgstr "" # #. type: Plain text #: R-exts.texi:6941 msgid "This can be run under @command{operf} and analysed by" msgstr "" #. type: example #: R-exts.texi:6948 #, no-wrap msgid "" "operf R -f pvec.R\n" "opreport\n" "opreport -l /path/to/R_HOME/bin/exec/R\n" "opannotate --source /path/to/R_HOME/bin/exec/R\n" "## And for the system time\n" "opreport -l /lib64/libc.so.6\n" msgstr "" # #. type: Plain text #: R-exts.texi:6950 msgid "The first report shows where (which library etc) the time was spent:" msgstr "" # #. type: example #: R-exts.texi:6964 #, no-wrap msgid "" "CPU_CLK_UNHALT...|\n" " samples| %|\n" "------------------\n" " 166761 99.9161 Rdev\n" "\tCPU_CLK_UNHALT...|\n" "\t samples| %|\n" "\t------------------\n" "\t 70586 42.3276 no-vmlinux\n" "\t 56963 34.1585 libc-2.16.so\n" "\t 36922 22.1407 R\n" "\t 1584 0.9499 stats.so\n" "\t 624 0.3742 libm-2.16.so\n" "...\n" msgstr "" # #. type: Plain text #: R-exts.texi:6968 msgid "" "The rest of the output is voluminous, and only extracts are shown below." msgstr "" # #. type: Plain text #: R-exts.texi:6970 msgid "Most of the time within @R{} is spent in" msgstr "" # #. type: example #: R-exts.texi:6985 #, no-wrap msgid "" "samples % image name symbol name\n" "10397 28.5123 R R_gc_internal\n" "5683 15.5848 R do_sprintf\n" "3036 8.3258 R do_asPOSIXct\n" "2427 6.6557 R do_strptime\n" "2421 6.6392 R Rf_mkCharLenCE\n" "1480 4.0587 R w_strptime_internal\n" "1202 3.2963 R Rf_qnorm5\n" "1165 3.1948 R unif_rand\n" "675 1.8511 R mktime0\n" "617 1.6920 R makelt\n" "617 1.6920 R validate_tm\n" "584 1.6015 R day_of_the_week\n" "...\n" msgstr "" # #. type: Plain text #: R-exts.texi:6991 msgid "" "@command{opannotate} shows that 31% of the time in @R{} is spent in " "@file{memory.c}, 21% in @file{datetime.c} and 7% in @file{Rstrptime.h}. The " "analysis for @file{libc} showed that calls to @code{wcsftime} dominated, so " "those calls were cached for @R{} 3.0.3: the time spent in @code{no-vmlinux} " "(the kernel) was reduced dramatically." msgstr "" # #. type: Plain text #: R-exts.texi:6995 msgid "" "On platforms which support it, call graphs can be produced by " "@command{opcontrol --callgraph} if collected via @command{operf --callgraph}." msgstr "" # #. type: Plain text #: R-exts.texi:6999 msgid "" "The profiling data is by default stored in sub-directory " "@file{oprofile_data} of the current directory, which can be removed at the " "end of the session." msgstr "" # #. type: Plain text #: R-exts.texi:7002 msgid "" "Another example, from @CRANpkg{sm} version 2.2-5.4. The example for " "@code{sm.variogram} took a long time:" msgstr "" #. type: example #: R-exts.texi:7007 #, no-wrap msgid "" "system.time(example(sm.variogram))\n" "...\n" " user system elapsed\n" " 5.543 3.202 8.785\n" msgstr "" # #. type: Plain text #: R-exts.texi:7012 msgid "" "including a lot of system time. Profiling just the slow part, the second " "plot, showed" msgstr "" # #. type: example #: R-exts.texi:7024 #, no-wrap msgid "" " samples| %|\n" "------------------\n" " 381845 99.9885 R\n" "\tCPU_CLK_UNHALT...|\n" "\t samples| %|\n" "\t------------------\n" "\t 187484 49.0995 sm.so\n" "\t 169627 44.4230 no-vmlinux\n" "\t 12636 3.3092 libgfortran.so.3.0.0\n" "\t 6455 1.6905 R\n" msgstr "" # #. type: Plain text #: R-exts.texi:7030 msgid "" "so the system time was almost all in the Linux kernel. It is possible to " "dig deeper if you have a matching uncompressed kernel with debug symbols to " "specify @emph{via} @option{--vmlinux}: we did not." msgstr "" # #. type: Plain text #: R-exts.texi:7033 msgid "" "In `legacy' mode @code{oprofile} works by running a daemon which collects " "information. The daemon must be started as root, e.g." msgstr "" # #. type: example #: R-exts.texi:7040 #, no-wrap msgid "" "% su\n" "% opcontrol --no-vmlinux\n" "% (optional, some platforms) opcontrol --callgraph=5\n" "% opcontrol --start\n" "% exit\n" msgstr "" # #. type: Plain text #: R-exts.texi:7043 msgid "Then as a user" msgstr "" # #. type: example #: R-exts.texi:7071 #, no-wrap msgid "" "% R\n" "... run the boot example\n" "% opcontrol --dump\n" "% opreport -l /path/to/R_HOME/library/stats/libs/stats.so\n" "...\n" "samples % symbol name\n" "1623 75.5939 anonymous symbol from section .plt\n" "349 16.2552 numeric_deriv\n" "113 5.2632 nls_iter\n" "62 2.8878 getListElement\n" "% opreport -l /path/to/R_HOME/bin/exec/R\n" "...\n" "samples % symbol name\n" "76052 11.9912 Rf_eval\n" "54670 8.6198 Rf_findVarInFrame3\n" "37814 5.9622 Rf_allocVector\n" "31489 4.9649 Rf_duplicate\n" "28221 4.4496 Rf_protect\n" "26485 4.1759 Rf_cons\n" "23650 3.7289 Rf_matchArgs\n" "21088 3.3250 Rf_findFun\n" "19995 3.1526 findVarLocInFrame\n" "14871 2.3447 Rf_evalList\n" "13794 2.1749 R_Newhashpjw\n" "13522 2.1320 R_gc_internal\n" "...\n" msgstr "" # #. type: Plain text #: R-exts.texi:7075 msgid "" "Shutting down the profiler and clearing the records needs to be done as root." msgstr "" # #. type: Plain text #: R-exts.texi:7082 msgid "" "On 64-bit (only) Solaris, the standard profiling tool @command{gprof} " "collects information from shared objects compiled with @option{-pg}." msgstr "" # #. type: Plain text #: R-exts.texi:7091 msgid "" "Developers have recommended @command{sample} (or @command{Sampler.app}, " "which is a GUI version), @command{Shark} (in version of @code{Xcode} up to " "those for Snow Leopard), and @command{Instruments} (part of @code{Xcode}, " "see @uref{https://developer.apple.com/library/mac/#documentation/" "DeveloperTools/Conceptual/InstrumentsUserGuide/Introduction/Introduction." "html})." msgstr "" #. type: Plain text #: R-exts.texi:7105 msgid "" "This chapter covers the debugging of @R{} extensions, starting with the ways " "to get useful error information and moving on to how to deal with errors " "that crash @R{}. For those who prefer other styles there are contributed " "packages such as @CRANpkg{debug} on @acronym{CRAN} (described in an article " "in @uref{https://CRAN.R-project.org/@/doc/@/Rnews/@/Rnews_2003-3.pdf, R-News " "3/3}). (There are notes from 2002 provided by Roger Peng at @uref{http://" "www.biostat.jhsph.edu/@/~rpeng/@/docs/@/R-debug-tools.pdf} which provide " "complementary examples to those given here.)" msgstr "" # #. type: node #: R-exts.texi:7111 #: R-exts.texi:7114 #: R-exts.texi:7115 #: R-exts.texi:7193 #, no-wrap msgid "Browsing" msgstr "" # #. type: node #: R-exts.texi:7111 #: R-exts.texi:7114 #: R-exts.texi:7193 #: R-exts.texi:7194 #: R-exts.texi:7509 #, no-wrap msgid "Debugging R code" msgstr "" # #. type: node #: R-exts.texi:7111 #: R-exts.texi:7193 #: R-exts.texi:7509 #: R-exts.texi:7510 #: R-exts.texi:7540 #: R-exts.texi:7609 #: R-exts.texi:7728 #: R-exts.texi:7865 #: R-exts.texi:7991 #: R-exts.texi:8005 #: R-exts.texi:8014 #: R-exts.texi:8049 #, no-wrap msgid "Checking memory access" msgstr "" # #. type: node #: R-exts.texi:7111 #: R-exts.texi:7509 #: R-exts.texi:8049 #: R-exts.texi:8050 #: R-exts.texi:8180 #: R-exts.texi:8211 #, no-wrap msgid "Debugging compiled code" msgstr "" # #. type: findex #: R-exts.texi:7117 #, no-wrap msgid "browser" msgstr "" # #. type: Plain text #: R-exts.texi:7124 msgid "" "Most of the @R{}-level debugging facilities are based around the built-in " "browser. This can be used directly by inserting a call to @code{browser()} " "into the code of a function (for example, using @code{fix(my_function)} ). " "When code execution reaches that point in the function, control returns to " "the @R{} console with a special prompt. For example" msgstr "" # #. type: example #: R-exts.texi:7143 #, no-wrap msgid "" "> fix(summary.data.frame) ## insert browser() call after for() loop\n" "> summary(women)\n" "Called from: summary.data.frame(women)\n" "Browse[1]> ls()\n" " [1] \"digits\" \"i\" \"lbs\" \"lw\" \"maxsum\" \"nm\" \"nr\" \"nv\"\n" " [9] \"object\" \"sms\" \"z\"\n" "Browse[1]> maxsum\n" "[1] 7\n" "Browse[1]>\n" " height weight\n" " Min. :58.0 Min. :115.0\n" " 1st Qu.:61.5 1st Qu.:124.5\n" " Median :65.0 Median :135.0\n" " Mean :65.0 Mean :136.7\n" " 3rd Qu.:68.5 3rd Qu.:148.0\n" " Max. :72.0 Max. :164.0\n" "> rm(summary.data.frame)\n" msgstr "" # #. type: Plain text #: R-exts.texi:7152 msgid "" "At the browser prompt one can enter any @R{} expression, so for example " "@code{ls()} lists the objects in the current frame, and entering the name of " "an object will@footnote{With the exceptions of the commands listed below: an " "object of such a name can be printed @emph{via} an explicit call to " "@code{print}.} print it. The following commands are also accepted" msgstr "" # #. type: code{#1} #: R-exts.texi:7154 #, no-wrap msgid "n" msgstr "" # #. type: itemize #: R-exts.texi:7160 msgid "" "Enter `step-through' mode. In this mode, hitting return executes the next " "line of code (more precisely one line and any continuation lines). Typing " "@code{c} will continue to the end of the current context, e.g.@: to the end " "of the current loop or function." msgstr "" # #. type: code{#1} #: R-exts.texi:7161 #, no-wrap msgid "c" msgstr "" # #. type: itemize #: R-exts.texi:7165 msgid "" "In normal mode, this quits the browser and continues execution, and just " "return works in the same way. @code{cont} is a synonym." msgstr "" # #. type: code{#1} #: R-exts.texi:7166 #, no-wrap msgid "where" msgstr "" # #. type: itemize #: R-exts.texi:7169 msgid "This prints the call stack. For example" msgstr "" # #. type: example #: R-exts.texi:7176 #, no-wrap msgid "" "> summary(women)\n" "Called from: summary.data.frame(women)\n" "Browse[1]> where\n" "where 1: summary.data.frame(women)\n" "where 2: summary(women)\n" "\n" msgstr "" # #. type: example #: R-exts.texi:7178 #, no-wrap msgid "Browse[1]>\n" msgstr "" # #. type: code{#1} #: R-exts.texi:7180 #, no-wrap msgid "Q" msgstr "" # #. type: itemize #: R-exts.texi:7184 msgid "" "Quit both the browser and the current expression, and return to the top-" "level prompt." msgstr "" # #. type: Plain text #: R-exts.texi:7192 msgid "" "Errors in code executed at the browser prompt will normally return control " "to the browser prompt. Objects can be altered by assignment, and will keep " "their changed values when the browser is exited. If really necessary, " "objects can be assigned to the workspace from the browser prompt (by using " "@code{<<-} if the name is not already in scope)." msgstr "" # #. type: findex #: R-exts.texi:7196 #, no-wrap msgid "traceback" msgstr "" # #. type: Plain text #: R-exts.texi:7205 msgid "" "Suppose your @R{} program gives an error message. The first thing to find " "out is what @R{} was doing at the time of the error, and the most useful " "tool is @code{traceback()}. We suggest that this is run whenever the cause " "of the error is not immediately obvious. Daily, errors are reported to the " "@R{} mailing lists as being in some package when @code{traceback()} would " "show that the error was being reported by some other package or base @R{}. " "Here is an example from the regression suite." msgstr "" # #. type: smallexample #: R-exts.texi:7220 #, no-wrap msgid "" "> success <- c(13,12,11,14,14,11,13,11,12)\n" "> failure <- c(0,0,0,0,0,0,0,2,2)\n" "> resp <- cbind(success, failure)\n" "> predictor <- c(0, 5^(0:7))\n" "> glm(resp ~ 0+predictor, family = binomial(link=\"log\"))\n" "Error: no valid set of coefficients has been found: please supply starting values\n" "> traceback()\n" "3: stop(\"no valid set of coefficients has been found: please supply\n" "\t starting values\", call. = FALSE)\n" "2: glm.fit(x = X, y = Y, weights = weights, start = start, etastart = etastart,\n" " mustart = mustart, offset = offset, family = family, control = control,\n" " intercept = attr(mt, \"intercept\") > 0)\n" "1: glm(resp ~ 0 + predictor, family = binomial(link =\"log\"))\n" msgstr "" # #. type: Plain text #: R-exts.texi:7228 msgid "" "The calls to the active frames are given in reverse order (starting with the " "innermost). So we see the error message comes from an explicit check in " "@code{glm.fit}. (@code{traceback()} shows you all the lines of the function " "calls, which can be limited by setting @code{option} @option{\"deparse.max." "lines\"}.)" msgstr "" # #. type: Plain text #: R-exts.texi:7231 msgid "" "Sometimes the traceback will indicate that the error was detected inside " "compiled code, for example (from @code{?nls})" msgstr "" # #. type: smallexample #: R-exts.texi:7238 #, no-wrap msgid "" "Error in nls(y ~ a + b * x, start = list(a = 0.12345, b = 0.54321), trace = TRUE) :\n" "\tstep factor 0.000488281 reduced below 'minFactor' of 0.000976563\n" "> traceback()\n" "2: .Call(R_nls_iter, m, ctrl, trace)\n" "1: nls(y ~ a + b * x, start = list(a = 0.12345, b = 0.54321), trace = TRUE)\n" msgstr "" # #. type: Plain text #: R-exts.texi:7245 msgid "" "This will be the case if the innermost call is to @code{.C}, @code{." "Fortran}, @code{.Call}, @code{.External} or @code{.Internal}, but as it is " "also possible for such code to evaluate @R{} expressions, this need not be " "the innermost call, as in" msgstr "" # #. type: smallexample #: R-exts.texi:7266 #, no-wrap msgid "" "> traceback()\n" "9: gm(a, b, x)\n" "8: .Call(R_numeric_deriv, expr, theta, rho, dir)\n" "7: numericDeriv(form[[3]], names(ind), env)\n" "6: getRHS()\n" "5: assign(\"rhs\", getRHS(), envir = thisEnv)\n" "4: assign(\"resid\", .swts * (lhs - assign(\"rhs\", getRHS(), envir = thisEnv)),\n" " envir = thisEnv)\n" "3: function (newPars)\n" " @{\n" " setPars(newPars)\n" " assign(\"resid\", .swts * (lhs - assign(\"rhs\", getRHS(), envir = thisEnv)),\n" "\t envir = thisEnv)\n" " assign(\"dev\", sum(resid^2), envir = thisEnv)\n" " assign(\"QR\", qr(.swts * attr(rhs, \"gradient\")), envir = thisEnv)\n" " return(QR$rank < min(dim(QR$qr)))\n" " @}(c(-0.00760232418963883, 1.00119632515036))\n" "2: .Call(R_nls_iter, m, ctrl, trace)\n" "1: nls(yeps ~ gm(a, b, x), start = list(a = 0.12345, b = 0.54321))\n" msgstr "" # #. type: Plain text #: R-exts.texi:7270 msgid "" "Occasionally @code{traceback()} does not help, and this can be the case if " "S4 method dispatch is involved. Consider the following example" msgstr "" # #. type: example #: R-exts.texi:7280 #, no-wrap msgid "" "> xyd <- new(\"xyloc\", x=runif(20), y=runif(20))\n" "Error in as.environment(pkg) : no item called \"package:S4nswv\"\n" "on the search list\n" "Error in initialize(value, ...) : S language method selection got\n" "an error when called from internal dispatch for function 'initialize'\n" "> traceback()\n" "2: initialize(value, ...)\n" "1: new(\"xyloc\", x = runif(20), y = runif(20))\n" msgstr "" # #. type: Plain text #: R-exts.texi:7289 msgid "" "which does not help much, as there is no call to @code{as.environment} in " "@code{initialize} (and the note ``called from internal dispatch'' tells us " "so). In this case we searched the @R{} sources for the quoted call, which " "occurred in only one place, @code{methods:::.asEnvironmentPackage}. So now " "we knew where the error was occurring. (This was an unusually opaque " "example.)" msgstr "" # #. type: Plain text #: R-exts.texi:7291 msgid "The error message" msgstr "" # #. type: example #: R-exts.texi:7294 #, no-wrap msgid "evaluation nested too deeply: infinite recursion / options(expressions=)?\n" msgstr "" # #. type: Plain text #: R-exts.texi:7300 msgid "" "can be hard to handle with the default value (5000). Unless you know that " "there actually is deep recursion going on, it can help to set something like" msgstr "" # #. type: example #: R-exts.texi:7303 #, no-wrap msgid "options(expressions=500)\n" msgstr "" # #. type: Plain text #: R-exts.texi:7310 msgid "" "Sometimes there is warning that clearly is the precursor to some later " "error, but it is not obvious where it is coming from. Setting " "@command{options(warn = 2)} (which turns warnings into errors) can help here." msgstr "" # #. type: Plain text #: R-exts.texi:7314 msgid "" "Once we have located the error, we have some choices. One way to proceed is " "to find out more about what was happening at the time of the crash by " "looking a @emph{post-mortem} dump. To do so, set" msgstr "" # #. type: findex #: R-exts.texi:7314 #, no-wrap msgid "dump.frames" msgstr "" # #. type: Plain text #: R-exts.texi:7317 msgid "" "@command{options(error=dump.frames)} and run the code again. Then invoke " "@command{debugger()} and explore the dump. Continuing our example:" msgstr "" # #. type: smallexample #: R-exts.texi:7322 #, no-wrap msgid "" "> options(error = dump.frames)\n" "> glm(resp ~ 0 + predictor, family = binomial(link =\"log\"))\n" "Error: no valid set of coefficients has been found: please supply starting values\n" msgstr "" # #. type: Plain text #: R-exts.texi:7329 msgid "" "which is the same as before, but an object called @code{last.dump} has " "appeared in the workspace. (Such objects can be large, so remove it when it " "is no longer needed.) We can examine this at a later time by calling the " "function @code{debugger}." msgstr "" # #. type: findex #: R-exts.texi:7329 #, no-wrap msgid "debugger" msgstr "" # #. type: smallexample #: R-exts.texi:7339 #, no-wrap msgid "" "> debugger()\n" "Message: Error: no valid set of coefficients has been found: please supply starting values\n" "Available environments had calls:\n" "1: glm(resp ~ 0 + predictor, family = binomial(link = \"log\"))\n" "2: glm.fit(x = X, y = Y, weights = weights, start = start, etastart = etastart, mus\n" "3: stop(\"no valid set of coefficients has been found: please supply starting values\n" "Enter an environment number, or 0 to exit Selection:\n" msgstr "" # #. type: Plain text #: R-exts.texi:7349 msgid "" "which gives the same sequence of calls as @code{traceback}, but in outer-" "first order and with only the first line of the call, truncated to the " "current width. However, we can now examine in more detail what was " "happening at the time of the error. Selecting an environment opens the " "browser in that frame. So we select the function call which spawned the " "error message, and explore some of the variables (and execute two function " "calls)." msgstr "" # #. type: smallexample #: R-exts.texi:7383 #, no-wrap msgid "" "Enter an environment number, or 0 to exit Selection: 2\n" "Browsing in the environment with call:\n" " glm.fit(x = X, y = Y, weights = weights, start = start, etas\n" "Called from: debugger.look(ind)\n" "Browse[1]> ls()\n" " [1] \"aic\" \"boundary\" \"coefold\" \"control\" \"conv\"\n" " [6] \"dev\" \"dev.resids\" \"devold\" \"EMPTY\" \"eta\"\n" "[11] \"etastart\" \"family\" \"fit\" \"good\" \"intercept\"\n" "[16] \"iter\" \"linkinv\" \"mu\" \"mu.eta\" \"mu.eta.val\"\n" "[21] \"mustart\" \"n\" \"ngoodobs\" \"nobs\" \"nvars\"\n" "[26] \"offset\" \"start\" \"valideta\" \"validmu\" \"variance\"\n" "[31] \"varmu\" \"w\" \"weights\" \"x\" \"xnames\"\n" "[36] \"y\" \"ynames\" \"z\"\n" "Browse[1]> eta\n" "\t 1 2 3 4 5\n" " 0.000000e+00 -2.235357e-06 -1.117679e-05 -5.588393e-05 -2.794197e-04\n" "\t 6 7 8 9\n" "-1.397098e-03 -6.985492e-03 -3.492746e-02 -1.746373e-01\n" "Browse[1]> valideta(eta)\n" "[1] TRUE\n" "Browse[1]> mu\n" "\t1 2 3 4 5 6 7 8\n" "1.0000000 0.9999978 0.9999888 0.9999441 0.9997206 0.9986039 0.9930389 0.9656755\n" "\t9\n" "0.8397616\n" "Browse[1]> validmu(mu)\n" "[1] FALSE\n" "Browse[1]> c\n" "Available environments had calls:\n" "1: glm(resp ~ 0 + predictor, family = binomial(link = \"log\"))\n" "2: glm.fit(x = X, y = Y, weights = weights, start = start, etastart = etastart\n" "3: stop(\"no valid set of coefficients has been found: please supply starting v\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:7386 #, no-wrap msgid "" "Enter an environment number, or 0 to exit Selection: 0\n" "> rm(last.dump)\n" msgstr "" # #. type: Plain text #: R-exts.texi:7393 msgid "" "Because @code{last.dump} can be looked at later or even in another @R{} " "session, post-mortem debugging is possible even for batch usage of @R{}. We " "do need to arrange for the dump to be saved: this can be done either using " "the command-line flag @option{--save} to save the workspace at the end of " "the run, or @emph{via} a setting such as" msgstr "" # #. type: example #: R-exts.texi:7396 #, no-wrap msgid "> options(error = quote(@{dump.frames(to.file=TRUE); q()@}))\n" msgstr "" # #. type: Plain text #: R-exts.texi:7401 msgid "" "See the help on @code{dump.frames} for further options and a worked example." msgstr "" # #. type: findex #: R-exts.texi:7402 #, no-wrap msgid "recover" msgstr "" # #. type: Plain text #: R-exts.texi:7404 msgid "An alternative error action is to use the function @command{recover()}:" msgstr "" # #. type: smallexample #: R-exts.texi:7409 #, no-wrap msgid "" "> options(error = recover)\n" "> glm(resp ~ 0 + predictor, family = binomial(link = \"log\"))\n" "Error: no valid set of coefficients has been found: please supply starting values\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:7411 #, no-wrap msgid "" "Enter a frame number, or 0 to exit\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:7414 #, no-wrap msgid "" "1: glm(resp ~ 0 + predictor, family = binomial(link = \"log\"))\n" "2: glm.fit(x = X, y = Y, weights = weights, start = start, etastart = etastart\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:7416 #, no-wrap msgid "Selection:\n" msgstr "" # #. type: Plain text #: R-exts.texi:7424 msgid "" "which is very similar to @code{dump.frames}. However, we can examine the " "state of the program directly, without dumping and re-loading the dump. As " "its help page says, @code{recover} can be routinely used as the error action " "in place of @code{dump.calls} and @code{dump.frames}, since it behaves like " "@code{dump.frames} in non-interactive use." msgstr "" # #. type: findex #: R-exts.texi:7426 #, no-wrap msgid "debug" msgstr "" # #. type: Plain text #: R-exts.texi:7433 msgid "" "Post-mortem debugging is good for finding out exactly what went wrong, but " "not necessarily why. An alternative approach is to take a closer look at " "what was happening just before the error, and a good way to do that is to " "use @command{debug}. This inserts a call to the browser at the beginning of " "the function, starting in step-through mode. So in our example we could use" msgstr "" # #. type: smallexample #: R-exts.texi:7460 #, no-wrap msgid "" "> debug(glm.fit)\n" "> glm(resp ~ 0 + predictor, family = binomial(link =\"log\"))\n" "debugging in: glm.fit(x = X, y = Y, weights = weights, start = start, etastart = etastart,\n" " mustart = mustart, offset = offset, family = family, control = control,\n" " intercept = attr(mt, \"intercept\") > 0)\n" "debug: @{\n" "## lists the whole function\n" "Browse[1]>\n" "debug: x <- as.matrix(x)\n" "...\n" "Browse[1]> start\n" "[1] -2.235357e-06\n" "debug: eta <- drop(x %*% start)\n" "Browse[1]> eta\n" "\t 1 2 3 4 5\n" " 0.000000e+00 -2.235357e-06 -1.117679e-05 -5.588393e-05 -2.794197e-04\n" "\t 6 7 8 9\n" "-1.397098e-03 -6.985492e-03 -3.492746e-02 -1.746373e-01\n" "Browse[1]>\n" "debug: mu <- linkinv(eta <- eta + offset)\n" "Browse[1]> mu\n" "\t1 2 3 4 5 6 7 8\n" "1.0000000 0.9999978 0.9999888 0.9999441 0.9997206 0.9986039 0.9930389 0.9656755\n" "\t9\n" "0.8397616\n" msgstr "" # #. type: Plain text #: R-exts.texi:7466 msgid "" "(The prompt @code{Browse[1]>} indicates that this is the first level of " "browsing: it is possible to step into another function that is itself being " "debugged or contains a call to @code{browser()}.)" msgstr "" # #. type: Plain text #: R-exts.texi:7476 msgid "" "@code{debug} can be used for hidden functions and S3 methods by e.g.@: " "@code{debug(stats:::predict.Arima)}. (It cannot be used for S4 methods, but " "an alternative is given on the help page for @code{debug}.) Sometimes you " "want to debug a function defined inside another function, e.g.@: the " "function @code{arimafn} defined inside @code{arima}. To do so, set " "@code{debug} on the outer function (here @code{arima}) and step through it " "until the inner function has been defined. Then call @code{debug} on the " "inner function (and use @code{c} to get out of step-through mode in the " "outer function)." msgstr "" # #. type: findex #: R-exts.texi:7477 #, no-wrap msgid "undebug" msgstr "" # #. type: Plain text #: R-exts.texi:7482 msgid "" "To remove debugging of a function, call @code{undebug} with the argument " "previously given to @code{debug}; debugging otherwise lasts for the rest of " "the @R{} session (or until the function is edited or otherwise replaced)." msgstr "" # #. type: findex #: R-exts.texi:7483 #, no-wrap msgid "trace" msgstr "" # #. type: Plain text #: R-exts.texi:7487 msgid "" "@code{trace} can be used to temporarily insert debugging code into a " "function, for example to insert a call to @code{browser()} just before the " "point of the error. To return to our running example" msgstr "" # #. type: example #: R-exts.texi:7501 #, no-wrap msgid "" "## first get a numbered listing of the expressions of the function\n" "> page(as.list(body(glm.fit)), method=\"print\")\n" "> trace(glm.fit, browser, at=22)\n" "Tracing function \"glm.fit\" in package \"stats\"\n" "[1] \"glm.fit\"\n" "> glm(resp ~ 0 + predictor, family = binomial(link =\"log\"))\n" "Tracing glm.fit(x = X, y = Y, weights = weights, start = start,\n" " etastart = etastart, .... step 22\n" "Called from: eval(expr, envir, enclos)\n" "Browse[1]> n\n" "## and single-step from here.\n" "> untrace(glm.fit)\n" msgstr "" # #. type: Plain text #: R-exts.texi:7507 msgid "" "For your own functions, it may be as easy to use @code{fix} to insert " "temporary code, but @code{trace} can help with functions in a namespace (as " "can @code{fixInNamespace}). Alternatively, use @code{trace(,edit=TRUE)} to " "insert code visually." msgstr "" # #. type: Plain text #: R-exts.texi:7518 msgid "" "Errors in memory allocation and reading/writing outside arrays are very " "common causes of crashes (e.g.,@: segfaults) on some machines. Often the " "crash appears long after the invalid memory access: in particular damage to " "the structures which @R{} itself has allocated may only become apparent at " "the next garbage collection (or even at later garbage collections after " "objects have been deleted)." msgstr "" #. type: Plain text #: R-exts.texi:7522 msgid "" "Note that memory access errors may be seen with LAPACK, BLAS, OpenMP and " "Java-using packages: some at least of these seem to be intentional, and some " "are related to passing characters to Fortran." msgstr "" # #. type: Plain text #: R-exts.texi:7529 msgid "" "Some of these tools can detect mismatched allocation and deallocation. C++ " "programmers should note that memory allocated by @code{new []} must be freed " "by @code{delete []}, other uses of @code{new} by @code{delete}, and memory " "allocated by @code{malloc}, @code{calloc} and @code{realloc} by " "@code{free}. Some platforms will tolerate mismatches (perhaps with memory " "leaks) but others will segfault." msgstr "" # #. type: node #: R-exts.texi:7538 #: R-exts.texi:7540 #: R-exts.texi:7541 #: R-exts.texi:7609 #, no-wrap msgid "Using gctorture" msgstr "" # #. type: node #: R-exts.texi:7538 #: R-exts.texi:7540 #: R-exts.texi:7609 #: R-exts.texi:7610 #: R-exts.texi:7728 #, no-wrap msgid "Using valgrind" msgstr "" # #. type: node #: R-exts.texi:7538 #: R-exts.texi:7609 #: R-exts.texi:7728 #: R-exts.texi:7832 #: R-exts.texi:7865 #, no-wrap msgid "Using Address Sanitizer" msgstr "" # #. type: node #: R-exts.texi:7538 #: R-exts.texi:7728 #: R-exts.texi:7865 #: R-exts.texi:7991 #, no-wrap msgid "Using Undefined Behaviour Sanitizer" msgstr "" # #. type: node #: R-exts.texi:7538 #: R-exts.texi:7865 #: R-exts.texi:7991 #: R-exts.texi:7992 #: R-exts.texi:8005 #, no-wrap msgid "Other analyses with `clang'" msgstr "" # #. type: node #: R-exts.texi:7538 #: R-exts.texi:7991 #: R-exts.texi:8005 #: R-exts.texi:8006 #: R-exts.texi:8014 #, no-wrap msgid "Using `Dr. Memory'" msgstr "" # #. type: subsection #: R-exts.texi:7538 #: R-exts.texi:8005 #: R-exts.texi:8014 #: R-exts.texi:8015 #, no-wrap msgid "Fortran array bounds checking" msgstr "" # #. type: findex #: R-exts.texi:7543 #, no-wrap msgid "gctorture" msgstr "" # #. type: Plain text #: R-exts.texi:7547 msgid "" "We can help to detect memory problems in @R{} objects earlier by running " "garbage collection as often as possible. This is achieved by " "@code{gctorture(TRUE)}, which as described on its help page" msgstr "" # #. type: quotation #: R-exts.texi:7552 msgid "" "Provokes garbage collection on (nearly) every memory allocation. Intended " "to ferret out memory protection bugs. Also makes @R{} run @emph{very} " "slowly, unfortunately." msgstr "" # #. type: Plain text #: R-exts.texi:7559 msgid "" "The reference to `memory protection' is to missing C-level calls to " "@code{PROTECT}/@code{UNPROTECT} (@pxref{Garbage Collection}) which if " "missing allow @R{} objects to be garbage-collected when they are still in " "use. But it can also help with other memory-related errors." msgstr "" # #. type: Plain text #: R-exts.texi:7563 msgid "" "Normally running under @code{gctorture(TRUE)} will just produce a crash " "earlier in the @R{} program, hopefully close to the actual cause. See the " "next section for how to decipher such crashes." msgstr "" # #. type: Plain text #: R-exts.texi:7567 msgid "" "It is possible to run all the examples, tests and vignettes covered by " "@code{R CMD check} under @code{gctorture(TRUE)} by using the option " "@option{--use-gct}." msgstr "" # #. type: Plain text #: R-exts.texi:7575 msgid "" "The function @code{gctorture2} provides more refined control over the GC " "torture process. Its arguments @code{step}, @code{wait} and " "@code{inhibit_release} are documented on its help page. Environment " "variables can also be used at the start of the @R{} session to turn on GC " "torture: @env{R_GCTORTURE} corresponds to the @code{step} argument to " "@code{gctorture2}, @env{R_GCTORTURE_WAIT} to @code{wait}, and " "@env{R_GCTORTURE_INHIBIT_RELEASE} to @code{inhibit_release}." msgstr "" # #. type: Plain text #: R-exts.texi:7579 msgid "" "If @R{} is configured with @option{--enable-strict-barrier} then a variety " "of tests for the integrity of the write barrier are enabled. In addition " "tests to help detect protect issues are enabled:" msgstr "" # #. type: itemize #: R-exts.texi:7584 msgid "All GCs are full GCs." msgstr "" # #. type: itemize #: R-exts.texi:7587 msgid "New nodes in small node pages are marked as @code{NEWSXP} on creation." msgstr "" # #. type: itemize #: R-exts.texi:7591 msgid "" "After a GC all free nodes that are not of type @code{NEWSXP} are marked as " "type @code{FREESXP} and their previous type is recorded." msgstr "" # #. type: itemize #: R-exts.texi:7597 msgid "" "Most calls to accessor functions check their @code{SEXP} inputs and " "@code{SEXP} outputs and signal an error if a @code{FREESXP} is found. The " "address of the node and the old type are included in the error message." msgstr "" # #. type: Plain text #: R-exts.texi:7604 msgid "" "@code{R CMD check --use-gct} can be set to use @code{gctorture2(@var{n})} " "rather than @code{gctorture(TRUE)} by setting environment variable " "@env{_R_CHECK_GCT_N_} to a positive integer value to be used as " "@code{@var{n}}." msgstr "" # #. type: Plain text #: R-exts.texi:7607 msgid "" "Used with a debugger and with @code{gctorture} or @code{gctorture2} this " "mechanism can be helpful in isolating memory protect problems." msgstr "" # #. type: Plain text #: R-exts.texi:7618 msgid "" "If you have access to Linux on a common CPU type or supported versions of OS " "X@footnote{at the time of writing mainly for 10.9 with some support for " "10.8, none for the current 10.10.} you can use @code{valgrind} (@uref{http://" "www.valgrind.org/}, pronounced to rhyme with `tinned') to check for possible " "problems. To run some examples under @code{valgrind} use something like" msgstr "" # #. type: example #: R-exts.texi:7622 #, no-wrap msgid "" "R -d valgrind --vanilla < mypkg-Ex.R\n" "R -d \"valgrind --tool=memcheck --leak-check=full\" --vanilla < mypkg-Ex.R\n" msgstr "" # #. type: Plain text #: R-exts.texi:7637 msgid "" "where @file{mypkg-Ex.R} is a set of examples, e.g.@: the file created in " "@file{mypkg.Rcheck} by @code{R CMD check}. Occasionally this reports memory " "reads of `uninitialised values' that are the result of compiler " "optimization, so can be worth checking under an unoptimized compile: for " "maximal information use a build with debugging symbols. We know there will " "be some small memory leaks from @code{readline} and @R{} itself --- these " "are memory areas that are in use right up to the end of the @R{} session. " "Expect this to run around 20x slower than without @code{valgrind}, and in " "some cases much slower than that. Several versions of @code{valgrind} were " "not happy with some optimized BLASes that use @acronym{CPU}-specific " "instructions so you may need to build a version of @R{} specifically to use " "with @code{valgrind}." msgstr "" #. type: Plain text #: R-exts.texi:7652 msgid "" "On platforms where @code{valgrind} is installed you can build a version of " "@R{} with extra instrumentation to help @code{valgrind} detect errors in the " "use of memory allocated from the @R{} heap. The @command{configure} option " "is @option{--with-valgrind-instrumentation=@var{level}}, where @var{level} " "is 0, 1 or 2. Level 0 is the default and does not add any anything. Level " "1 will detect some uses@footnote{Those in some numeric, logical, integer, " "raw, complex vectors and in memory allocated by @code{R_alloc}.} of " "uninitialised memory and has little impact on speed (compared to level 0). " "Level 2 will detect many other memory-use bugs@footnote{including using the " "data sections of @R{} vectors after they are freed.} but make @R{} much " "slower when running under @code{valgrind}. Using this in conjunction with " "@code{gctorture} can be even more effective (and even slower)." msgstr "" # #. type: Plain text #: R-exts.texi:7654 msgid "An example of @code{valgrind} output is" msgstr "" # #. type: smallexample #: R-exts.texi:7673 #, no-wrap msgid "" "==12539== Invalid read of size 4\n" "==12539== at 0x1CDF6CBE: csc_compTr (Mutils.c:273)\n" "==12539== by 0x1CE07E1E: tsc_transpose (dtCMatrix.c:25)\n" "==12539== by 0x80A67A7: do_dotcall (dotcode.c:858)\n" "==12539== by 0x80CACE2: Rf_eval (eval.c:400)\n" "==12539== by 0x80CB5AF: R_execClosure (eval.c:658)\n" "==12539== by 0x80CB98E: R_execMethod (eval.c:760)\n" "==12539== by 0x1B93DEFA: R_standardGeneric (methods_list_dispatch.c:624)\n" "==12539== by 0x810262E: do_standardGeneric (objects.c:1012)\n" "==12539== by 0x80CAD23: Rf_eval (eval.c:403)\n" "==12539== by 0x80CB2F0: Rf_applyClosure (eval.c:573)\n" "==12539== by 0x80CADCC: Rf_eval (eval.c:414)\n" "==12539== by 0x80CAA03: Rf_eval (eval.c:362)\n" "==12539== Address 0x1C0D2EA8 is 280 bytes inside a block of size 1996 alloc'd\n" "==12539== at 0x1B9008D1: malloc (vg_replace_malloc.c:149)\n" "==12539== by 0x80F1B34: GetNewPage (memory.c:610)\n" "==12539== by 0x80F7515: Rf_allocVector (memory.c:1915)\n" "...\n" msgstr "" # #. type: Plain text #: R-exts.texi:7691 msgid "" "This example is from an instrumented version of @R{}, while tracking down a " "bug in the @CRANpkg{Matrix} package in 2006. The first line indicates that " "@R{} has tried to read 4 bytes from a memory address that it does not have " "access to. This is followed by a C stack trace showing where the error " "occurred. Next is a description of the memory that was accessed. It is " "inside a block allocated by @code{malloc}, called from @code{GetNewPage}, " "that is, in the internal @R{} heap. Since this memory all belongs to @R{}, " "@code{valgrind} would not (and did not) detect the problem in an " "uninstrumented build of @R{}. In this example the stack trace was enough to " "isolate and fix the bug, which was in @code{tsc_transpose}, and in this " "example running under @code{gctorture()} did not provide any additional " "information. When the stack trace is not sufficiently informative the " "option @option{--db-attach=yes} to @code{valgrind} may be helpful. This " "starts a post-mortem debugger (by default @code{gdb}) so that variables in " "the C code can be inspected (@pxref{Inspecting R objects})." msgstr "" # #. type: Plain text #: R-exts.texi:7698 msgid "" "@command{valgrind} is good at spotting the use of uninitialized values: use " "option @option{--track-origins=yes} to show where these originated from. " "What it cannot detect is the misuse of arrays allocated on the stack: this " "includes C automatic variables and some@footnote{small fixed-size arrays by " "default in @command{gfortran}, for example.} Fortran arrays." msgstr "" # #. type: Plain text #: R-exts.texi:7704 msgid "" "It is possible to run all the examples, tests and vignettes covered by " "@code{R CMD check} under @code{valgrind} by using the option @option{--use-" "valgrind}. If you do this you will need to select the @code{valgrind} " "options some other way, for example by having a @file{~/.valgrindrc} file " "containing" msgstr "" # #. type: example #: R-exts.texi:7708 #, no-wrap msgid "" "--leak-check=full\n" "--track-origins=yes\n" msgstr "" # #. type: Plain text #: R-exts.texi:7712 msgid "or setting the environment variable @env{VALGRIND_OPTS}." msgstr "" # #. type: Plain text #: R-exts.texi:7722 msgid "" "On OS X you may need to ensure that debugging symbols are made available (so " "@command{valgrind} reports line numbers in files). This can usually be done " "with the @command{valgrind} option @option{--dsymutil=yes} to ask for the " "symbols to be dumped when the @file{.so} file is loaded. This will not work " "where packages are installed into a system area (such as the @file{R." "framework}) and can be slow. Installing packages with @command{R CMD " "INSTALL --dsym} installs the dumped symbols. (This can also be done by " "setting environment variable @env{PKG_MAKE_DSYM} to a non-empty value before " "the @command{INSTALL}.)" msgstr "" # #. type: Plain text #: R-exts.texi:7727 msgid "" "This section has described the use of @command{memtest}, the default (and " "most useful) of @code{valgrind}'s tools. There are others described in its " "documentation: @command{helgrind} can be useful for threaded programs." msgstr "" # #. type: subsection #: R-exts.texi:7729 #, no-wrap msgid "Using the Address Sanitizer" msgstr "" #. type: Plain text #: R-exts.texi:7744 msgid "" "@command{AddressSanitizer} (`ASan') is a tool with similar aims to the " "memory checker in @command{valgrind}. It is available with suitable " "builds@footnote{currently only on @cputype{ix86}/@cputype{x86_64} Linux and " "OS X (including the builds in Xcode 7 beta but not earlier Apple releases). " "On some platforms, e.g.@: Fedora, the runtime library, @pkg{libasan}, needs " "to be installed separately. OS X users can install a suitable " "@command{clang} from the sources, @url{http://llvm.org/releases/} or " "possibly distributions such as MacPorts or Homebrew.} of @command{gcc} and " "@command{clang} on common Linux and OS X platforms. See @uref{http://clang." "llvm.org/@/docs/@/UsersManual.html#controlling-code-generation}, " "@uref{http://clang.llvm.org/@/docs/@/AddressSanitizer.html} and " "@uref{https://code.google.com/@/p/@/address-sanitizer/}." msgstr "" #. type: Plain text #: R-exts.texi:7749 msgid "" "More thorough checks of C++ code are done if the C++ library has been " "`annotated': at the time of writing this applied to @code{std::vector} in " "@code{libc++} for use with @command{clang} and gives rise to @samp{container-" "overflow} reports." msgstr "" #. type: Plain text #: R-exts.texi:7757 msgid "" "It requires code to have been compiled @emph{and linked} with @option{-" "fsanitize=address} and compiling with @code{-fno-omit-frame-pointer} will " "give more legible reports. It has a runtime penalty of 2--3x, extended " "compilation times and uses substantially more memory, often 1--2GB, at run " "time. On 64-bit platforms it reserves (but does not allocate) 16--20TB of " "virtual memory: restrictive shell settings can cause problems." msgstr "" # #. type: Plain text #: R-exts.texi:7761 msgid "" "By comparison with @command{valgrind}, ASan can detect misuse of stack and " "global variables but not the use of uninitialized memory." msgstr "" #. type: Plain text #: R-exts.texi:7768 msgid "" "Recent versions return symbolic addresses for the location of the error " "provided @command{llvm-symbolizer}@footnote{part of the LLVM project and in " "distributed in @code{llvm} RPMs and @code{.deb}s on Linux. It is not " "currently shipped by Apple.} is on the path: if it is available but not on " "the path or has been renamed@footnote{as Ubuntu does.}, one can use an " "environment variable, e.g.@:" msgstr "" # #. type: example #: R-exts.texi:7771 #, no-wrap msgid "ASAN_SYMBOLIZER_PATH=/path/to/llvm-symbolizer\n" msgstr "" #. type: Plain text #: R-exts.texi:7781 msgid "" "An alternative is to pipe the output through @command{asan_symbolize.py}" "@footnote{installed on some Linux systems as @command{asan_symbolize}, and " "obtainable from @uref{https://llvm.org/@/svn/@/llvm-project/@/compiler-rt/@/" "trunk/@/lib/@/asan/scripts/@/asan_symbolize.py}: it makes use of " "@command{llvm-symbolizer} if available.} and perhaps then (for compiled C++ " "code) @command{c++filt}. (On OS X, you may need to run @command{dsymutil} " "to get line-number reports.)" msgstr "" # #. type: Plain text #: R-exts.texi:7784 msgid "" "The simplest way to make use of this is to build a version of @R{} with " "something like" msgstr "" #. type: example #: R-exts.texi:7788 #, no-wrap msgid "" "CC=\"gcc -std=gnu99 -fsanitize=address\"\n" "CFLAGS=\"-fno-omit-frame-pointer -g -O2 -Wall -pedantic -mtune=native\"\n" msgstr "" # #. type: Plain text #: R-exts.texi:7794 msgid "" "which will ensure that the @code{libasan} run-time library is compiled into " "the @R{} executable. However this check can be enabled on a per-package " "basis by using a @file{~/.R/Makevars} file like" msgstr "" # #. type: example #: R-exts.texi:7799 #, no-wrap msgid "" "CC = gcc-4.9 -std=gnu99 -fsanitize=address -fno-omit-frame-pointer\n" "CXX = g++-4.9 -fsanitize=address -fno-omit-frame-pointer\n" "F77 = gfortran-4.9 -fsanitize=address\n" "FC = gfortran-4.9 -fsanitize=address\n" msgstr "" # #. type: Plain text #: R-exts.texi:7804 msgid "" "(Note that @code{-fsanitize=address} has to be part of the compiler " "specification to ensure it is used for linking. These settings will not be " "honoured by packages which ignore @file{~/.R/Makevars}.) It will be " "necessary to build @R{} with" msgstr "" # #. type: example #: R-exts.texi:7807 #, no-wrap msgid "MAIN_LDFLAGS = -fsanitize=address\n" msgstr "" # #. type: Plain text #: R-exts.texi:7812 msgid "" "to link the runtime libraries into the @R{} executable if it was not " "specified as part of @samp{CC} when @R{} was built." msgstr "" #. type: Plain text #: R-exts.texi:7818 msgid "" "For options available @emph{via} the environment variable @env{ASAN_OPTIONS} " "see @uref{https://code.google.com/@/p/@/address-sanitizer/@/wiki/@/Flags#Run-" "time_flags}. With @command{gcc} additional control is available @emph{via} " "the @option{--params} flag: see its @command{man} page." msgstr "" # #. type: Plain text #: R-exts.texi:7822 msgid "" "For more detailed information on an error, @R{} can be run under a debugger " "with a breakpoint set before the address sanitizer report is produced: for " "@command{gdb} or @command{lldb} you could use" msgstr "" # #. type: example #: R-exts.texi:7824 #, no-wrap msgid "break __asan_report_error\n" msgstr "" #. type: Plain text #: R-exts.texi:7827 msgid "" "(See @uref{https://code.google.com/@/p/@/address-sanitizer/@/wiki@//" "AddressSanitizer#gdb}.)" msgstr "" # #. type: node #: R-exts.texi:7830 #: R-exts.texi:7832 #, no-wrap msgid "Using Leak Sanitizer" msgstr "" # #. type: subsubsection #: R-exts.texi:7833 #, no-wrap msgid "Using the Leak Sanitizer" msgstr "" #. type: Plain text #: R-exts.texi:7839 msgid "" "For @code{x86_64} Linux there is a leak sanitizer, `LSan': see @uref{https://" "code.google.com/@/p/@/address-sanitizer/@/wiki/@/LeakSanitizer}. This is " "available on recent versions of @code{gcc} and @code{clang}, and where " "available is compiled in as part of ASan." msgstr "" # #. type: Plain text #: R-exts.texi:7842 msgid "" "One way to invoke this from an ASan-enabled build is by the environment " "variable" msgstr "" # #. type: example #: R-exts.texi:7845 #, no-wrap msgid "ASAN_OPTIONS='detect_leaks=1'\n" msgstr "" #. type: Plain text #: R-exts.texi:7849 msgid "" "However, this was made the default for @command{clang} 3.5 and @command{gcc} " "5.1.0." msgstr "" #. type: Plain text #: R-exts.texi:7855 msgid "" "When LSan is enabled, leaks give the process a failure error status (by " "default @code{23}). For an @R{} package this means the @R{} process, and as " "the parser retains some memory to the end of the process, if @R{} itself was " "built against ASan, all runs will have a failure error status (which may " "include running @R{} as part of building @R{} itself)." msgstr "" # #. type: Plain text #: R-exts.texi:7857 msgid "To disable both this and some strict checking use" msgstr "" #. type: example #: R-exts.texi:7860 #, no-wrap msgid "setenv ASAN_OPTIONS 'alloc_dealloc_mismatch=0:detect_leaks=0:detect_odr_violation=0'\n" msgstr "" # #. type: Plain text #: R-exts.texi:7864 msgid "" "LSan also has a `stand-alone' mode where it is compiled in using @option{-" "fsanitize=leak} and avoids the run-time overhead of ASan." msgstr "" # #. type: subsection #: R-exts.texi:7866 #, no-wrap msgid "Using the Undefined Behaviour Sanitizer" msgstr "" # #. type: Plain text #: R-exts.texi:7879 msgid "" "`Undefined behaviour' is where the language standard does not require " "particular behaviour from the compiler. Examples include division by zero " "(where for doubles @R{} requires the @acronym{ISO}/@acronym{IEC}@tie{}60559 " "behaviour but C/C++ do not), use of zero-length arrays, shifts too far for " "signed types (e.g.@: @code{int x, y; y = x << 31;}), out-of-range coercion, " "invalid C++ casts and mis-alignment. Not uncommon examples of out-of-range " "coercion in @R{} packages are attempts to coerce a @code{NaN} or infinity to " "type @code{int} or @code{NA_INTEGER} to an unsigned type such as " "@code{size_t}. Also common is @code{y[x - 1]} forgetting that @code{x} " "might be @code{NA_INTEGER}." msgstr "" #. type: Plain text #: R-exts.texi:7885 msgid "" "`UBSanitizer' is a tool for C/C++ source code selected by @option{-" "fsanitize=undefined} in suitable builds of @command{clang}, and GCC as from " "4.9.0. Its (main) runtime library is linked into each package's DLL, so it " "is less often needed to be included in @env{MAIN_LDFLAGS}." msgstr "" #. type: Plain text #: R-exts.texi:7889 msgid "" "Some versions have greatly increased compilation times on a few " "files@footnote{e.g.@: @file{src/main/dotcode.c} and parts of the " "@pkg{Matrix} sources with @command{clang} 3.7.0).}." msgstr "" #. type: Plain text #: R-exts.texi:7892 msgid "" "This sanitizer can be combined with the Address Sanitizer by @option{-" "fsanitize=undefined,address} (where both are supported)." msgstr "" #. type: Plain text #: R-exts.texi:7899 msgid "" "Finer control of what is checked can be achieved by other options: for " "@command{clang} see @uref{http://clang.llvm.org/@/docs/@/UsersManual." "html#controlling-code-generation}.@footnote{or the user manual for your " "version of @command{clang}, e.g.@: @uref{http://llvm.org/@/releases/" "@/3.6.2@//tools/@/clang/@/docs/@/UsersManual.html}.} The current set for " "@command{clang} is (on a single line):" msgstr "" #. type: example #: R-exts.texi:7904 #, no-wrap msgid "" "-fsanitize=alignment,bool,bounds,enum,float-cast-overflow,\n" "float-divide-by-zero,function,integer-divide-by-zero,non-null-attribute,\n" "null,object-size,return,returns-nonnull-attribute,shift,\n" "signed-integer-overflow,unreachable,vla-bound,vptr\n" msgstr "" # #. type: Plain text #: R-exts.texi:7909 msgid "" "a subset of which could be combined with @code{address}, or use something " "like" msgstr "" # #. type: example #: R-exts.texi:7912 #, no-wrap msgid "-fsanitize=undefined -fno-sanitize=float-divide-by-zero\n" msgstr "" #. type: Plain text #: R-exts.texi:7917 msgid "" "(@code{function}, @code{return} and @code{vptr} apply only to C++). In " "addition," msgstr "" # #. type: example #: R-exts.texi:7919 #, no-wrap msgid "-fsanitize=unsigned-integer-overflow\n" msgstr "" # #. type: Plain text #: R-exts.texi:7922 msgid "" "is available as a separate option in some versions of @command{clang} (not " "enabled by @option{-fsanitize=undefined})." msgstr "" #. type: Plain text #: R-exts.texi:7924 msgid "@command{clang} 3.5 and later may need" msgstr "" # #. type: example #: R-exts.texi:7927 #, no-wrap msgid "-fsanitize=undefined -fno-sanitize=float-divide-by-zero,vptr\n" msgstr "" #. type: Plain text #: R-exts.texi:7934 msgid "" "for C++ code (in @code{CXX} and @code{CXX1X}) as the run-time library for " "@code{vptr} needs to be linked into the main @R{} executable (and that would " "need to be linked by @code{clang++}, not @code{clang}: you could try " "building @R{} with something like" msgstr "" #. type: example #: R-exts.texi:7937 #, no-wrap msgid "" "MAIN_LD=\"clang++ -fsanitize=undefined\"\n" "R_OPENMP_CFLAGS=\"-fopenmp=libomp\"\n" msgstr "" #. type: Plain text #: R-exts.texi:7940 msgid "" "or add @code{-lclang_rt.asan_cxx-x86_64}@footnote{This includes the C++ " "UBSAN handlers, despite its name.} or similar to @code{LD_FLAGS})." msgstr "" #. type: Plain text #: R-exts.texi:7945 msgid "" "See @uref{https://gcc.gnu.org/@/onlinedocs/@/gcc/@/Debugging-Options.html} " "(or the manual for your version of GCC, installed or @emph{via} " "@uref{https://gcc.gnu.org/@/onlinedocs/}) for the options supported by GCC: " "5.2.0 supports" msgstr "" #. type: example #: R-exts.texi:7950 #, no-wrap msgid "" "-fsanitize=alignment,bool,bounds,enum,float-cast-overflow,\n" "integer-divide-by-zero,non-null-attribute,null,object-size,\n" "return,returns-nonnull-attribute,shift,signed-integer-overflow,\n" "unreachable,vla-bound,vptr\n" msgstr "" # #. type: Plain text #: R-exts.texi:7953 msgid "with" msgstr "" # #. type: example #: R-exts.texi:7955 #, no-wrap msgid "-fsanitize=float-divide-by-zero\n" msgstr "" #. type: Plain text #: R-exts.texi:7961 msgid "" "as a separate option not enabled by @code{-fsanitize=undefined} (and not " "desirable for @R{} uses). At the time of writing the @code{object-size} and " "@code{vptr} checks produced many warnings on GCC's own C++ headers, so " "should be disabled." msgstr "" # #. type: Plain text #: R-exts.texi:7964 msgid "Other useful flags include" msgstr "" # #. type: example #: R-exts.texi:7966 #, no-wrap msgid "-no-fsanitize-recover\n" msgstr "" # #. type: Plain text #: R-exts.texi:7974 msgid "" "which causes the first report to be fatal (it always is for the " "@code{unreachable} and @code{return} suboptions). For more detailed " "information on where the runtime error occurs, @R{} can be run under a " "debugger with a breakpoint set before the sanitizer report is produced: for " "@command{gdb} or @command{lldb} you could use" msgstr "" # #. type: example #: R-exts.texi:7977 #, no-wrap msgid "" "break __ubsan_handle_float_cast_overflow\n" "break __ubsan_handle_float_cast_overflow_abort\n" msgstr "" # #. type: Plain text #: R-exts.texi:7980 msgid "or similar (there are handlers for each type of undefined behaviour)." msgstr "" # #. type: Plain text #: R-exts.texi:7984 msgid "" "There are also the compiler flags @option{-fcatch-undefined-behavior} and " "@option{-ftrapv}, said to be more reliable in @command{clang} than " "@command{gcc}." msgstr "" #. type: Plain text #: R-exts.texi:7989 msgid "" "For more details on the topic see @uref{http://blog.regehr.org/archives/213} " "and @uref{http://blog.llvm.org/@/2011/@/05/@/what-every-c-programmer-should-" "know.html} (which has 3 parts)." msgstr "" #. type: Plain text #: R-exts.texi:8001 msgid "" "Recent versions of @command{clang} on @cputype{x86_64} Linux have " "`ThreadSanitizer' (@uref{https://code.google.com/@/p/@/thread-sanitizer/}), " "a `data race detector for C/C++ programs', and " "`MemorySanitizer' (@uref{http://clang.llvm.org/@/docs/@/MemorySanitizer." "html}, @uref{https://code.google.com/@/p/@/memory-sanitizer/@/wiki/@/" "MemorySanitizer}) for the detection of uninitialized memory. Both are " "based on and provide similar functionality to tools in @command{valgrind}." msgstr "" # #. type: Plain text #: R-exts.texi:8004 msgid "" "@command{clang} has a `Static Analyser' which can be run on the source files " "during compilation: see @uref{http://clang-analyzer.llvm.org/}." msgstr "" # #. type: Plain text #: R-exts.texi:8013 msgid "" "`Dr. Memory' from @uref{http://www.drmemory.org/} is a memory checker for " "(currently) 32-bit Windows, Linux and OS X with similar aims to " "@command{valgrind}. It works with unmodified executables@footnote{but works " "better if inlining and frame pointer optimizations are disabled.} and " "detects memory access errors, uninitialized reads and memory leaks." msgstr "" # #. type: Plain text #: R-exts.texi:8021 msgid "" "Most of the Fortran compilers used with @R{} allow code to be compiled with " "checking of array bounds: for example @command{gfortran} has option @option{-" "fbounds-check} and Solaris Studio has @option{-C}. This will give an error " "when the upper or lower bound is exceeded, e.g." msgstr "" # #. type: example #: R-exts.texi:8024 #, no-wrap msgid "" "At line 97 of file .../src/appl/dqrdc2.f\n" "Fortran runtime error: Index '1' of dimension 1 of array 'x' above upper bound of 0\n" msgstr "" # #. type: Plain text #: R-exts.texi:8029 msgid "" "One does need to be aware that lazy programmers often specify Fortran " "dimensions as @code{1} rather than @code{*} or a real bound and these will " "be reported." msgstr "" # #. type: Plain text #: R-exts.texi:8033 msgid "" "It is easy to arrange to use this check on just the code in your package: " "add to @file{~/.R/Makevars} something like (for @command{gfortran})" msgstr "" # #. type: example #: R-exts.texi:8036 #, no-wrap msgid "" "FCFLAGS = -g -O2 -mtune=native -fbounds-check\n" "FFLAGS = -g -O2 -mtune=native -fbounds-check\n" msgstr "" # #. type: Plain text #: R-exts.texi:8040 msgid "when you run @command{R CMD check}." msgstr "" #. type: Plain text #: R-exts.texi:8047 msgid "" "This may report incorrectly errors with the way that Fortran character " "variables are passed, particularly when Fortran subroutines are called from " "C code. This may include the use of BLAS and LAPACK subroutines in @R{}, so " "it is not advisable to build @R{} itself with bounds checking (and may not " "even be possible as these subroutines are called during the @R{} build)." msgstr "" # #. type: Plain text #: R-exts.texi:8060 msgid "" "Sooner or later programmers will be faced with the need to debug compiled " "code loaded into @R{}. This section is geared to platforms using " "@command{gdb} with code compiled by @code{gcc}, but similar things are " "possible with other debuggers such as @command{lldb} (@uref{http://lldb.llvm." "org/}, used on OS X) and Sun's @command{dbx}: some debuggers have graphical " "front-ends available." msgstr "" # #. type: Plain text #: R-exts.texi:8065 msgid "" "Consider first `crashes', that is when @R{} terminated unexpectedly with an " "illegal memory access (a `segfault' or `bus error'), illegal instruction or " "similar. Unix-alike versions of @R{} use a signal handler which aims to " "give some basic information. For example" msgstr "" # #. type: example #: R-exts.texi:8069 #, no-wrap msgid "" " *** caught segfault ***\n" "address 0x20000028, cause 'memory not mapped'\n" "\n" msgstr "" # #. type: example #: R-exts.texi:8077 #, no-wrap msgid "" "Traceback:\n" " 1: .identC(class1[[1]], class2)\n" " 2: possibleExtends(class(sloti), classi, ClassDef2 = getClassDef(classi,\n" "where = where))\n" " 3: validObject(t(cu))\n" " 4: stopifnot(validObject(cu <- as(tu, \"dtCMatrix\")), validObject(t(cu)),\n" "validObject(t(tu)))\n" "\n" msgstr "" # #. type: example #: R-exts.texi:8084 #, no-wrap msgid "" "Possible actions:\n" "1: abort (with core dump)\n" "2: normal R exit\n" "3: exit R without saving workspace\n" "4: exit R saving workspace\n" "Selection: 3\n" msgstr "" # #. type: Plain text #: R-exts.texi:8091 msgid "" "Since the @R{} process may be damaged, the only really safe options are the " "first or third. (Note that a core dump is only produced where enabled: a " "common default in a shell is to limit its size to 0, thereby disabling it.)" msgstr "" # #. type: Plain text #: R-exts.texi:8099 msgid "" "A fairly common cause of such crashes is a package which uses @code{.C} or " "@code{.Fortran} and writes beyond (at either end) one of the arguments it is " "passed. As from @R{} 3.0.0 there is a good way to detect this: using " "@code{options(CBoundsCheck = TRUE)} (which can be selected @emph{via} the " "environment variable @env{R_C_BOUNDS_CHECK=yes)} changes the way @code{.C} " "and @code{.Fortran} work to check if the compiled code writes in the 64 " "bytes at either end of an argument." msgstr "" # #. type: Plain text #: R-exts.texi:8104 msgid "" "Another cause of a `crash' is to overrun the C stack. @R{} tries to track " "that in its own code, but it may happen in third-party compiled code. For " "modern POSIX-compliant OSes @R{} can safely catch that and return to the top-" "level prompt, so one gets something like" msgstr "" # #. type: example #: R-exts.texi:8109 #, no-wrap msgid "" "> .C(\"aaa\")\n" "Error: segfault from C stack overflow\n" ">\n" msgstr "" # #. type: Plain text #: R-exts.texi:8116 msgid "" "However, C stack overflows are fatal under Windows and normally defeat " "attempts at debugging on that platform. Further, the size of the stack is " "set when @R{} is compiled, whereas on POSIX OSes it can be set in the shell " "from which @R{} is launched." msgstr "" # #. type: Plain text #: R-exts.texi:8118 msgid "If you have a crash which gives a core dump you can use something like" msgstr "" # #. type: example #: R-exts.texi:8121 #, no-wrap msgid "gdb /path/to/R/bin/exec/R core.12345\n" msgstr "" # #. type: Plain text #: R-exts.texi:8127 msgid "" "to examine the core dump. If core dumps are disabled or to catch errors " "that do not generate a dump one can run @R{} directly under a debugger by " "for example" msgstr "" # #. type: example #: R-exts.texi:8132 #, no-wrap msgid "" "$ R -d gdb --vanilla\n" "...\n" "gdb> run\n" msgstr "" # #. type: Plain text #: R-exts.texi:8139 msgid "" "at which point @R{} will run normally, and hopefully the debugger will catch " "the error and return to its prompt. This can also be used to catch infinite " "loops or interrupt very long-running code. For a simple example" msgstr "" # #. type: example #: R-exts.texi:8157 #, no-wrap msgid "" "> for(i in 1:1e7) x <- rnorm(100)\n" "[hit Ctrl-C]\n" "Program received signal SIGINT, Interrupt.\n" "0x00397682 in _int_free () from /lib/tls/libc.so.6\n" "(gdb) where\n" "#0 0x00397682 in _int_free () from /lib/tls/libc.so.6\n" "#1 0x00397eba in free () from /lib/tls/libc.so.6\n" "#2 0xb7cf2551 in R_gc_internal (size_needed=313)\n" " at /users/ripley/R/svn/R-devel/src/main/memory.c:743\n" "#3 0xb7cf3617 in Rf_allocVector (type=13, length=626)\n" " at /users/ripley/R/svn/R-devel/src/main/memory.c:1906\n" "#4 0xb7c3f6d3 in PutRNGstate ()\n" " at /users/ripley/R/svn/R-devel/src/main/RNG.c:351\n" "#5 0xb7d6c0a5 in do_random2 (call=0x94bf7d4, op=0x92580e8, args=0x9698f98,\n" " rho=0x9698f28) at /users/ripley/R/svn/R-devel/src/main/random.c:183\n" "...\n" msgstr "" # #. type: Plain text #: R-exts.texi:8163 msgid "" "In many cases it is possible to attach a debugger to a running process: this " "is helpful if an alternative front-end is in use or to investigate a task " "that seems to be taking far too long. This is done by something like" msgstr "" # #. type: example #: R-exts.texi:8166 #, no-wrap msgid "gdb -p @var{pid}\n" msgstr "" # #. type: Plain text #: R-exts.texi:8172 msgid "" "where @code{@var{pid}} is the id of the @R{} executable or front-end. This " "stops the process so its state can be examined: use @code{continue} to " "resume execution." msgstr "" # #. type: Plain text #: R-exts.texi:8174 msgid "Some ``tricks'' worth knowing follow:" msgstr "" # #. type: node #: R-exts.texi:8178 #: R-exts.texi:8180 #: R-exts.texi:8211 #, no-wrap msgid "Finding entry points" msgstr "" # #. type: node #: R-exts.texi:8178 #: R-exts.texi:8180 #: R-exts.texi:8211 #, no-wrap msgid "Inspecting R objects" msgstr "" # #. type: subsection #: R-exts.texi:8181 #, no-wrap msgid "Finding entry points in dynamically loaded code" msgstr "" # #. type: Plain text #: R-exts.texi:8187 msgid "" "Under most compilation environments, compiled code dynamically loaded into " "@R{} cannot have breakpoints set within it until it is loaded. To use a " "symbolic debugger on such dynamically loaded code under Unix-alikes use" msgstr "" # #. type: itemize #: R-exts.texi:8191 msgid "" "Call the debugger on the @R{} executable, for example by @kbd{R -d gdb}." msgstr "" # #. type: itemize #: R-exts.texi:8193 msgid "Start @R{}." msgstr "" # #. type: itemize #: R-exts.texi:8196 msgid "" "At the @R{} prompt, use @code{dyn.load} or @code{library} to load your " "shared object." msgstr "" # #. type: itemize #: R-exts.texi:8199 msgid "" "Send an interrupt signal. This will put you back to the debugger prompt." msgstr "" # #. type: itemize #: R-exts.texi:8201 msgid "Set the breakpoints in your code." msgstr "" # #. type: itemize #: R-exts.texi:8203 msgid "Continue execution of @R{} by typing @kbd{signal 0@key{RET}}." msgstr "" # #. type: Plain text #: R-exts.texi:8209 msgid "" "Under Windows signals may not be able to be used, and if so the procedure is " "more complicated. See the rw-FAQ and @uref{http://www.stats.uwo.ca/faculty/" "murdoch/software/debuggingR/gdb.shtml, @code{www.stats.uwo.ca/faculty/" "murdoch/@/software/@/debuggingR/@/gdb.shtml}}." msgstr "" # #. type: cindex #: R-exts.texi:8212 #: R-exts.texi:8213 #, no-wrap msgid "Inspecting R objects when debugging" msgstr "" # #. type: Plain text #: R-exts.texi:8219 msgid "" "The key to inspecting @R{} objects from compiled code is the function " "@code{PrintValue(SEXP @var{s})} which uses the normal @R{} printing " "mechanisms to print the @R{} object pointed to by @var{s}, or the safer " "version @code{R_PV(SEXP @var{s})} which will only print `objects'." msgstr "" # #. type: Plain text #: R-exts.texi:8222 msgid "" "One way to make use of @code{PrintValue} is to insert suitable calls into " "the code to be debugged." msgstr "" # #. type: Plain text #: R-exts.texi:8226 msgid "" "Another way is to call @code{R_PV} from the symbolic debugger. " "(@code{PrintValue} is hidden as @code{Rf_PrintValue}.) For example, from " "@code{gdb} we can use" msgstr "" # #. type: example #: R-exts.texi:8229 #, no-wrap msgid "(gdb) p R_PV(ab)\n" msgstr "" # #. type: Plain text #: R-exts.texi:8234 msgid "" "using the object @code{ab} from the convolution example, if we have placed a " "suitable breakpoint in the convolution C code." msgstr "" # #. type: Plain text #: R-exts.texi:8237 msgid "" "To examine an arbitrary @R{} object we need to work a little harder. For " "example, let" msgstr "" # #. type: example #: R-exts.texi:8240 #, no-wrap msgid "R> DF <- data.frame(a = 1:3, b = 4:6)\n" msgstr "" # #. type: Plain text #: R-exts.texi:8246 msgid "" "By setting a breakpoint at @code{do_get} and typing @kbd{get(\"DF\")} at the " "@R{} prompt, one can find out the address in memory of @code{DF}, for example" msgstr "" # #. type: group #: R-exts.texi:8270 #, no-wrap msgid "" "Value returned is $1 = (SEXPREC *) 0x40583e1c\n" "(gdb) p *$1\n" "$2 = @{\n" " sxpinfo = @{type = 19, obj = 1, named = 1, gp = 0,\n" " mark = 0, debug = 0, trace = 0, = 0@},\n" " attrib = 0x40583e80,\n" " u = @{\n" " vecsxp = @{\n" " length = 2,\n" " type = @{c = 0x40634700 \"0>X@@D>X@@0>X@@\", i = 0x40634700,\n" "\tf = 0x40634700, z = 0x40634700, s = 0x40634700@},\n" " truelength = 1075851272,\n" " @},\n" " primsxp = @{offset = 2@},\n" " symsxp = @{pname = 0x2, value = 0x40634700, internal = 0x40203008@},\n" " listsxp = @{carval = 0x2, cdrval = 0x40634700, tagval = 0x40203008@},\n" " envsxp = @{frame = 0x2, enclos = 0x40634700@},\n" " closxp = @{formals = 0x2, body = 0x40634700, env = 0x40203008@},\n" " promsxp = @{value = 0x2, expr = 0x40634700, env = 0x40203008@}\n" " @}\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:8275 msgid "(Debugger output reformatted for better legibility)." msgstr "" # #. type: Plain text #: R-exts.texi:8278 msgid "" "Using @code{R_PV()} one can ``inspect'' the values of the various elements " "of the SEXP, for example," msgstr "" # #. type: group #: R-exts.texi:8284 #, no-wrap msgid "" "(gdb) p R_PV($1->attrib)\n" "$names\n" "[1] \"a\" \"b\"\n" "\n" msgstr "" # #. type: group #: R-exts.texi:8287 #, no-wrap msgid "" "$row.names\n" "[1] \"1\" \"2\" \"3\"\n" "\n" msgstr "" # #. type: group #: R-exts.texi:8290 #, no-wrap msgid "" "$class\n" "[1] \"data.frame\"\n" "\n" msgstr "" # #. type: group #: R-exts.texi:8292 #, no-wrap msgid "$3 = void\n" msgstr "" # #. type: Plain text #: R-exts.texi:8297 msgid "" "To find out where exactly the corresponding information is stored, one needs " "to go ``deeper'':" msgstr "" # #. type: group #: R-exts.texi:8309 #, no-wrap msgid "" "(gdb) set $a = $1->attrib\n" "(gdb) p $a->u.listsxp.tagval->u.symsxp.pname->u.vecsxp.type.c\n" "$4 = 0x405d40e8 \"names\"\n" "(gdb) p $a->u.listsxp.carval->u.vecsxp.type.s[1]->u.vecsxp.type.c\n" "$5 = 0x40634378 \"b\"\n" "(gdb) p $1->u.vecsxp.type.s[0]->u.vecsxp.type.i[0]\n" "$6 = 1\n" "(gdb) p $1->u.vecsxp.type.s[1]->u.vecsxp.type.i[1]\n" "$7 = 5\n" msgstr "" # #. type: Plain text #: R-exts.texi:8315 msgid "" "Another alternative is the @code{R_inspect} function which shows the low-" "level structure of the objects recursively (addresses differ from the above " "as this example is created on another machine):" msgstr "" # #. type: group #: R-exts.texi:8333 #, no-wrap msgid "" "(gdb) p R_inspect($1)\n" "@@100954d18 19 VECSXP g0c2 [OBJ,NAM(2),ATT] (len=2, tl=0)\n" " @@100954d50 13 INTSXP g0c2 [NAM(2)] (len=3, tl=0) 1,2,3\n" " @@100954d88 13 INTSXP g0c2 [NAM(2)] (len=3, tl=0) 4,5,6\n" "ATTRIB:\n" " @@102a70140 02 LISTSXP g0c0 []\n" " TAG: @@10083c478 01 SYMSXP g0c0 [MARK,NAM(2),gp=0x4000] \"names\"\n" " @@100954dc0 16 STRSXP g0c2 [NAM(2)] (len=2, tl=0)\n" " @@10099df28 09 CHARSXP g0c1 [MARK,gp=0x21] \"a\"\n" " @@10095e518 09 CHARSXP g0c1 [MARK,gp=0x21] \"b\"\n" " TAG: @@100859e60 01 SYMSXP g0c0 [MARK,NAM(2),gp=0x4000] \"row.names\"\n" " @@102a6f868 13 INTSXP g0c1 [NAM(2)] (len=2, tl=1) -2147483648,-3\n" " TAG: @@10083c948 01 SYMSXP g0c0 [MARK,gp=0x4000] \"class\"\n" " @@102a6f838 16 STRSXP g0c1 [NAM(2)] (len=1, tl=1)\n" " @@1008c6d48 09 CHARSXP g0c2 [MARK,gp=0x21,ATT] \"data.frame\"\n" msgstr "" # #. type: Plain text #: R-exts.texi:8337 msgid "In general the representation of each object follows the format:" msgstr "" # #. type: smallexample #: R-exts.texi:8340 #, no-wrap msgid "@@<address> <type-nr> <type-name> <gc-info> [<flags>] ...\n" msgstr "" #. type: Plain text #: R-exts.texi:8347 msgid "" "For a more fine-grained control over the depth of the recursion and the " "output of vectors @code{R_inspect3} takes additional two character() " "parameters: maximum depth and the maximal number of elements that will be " "printed for scalar vectors. The defaults in @code{R_inspect} are currently " "-1 (no limit) and 5 respectively." msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:8370 #: R-exts.texi:8371 #: R-exts.texi:8372 #: R-exts.texi:8394 #, no-wrap msgid "Operating system access" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:8370 #: R-exts.texi:8394 #: R-exts.texi:8563 #, no-wrap msgid "Interface functions .C and .Fortran" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:8394 #: R-exts.texi:8563 #: R-exts.texi:8693 #, no-wrap msgid "dyn.load and dyn.unload" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:8563 #: R-exts.texi:8693 #: R-exts.texi:8694 #: R-exts.texi:8695 #: R-exts.texi:8872 #: R-exts.texi:8939 #: R-exts.texi:8991 #, no-wrap msgid "Registering native routines" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:8693 #: R-exts.texi:8991 #: R-exts.texi:8992 #: R-exts.texi:8993 #: R-exts.texi:9108 #, no-wrap msgid "Creating shared objects" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:8991 #: R-exts.texi:9108 #: R-exts.texi:9109 #: R-exts.texi:9110 #: R-exts.texi:9236 #, no-wrap msgid "Interfacing C++ code" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:9108 #: R-exts.texi:9236 #: R-exts.texi:9237 #: R-exts.texi:9254 #, no-wrap msgid "Fortran I/O" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:9236 #: R-exts.texi:9254 #: R-exts.texi:9255 #: R-exts.texi:9276 #: R-exts.texi:9350 #: R-exts.texi:9427 #, no-wrap msgid "Linking to other packages" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:9254 #: R-exts.texi:9427 #: R-exts.texi:9428 #: R-exts.texi:9429 #: R-exts.texi:9552 #: R-exts.texi:9670 #: R-exts.texi:9692 #: R-exts.texi:9768 #: R-exts.texi:9909 #: R-exts.texi:9939 #: R-exts.texi:10000 #: R-exts.texi:10032 #: R-exts.texi:10092 #: R-exts.texi:10171 #: R-exts.texi:10257 #, no-wrap msgid "Handling R objects in C" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:9427 #: R-exts.texi:10257 #: R-exts.texi:10274 #: R-exts.texi:10315 #: R-exts.texi:10456 #: R-exts.texi:10502 #, no-wrap msgid "Interface functions .Call and .External" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:10257 #: R-exts.texi:10502 #: R-exts.texi:10503 #: R-exts.texi:10504 #: R-exts.texi:10633 #: R-exts.texi:10716 #: R-exts.texi:10939 #, no-wrap msgid "Evaluating R expressions from C" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:10502 #: R-exts.texi:10939 #: R-exts.texi:10940 #: R-exts.texi:10941 #: R-exts.texi:11008 #: R-exts.texi:11038 #, no-wrap msgid "Parsing R code from C" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:10939 #: R-exts.texi:11038 #: R-exts.texi:11039 #: R-exts.texi:11162 #: R-exts.texi:11213 #, no-wrap msgid "External pointers and weak references" msgstr "" # #. type: node #: R-exts.texi:8368 #: R-exts.texi:11038 #: R-exts.texi:11213 #: R-exts.texi:11214 #: R-exts.texi:11234 #, no-wrap msgid "Vector accessor functions" msgstr "" # #. type: section #: R-exts.texi:8368 #: R-exts.texi:11213 #: R-exts.texi:11234 #: R-exts.texi:11235 #, no-wrap msgid "Character encoding issues" msgstr "" # #. type: Plain text #: R-exts.texi:8376 msgid "" "Access to operating system functions is @emph{via} the @R{} functions " "@code{system} and @code{system2}." msgstr "" # #. type: findex #: R-exts.texi:8376 #, no-wrap msgid "system" msgstr "" # #. type: findex #: R-exts.texi:8377 #, no-wrap msgid "system2" msgstr "" # #. type: Plain text #: R-exts.texi:8384 msgid "" "The details will differ by platform (see the on-line help), and about all " "that can safely be assumed is that the first argument will be a string " "@code{command} that will be passed for execution (not necessarily by a " "shell) and the second argument to @code{system} will be @code{internal} " "which if true will collect the output of the command into an @R{} character " "vector." msgstr "" # #. type: Plain text #: R-exts.texi:8388 msgid "" "On POSIX-compliant OSes these commands pass a command-line to a shell: " "Windows is not POSIX-compliant and there is a separate function @code{shell} " "to do so." msgstr "" # #. type: Plain text #: R-exts.texi:8390 msgid "The function @code{system.time}" msgstr "" # #. type: findex #: R-exts.texi:8390 #, no-wrap msgid "system.time" msgstr "" # #. type: Plain text #: R-exts.texi:8393 msgid "" "is available for timing. Timing on child processes is only available on " "Unix-alikes, and may not be reliable there." msgstr "" # #. type: section #: R-exts.texi:8395 #, no-wrap msgid "Interface functions @code{.C} and @code{.Fortran}" msgstr "" # #. type: cindex #: R-exts.texi:8396 #: R-exts.texi:10259 #, no-wrap msgid "Interfaces to compiled code" msgstr "" # #. type: findex #: R-exts.texi:8398 #, no-wrap msgid ".C" msgstr "" # #. type: findex #: R-exts.texi:8399 #, no-wrap msgid ".Fortran" msgstr "" # #. type: Plain text #: R-exts.texi:8407 msgid "" "These two functions provide an interface to compiled code that has been " "linked into @R{}, either at build time or @emph{via} @code{dyn.load} " "(@pxref{dyn.load and dyn.unload}). They are primarily intended for compiled " "C and FORTRAN 77 code respectively, but the @code{.C} function can be used " "with other languages which can generate C interfaces, for example C++ " "(@pxref{Interfacing C++ code})." msgstr "" # #. type: Plain text #: R-exts.texi:8415 msgid "" "The first argument to each function is a character string specifying the " "symbol name as known@footnote{possibly after some platform-specific " "translation, e.g.@: adding leading or trailing underscores.} to C or " "FORTRAN, that is the function or subroutine name. (That the symbol is " "loaded can be tested by, for example, @code{is.loaded(\"cg\")}. Use the " "name you pass to @code{.C} or @code{.Fortran} rather than the translated " "symbol name.)" msgstr "" # #. type: Plain text #: R-exts.texi:8422 msgid "" "There can be up to 65 further arguments giving @R{} objects to be passed to " "compiled code. Normally these are copied before being passed in, and copied " "again to an @R{} list object when the compiled code returns. If the " "arguments are given names, these are used as names for the components in the " "returned list object (but not passed to the compiled code)." msgstr "" # #. type: Plain text #: R-exts.texi:8426 msgid "" "The following table gives the mapping between the modes of @R{} atomic " "vectors and the types of arguments to a C function or FORTRAN subroutine." msgstr "" # #. type: multitable #: R-exts.texi:8430 msgid "@headitem @R{} storage mode" msgstr "" # #. type: multitable #: R-exts.texi:8430 msgid "C type" msgstr "" # #. type: multitable #: R-exts.texi:8430 msgid "FORTRAN type" msgstr "" # #. type: item #: R-exts.texi:8430 #, no-wrap msgid "@code{logical} @tab @code{int *} @tab @code{INTEGER}" msgstr "" # #. type: item #: R-exts.texi:8431 #, no-wrap msgid "@code{integer} @tab @code{int *} @tab @code{INTEGER}" msgstr "" # #. type: item #: R-exts.texi:8432 #, no-wrap msgid "@code{double} @tab @code{double *} @tab @code{DOUBLE PRECISION}" msgstr "" # #. type: item #: R-exts.texi:8433 #, no-wrap msgid "@code{complex} @tab @code{Rcomplex *} @tab @code{DOUBLE COMPLEX}" msgstr "" # #. type: item #: R-exts.texi:8434 #, no-wrap msgid "@code{character} @tab @code{char **} @tab @code{CHARACTER*255}" msgstr "" # #. type: item #: R-exts.texi:8435 #, no-wrap msgid "@code{raw} @tab @code{unsigned char *} @tab none" msgstr "" # #. type: Plain text #: R-exts.texi:8446 msgid "" "Do please note the first two. On the 64-bit Unix/Linux/OS X platforms, " "@code{long} is 64-bit whereas @code{int} and @code{INTEGER} are 32-bit. " "Code ported from S-PLUS (which uses @code{long *} for @code{logical} and " "@code{integer}) will not work on all 64-bit platforms (although it may " "appear to work on some, including Windows). Note also that if your compiled " "code is a mixture of C functions and FORTRAN subprograms the argument types " "must match as given in the table above." msgstr "" # #. type: Plain text #: R-exts.texi:8455 msgid "" "C type @code{Rcomplex} is a structure with @code{double} members @code{r} " "and @code{i} defined in the header file @file{R_ext/Complex.h} included by " "@file{R.h}. (On most platforms this is stored in a way compatible with the " "C99 @code{double complex} type: however, it may not be possible to pass " "@code{Rcomplex} to a C99 function expecting a @code{double complex} " "argument. Nor need it be compatible with a C++ @code{complex} type. " "Moreover, the compatibility can depends on the optimization level set for " "the compiler.)" msgstr "" # #. type: Plain text #: R-exts.texi:8459 msgid "" "Only a single character string can be passed to or from FORTRAN, and the " "success of this is compiler-dependent. Other @R{} objects can be passed to " "@code{.C}, but it is much better to use one of the other interfaces." msgstr "" # #. type: Plain text #: R-exts.texi:8465 msgid "" "It is possible to pass numeric vectors of storage mode @code{double} to C as " "@code{float *} or to FORTRAN as @code{REAL} by setting the attribute " "@code{Csingle}, most conveniently by using the @R{} functions @code{as." "single}, @code{single} or @code{mode}. This is intended only to be used to " "aid interfacing existing C or FORTRAN code." msgstr "" # #. type: Plain text #: R-exts.texi:8471 msgid "" "Logical values are sent as @code{0} (@code{FALSE}), @code{1} (@code{TRUE}) " "or @code{INT_MIN = -2147483648} (@code{NA}, but only if @code{NAOK} is " "true), and the compiled code should return one of these three values. (Non-" "zero values other than @code{INT_MIN} are mapped to @code{TRUE}.)" msgstr "" # #. type: Plain text #: R-exts.texi:8477 msgid "" "Unless formal argument @code{NAOK} is true, all the other arguments are " "checked for missing values @code{NA} and for the @acronym{IEEE} special " "values @code{NaN}, @code{Inf} and @code{-Inf}, and the presence of any of " "these generates an error. If it is true, these values are passed unchecked." msgstr "" # #. type: Plain text #: R-exts.texi:8489 msgid "" "Argument @code{PACKAGE} confines the search for the symbol name to a " "specific shared object (or use @code{\"base\"} for code compiled into " "@R{}). Its use is highly desirable, as there is no way to avoid two package " "writers using the same symbol name, and such name clashes are normally " "sufficient to cause @R{} to crash. (If it is not present and the call is " "from the body of a function defined in a package namespace, the shared " "object loaded by the first (if any) @code{useDynLib} directive will be " "used. However, prior to @R{} 2.15.2 the detection of the correct namespace " "is unreliable and you are strongly recommended to use the @code{PACKAGE} " "argument for packages to be used with earlier versions of @R{}." msgstr "" # #. type: Plain text #: R-exts.texi:8493 msgid "" "Note that the compiled code should not return anything except through its " "arguments: C functions should be of type @code{void} and FORTRAN subprograms " "should be subroutines." msgstr "" # #. type: Plain text #: R-exts.texi:8497 msgid "" "To fix ideas, let us consider a very simple example which convolves two " "finite sequences. (This is hard to do fast in interpreted @R{} code, but " "easy in C code.) We could do this using @code{.C} by" msgstr "" # #. type: group #: R-exts.texi:8503 #, no-wrap msgid "" "void convolve(double *a, int *na, double *b, int *nb, double *ab)\n" "@{\n" " int nab = *na + *nb - 1;\n" "\n" msgstr "" # #. type: group #: R-exts.texi:8510 #, no-wrap msgid "" " for(int i = 0; i < nab; i++)\n" "\tab[i] = 0.0;\n" " for(int i = 0; i < *na; i++)\n" "\tfor(int j = 0; j < *nb; j++)\n" "\t ab[i + j] += a[i] * b[j];\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:8515 msgid "called from @R{} by" msgstr "" # #. type: group #: R-exts.texi:8525 #, no-wrap msgid "" "conv <- function(a, b)\n" " .C(\"convolve\",\n" " as.double(a),\n" " as.integer(length(a)),\n" " as.double(b),\n" " as.integer(length(b)),\n" " ab = double(length(a) + length(b) - 1))$ab\n" msgstr "" # #. type: Plain text #: R-exts.texi:8531 msgid "" "Note that we take care to coerce all the arguments to the correct @R{} " "storage mode before calling @code{.C}; mistakes in matching the types can " "lead to wrong results or hard-to-catch errors." msgstr "" # #. type: Plain text #: R-exts.texi:8544 msgid "" "Special care is needed in handling @code{character} vector arguments in C " "(or C++). On entry the contents of the elements are duplicated and assigned " "to the elements of a @code{char **} array, and on exit the elements of the C " "array are copied to create new elements of a character vector. This means " "that the contents of the character strings of the @code{char **} array can " "be changed, including to @code{\\0} to shorten the string, but the strings " "cannot be lengthened. It is possible@footnote{Note that this is then not " "checked for over-runs by option @code{CBoundsCheck = TRUE}.} to allocate a " "new string @emph{via} @code{R_alloc} and replace an entry in the @code{char " "**} array by the new string. However, when character vectors are used other " "than in a read-only way, the @code{.Call} interface is much to be preferred." msgstr "" # #. type: Plain text #: R-exts.texi:8556 msgid "" "Passing character strings to FORTRAN code needs even more care, and should " "be avoided where possible. Only the first element of the character vector " "is passed in, as a fixed-length (255) character array. Up to 255 characters " "are passed back to a length-one character vector. How well this works (or " "even if it works at all) depends on the C and FORTRAN compilers on each " "platform (including on their options). Often what is being passed to " "FORTRAN is one of a small set of possible values (a factor in @R{} terms) " "which could alternatively be passed as an integer code: similarly FORTRAN " "code that wants to generate diagnostic messages can pass an integer code to " "a C or @R{} wrapper which will convert it to a character string." msgstr "" # #. type: Plain text #: R-exts.texi:8562 msgid "" "It is possible to pass some @R{} objects other than atomic vectors via " "@code{.C}, but this is only supported for historical compatibility: use the " "@code{.Call} or @code{.External} interfaces for such objects. Any C/C++ " "code that includes @file{Rinternals.h} should be called via @code{.Call} or " "@code{.External}." msgstr "" # #. type: section #: R-exts.texi:8564 #, no-wrap msgid "@code{dyn.load} and @code{dyn.unload}" msgstr "" # #. type: cindex #: R-exts.texi:8565 #, no-wrap msgid "Dynamic loading" msgstr "" # #. type: findex #: R-exts.texi:8567 #, no-wrap msgid "dyn.load" msgstr "" # #. type: findex #: R-exts.texi:8568 #, no-wrap msgid "dyn.unload" msgstr "" # #. type: Plain text #: R-exts.texi:8573 msgid "" "Compiled code to be used with @R{} is loaded as a shared object (Unix-alikes " "including OS X, @pxref{Creating shared objects} for more information) or DLL " "(Windows)." msgstr "" # #. type: Plain text #: R-exts.texi:8578 msgid "" "The shared object/DLL is loaded by @code{dyn.load} and unloaded by @code{dyn." "unload}. Unloading is not normally necessary, but it is needed to allow the " "DLL to be re-built on some platforms, including Windows." msgstr "" # #. type: Plain text #: R-exts.texi:8583 msgid "" "The first argument to both functions is a character string giving the path " "to the object. Programmers should not assume a specific file extension for " "the object/DLL (such as @file{.so}) but use a construction like" msgstr "" # #. type: example #: R-exts.texi:8586 #, no-wrap msgid "file.path(path1, path2, paste0(\"mylib\", .Platform$dynlib.ext))\n" msgstr "" # #. type: Plain text #: R-exts.texi:8593 msgid "" "for platform independence. On Unix-alike systems the path supplied to " "@code{dyn.load} can be an absolute path, one relative to the current " "directory or, if it starts with @samp{~}, relative to the user's home " "directory." msgstr "" # #. type: Plain text #: R-exts.texi:8597 msgid "" "Loading is most often done automatically based on the @code{useDynLib()} " "declaration in the @file{NAMESPACE} file, but may be done explicitly " "@emph{via} a call to @code{library.dynam}." msgstr "" # #. type: Plain text #: R-exts.texi:8599 msgid "This has the form" msgstr "" # #. type: example #: R-exts.texi:8602 #, no-wrap msgid "library.dynam(\"libname\", package, lib.loc)\n" msgstr "" # #. type: Plain text #: R-exts.texi:8609 msgid "" "where @code{libname} is the object/DLL name @emph{with the extension " "omitted}. Note that the first argument, @code{chname}, should @strong{not} " "be @code{package} since this will not work if the package is installed under " "another name." msgstr "" # #. type: Plain text #: R-exts.texi:8615 msgid "" "Under some Unix-alike systems there is a choice of how the symbols are " "resolved when the object is loaded, governed by the arguments @code{local} " "and @code{now}. Only use these if really necessary: in particular using " "@code{now=FALSE} and then calling an unresolved symbol will terminate @R{} " "unceremoniously." msgstr "" # #. type: Plain text #: R-exts.texi:8623 msgid "" "@R{} provides a way of executing some code automatically when a object/DLL " "is either loaded or unloaded. This can be used, for example, to register " "native routines with @R{}'s dynamic symbol mechanism, initialize some data " "in the native code, or initialize a third party library. On loading a DLL, " "@R{} will look for a routine within that DLL named @code{R_init_@var{lib}} " "where @var{lib} is the name of the DLL file with the extension removed. For " "example, in the command" msgstr "" # #. type: example #: R-exts.texi:8626 #, no-wrap msgid "library.dynam(\"mylib\", package, lib.loc)\n" msgstr "" # #. type: Plain text #: R-exts.texi:8636 msgid "" "R looks for the symbol named @code{R_init_mylib}. Similarly, when unloading " "the object, @R{} looks for a routine named @code{R_unload_@var{lib}}, e.g., " "@code{R_unload_mylib}. In either case, if the routine is present, @R{} will " "invoke it and pass it a single argument describing the DLL. This is a value " "of type @code{DllInfo} which is defined in the @file{Rdynload.h} file in the " "@file{R_ext} directory." msgstr "" # #. type: Plain text #: R-exts.texi:8643 msgid "" "Note that there are some implicit restrictions on this mechanism as the " "basename of the DLL needs to be both a valid file name and valid as part of " "a C entry point (e.g.@: it cannot contain @samp{.}): for portable code it is " "best to confine DLL names to be @acronym{ASCII} alphanumeric plus " "underscore. If entry point @code{R_init_@var{lib}} is not found it is also " "looked for with @samp{.} replaced by @samp{_}." msgstr "" # #. type: Plain text #: R-exts.texi:8647 msgid "" "The following example shows templates for the initialization and unload " "routines for the @code{mylib} DLL." msgstr "" # #. type: example #: R-exts.texi:8654 #, no-wrap msgid "" "#include <R.h>\n" "#include <Rinternals.h>\n" "#include <R_ext/Rdynload.h>\n" "\n" msgstr "" # #. type: example #: R-exts.texi:8661 #, no-wrap msgid "" "void\n" "R_init_mylib(DllInfo *info)\n" "@{\n" " /* Register routines,\n" " allocate resources. */\n" "@}\n" "\n" msgstr "" # #. type: example #: R-exts.texi:8667 #, no-wrap msgid "" "void\n" "R_unload_mylib(DllInfo *info)\n" "@{\n" " /* Release resources. */\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:8676 msgid "" "If a shared object/DLL is loaded more than once the most recent version is " "used. More generally, if the same symbol name appears in several shared " "objects, the most recently loaded occurrence is used. The @code{PACKAGE} " "argument and registration (see the next section) provide good ways to avoid " "any ambiguity in which occurrence is meant." msgstr "" # #. type: Plain text #: R-exts.texi:8682 msgid "" "On Unix-alikes the paths used to resolve dynamically linked dependent " "libraries are fixed (for security reasons) when the process is launched, so " "@code{dyn.load} will only look for such libraries in the locations set by " "the @file{R} shell script (@emph{via} @file{etc/ldpaths}) and in the OS-" "specific defaults." msgstr "" # #. type: Plain text #: R-exts.texi:8691 msgid "" "Windows allows more control (and less security) over where dependent DLLs " "are looked for. On all versions this includes the @env{PATH} environment " "variable, but with lowest priority: note that it does not include the " "directory from which the DLL was loaded. It is possible to add a single " "path with quite high priority @emph{via} the @code{DLLpath} argument to " "@code{dyn.load}. This is (by default) used by @code{library.dynam} to " "include the package's @file{libs/i386} or @file{libs/x64} directory in the " "DLL search path." msgstr "" # #. type: Plain text #: R-exts.texi:8698 msgid "By `native' routine, we mean an entry point in compiled code." msgstr "" # #. type: Plain text #: R-exts.texi:8711 msgid "" "In calls to @code{.C}, @code{.Call}, @code{.Fortran} and @code{.External}, " "@R{} must locate the specified native routine by looking in the appropriate " "shared object/DLL. By default, @R{} uses the operating system-specific " "dynamic loader to lookup the symbol in all loaded DLLs and elsewhere. " "Alternatively, the author of the DLL can explicitly register routines with " "@R{} and use a single, platform-independent mechanism for finding the " "routines in the DLL. One can use this registration mechanism to provide " "additional information about a routine, including the number and type of the " "arguments, and also make it available to @R{} programmers under a different " "name. In the future, registration may be used to implement a form of " "``secure'' or limited native access." msgstr "" # #. type: findex #: R-exts.texi:8712 #, no-wrap msgid "R_registerRoutines" msgstr "" # #. type: Plain text #: R-exts.texi:8724 msgid "" "To register routines with @R{}, one calls the C routine " "@code{R_registerRoutines}. This is typically done when the DLL is first " "loaded within the initialization routine @code{R_init_@var{dll name}} " "described in @ref{dyn.load and dyn.unload}. @code{R_registerRoutines} takes " "5 arguments. The first is the @code{DllInfo} object passed by @R{} to the " "initialization routine. This is where @R{} stores the information about the " "methods. The remaining 4 arguments are arrays describing the routines for " "each of the 4 different interfaces: @code{.C}, @code{.Call}, @code{.Fortran} " "and @code{.External}. Each argument is a @code{FIND}-terminated array of " "the element types given in the following table:" msgstr "" # #. type: item #: R-exts.texi:8727 #, no-wrap msgid "@code{.C} @tab @code{R_CMethodDef}" msgstr "" # #. type: item #: R-exts.texi:8728 #, no-wrap msgid "@code{.Call} @tab @code{R_CallMethodDef}" msgstr "" # #. type: item #: R-exts.texi:8729 #, no-wrap msgid "@code{.Fortran} @tab @code{R_FortranMethodDef}" msgstr "" # #. type: item #: R-exts.texi:8730 #, no-wrap msgid "@code{.External} @tab @code{R_ExternalMethodDef}" msgstr "" # #. type: Plain text #: R-exts.texi:8740 msgid "" "Currently, the @code{R_ExternalMethodDef} is the same as " "@code{R_CallMethodDef} type and contains fields for the name of the routine " "by which it can be accessed in @R{}, a pointer to the actual native symbol " "(i.e., the routine itself), and the number of arguments the routine expects " "to be passed from @R{}. For example, if we had a routine named @code{myCall} " "defined as" msgstr "" # #. type: example #: R-exts.texi:8743 #, no-wrap msgid "SEXP myCall(SEXP a, SEXP b, SEXP c);\n" msgstr "" # #. type: Plain text #: R-exts.texi:8747 msgid "we would describe this as" msgstr "" # #. type: example #: R-exts.texi:8753 #, no-wrap msgid "" "static R_CallMethodDef callMethods[] = @{\n" " @{\"myCall\", (DL_FUNC) &myCall, 3@},\n" " @{NULL, NULL, 0@}\n" "@};\n" msgstr "" # #. type: Plain text #: R-exts.texi:8762 msgid "" "along with any other routines for the @code{.Call} interface. For routines " "with a variable number of arguments invoked @emph{via} the @code{.External} " "interface, one specifies @code{-1} for the number of arguments which tells " "@R{} not to check the actual number passed. Note that the number of " "arguments passed to @code{.External} were not checked prior to @R{} 3.0.0." msgstr "" # #. type: Plain text #: R-exts.texi:8773 msgid "" "Routines for use with the @code{.C} and @code{.Fortran} interfaces are " "described with similar data structures, but which have two additional fields " "for describing the type and ``style'' of each argument. Each of these can " "be omitted. However, if specified, each should be an array with the same " "number of elements as the number of parameters for the routine. The types " "array should contain the @code{SEXP} types describing the expected type of " "the argument. (Technically, the elements of the types array are of type " "@code{R_NativePrimitiveArgType} which is just an unsigned integer.) The " "@R{} types and corresponding type identifiers are provided in the following " "table:" msgstr "" # #. type: item #: R-exts.texi:8776 #, no-wrap msgid "@code{numeric} @tab @code{REALSXP}" msgstr "" # #. type: item #: R-exts.texi:8777 #, no-wrap msgid "@code{integer} @tab @code{INTSXP}" msgstr "" # #. type: item #: R-exts.texi:8778 #, no-wrap msgid "@code{logical} @tab @code{LGLSXP}" msgstr "" # #. type: item #: R-exts.texi:8779 #, no-wrap msgid "@code{single} @tab @code{SINGLESXP}" msgstr "" # #. type: item #: R-exts.texi:8780 #, no-wrap msgid "@code{character} @tab @code{STRSXP}" msgstr "" # #. type: item #: R-exts.texi:8781 #, no-wrap msgid "@code{list} @tab @code{VECSXP}" msgstr "" # #. type: Plain text #: R-exts.texi:8786 msgid "Consider a C routine, @code{myC}, declared as" msgstr "" # #. type: example #: R-exts.texi:8789 #, no-wrap msgid "void myC(double *x, int *n, char **names, int *status);\n" msgstr "" # #. type: Plain text #: R-exts.texi:8792 msgid "We would register it as" msgstr "" # #. type: example #: R-exts.texi:8797 #, no-wrap msgid "" "static R_NativePrimitiveArgType myC_t[] = @{\n" " REALSXP, INTSXP, STRSXP, LGLSXP\n" "@};\n" "\n" msgstr "" # #. type: example #: R-exts.texi:8802 #, no-wrap msgid "" "static R_CMethodDef cMethods[] = @{\n" " @{\"myC\", (DL_FUNC) &myC, 4, myC_t@}\n" " @{NULL, NULL, 0@}\n" "@};\n" msgstr "" # #. type: Plain text #: R-exts.texi:8811 msgid "" "One can also specify whether each argument is used simply as input, or as " "output, or as both input and output. The style field in the description of " "a method is used for this. The purpose is to allow@footnote{but this is not " "currently done.} @R{} to transfer values more efficiently across the @R{}-C/" "FORTRAN interface by avoiding copying values when it is not necessary. " "Typically, one omits this information in the registration data." msgstr "" # #. type: Plain text #: R-exts.texi:8817 msgid "" "Having created the arrays describing each routine, the last step is to " "actually register them with @R{}. We do this by calling " "@code{R_registerRoutines}. For example, if we have the descriptions above " "for the routines accessed by the @code{.C} and @code{.Call} we would use the " "following code:" msgstr "" # #. type: example #: R-exts.texi:8824 #, no-wrap msgid "" "void\n" "R_init_myLib(DllInfo *info)\n" "@{\n" " R_registerRoutines(info, cMethods, callMethods, NULL, NULL);\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:8831 msgid "" "This routine will be invoked when @R{} loads the shared object/DLL named " "@code{myLib}. The last two arguments in the call to " "@code{R_registerRoutines} are for the routines accessed by @code{.Fortran} " "and @code{.External} interfaces. In our example, these are given as " "@code{NULL} since we have no routines of these types." msgstr "" # #. type: Plain text #: R-exts.texi:8835 msgid "" "When @R{} unloads a shared object/DLL, its registrations are automatically " "removed. There is no other facility for unregistering a symbol." msgstr "" #. type: Plain text #: R-exts.texi:8840 msgid "" "Examples of registering routines can be found in the different packages in " "the @R{} source tree (e.g., @pkg{stats}). Also, there is a brief, high-" "level introduction in @emph{R News} (volume 1/3, September 2001, pages " "20--23, @uref{https://www.r-project.org/@/doc/@/Rnews/Rnews_2001-3.pdf})." msgstr "" # #. type: Plain text #: R-exts.texi:8847 msgid "" "Once routines are registered, they can be referred to as @R{} objects if " "they this is arranged in the @code{useDynLib} call in the package's " "@file{NAMESPACE} file (see @ref{useDynLib}). This avoids the overhead of " "looking up an entry point each time it is used, and ensure that the entry " "point in the package is the one used (without a @code{PACKAGE = \"pkg\"} " "argument). So for example the @pkg{stats} package has" msgstr "" # #. type: example #: R-exts.texi:8850 #, no-wrap msgid "" "# Refer to all C/Fortran routines by their name prefixed by C_\n" "useDynLib(stats, .registration = TRUE, .fixes = \"C_\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:8853 msgid "" "in its @file{NAMESPACE} file, and then @code{ansari.test}'s default methods " "can contain" msgstr "" # #. type: example #: R-exts.texi:8857 #, no-wrap msgid "" "\tpansari <- function(q, m, n)\n" "\t .C(C_pansari, as.integer(length(q)), p = as.double(q),\n" "\t\tas.integer(m), as.integer(n))$p\n" msgstr "" # #. type: node #: R-exts.texi:8870 #: R-exts.texi:8872 #: R-exts.texi:8873 #: R-exts.texi:8939 #, no-wrap msgid "Speed considerations" msgstr "" # #. type: subsection #: R-exts.texi:8870 #: R-exts.texi:8872 #: R-exts.texi:8939 #: R-exts.texi:8940 #, no-wrap msgid "Linking to native routines in other packages" msgstr "" # #. type: Plain text #: R-exts.texi:8879 msgid "" "Sometimes registering native routines or using a @code{PACKAGE} argument can " "make a large difference. The results can depend quite markedly on the OS " "(and even if it is 32- or 64-bit), on the version of @R{} and what else is " "loaded into @R{} at the time." msgstr "" # #. type: Plain text #: R-exts.texi:8882 msgid "" "To fix ideas, first consider @code{x84_64} OS 10.7 and @R{} 2.15.2. A " "simple @code{.Call} function might be" msgstr "" # #. type: example #: R-exts.texi:8884 #, no-wrap msgid "foo <- function(x) .Call(\"foo\", x)\n" msgstr "" # #. type: Plain text #: R-exts.texi:8886 #: R-exts.texi:10530 msgid "with C code" msgstr "" # #. type: example #: R-exts.texi:8891 #, no-wrap msgid "" "SEXP foo(SEXP x)\n" "@{\n" " return x;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:8895 msgid "" "If we compile with by @command{R CMD SHLIB foo.c}, load the code by " "@code{dyn.load(\"foo.so\")} and run @code{foo(pi)} it took around 22 " "microseconds (us). Specifying the DLL by" msgstr "" # #. type: example #: R-exts.texi:8897 #, no-wrap msgid "foo2 <- function(x) .Call(\"foo\", x, PACKAGE = \"foo\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:8899 msgid "reduced the time to 1.7 us." msgstr "" # #. type: Plain text #: R-exts.texi:8907 msgid "" "Now consider making these functions part of a package whose @file{NAMESPACE} " "file uses @code{useDynlib(foo)}. This immediately reduces the running time " "as @code{\"foo\"} will be preferentially looked for @file{foo.dll}. Without " "specifying @code{PACKAGE} it took about 5 us (it needs to fathom out the " "appropriate DLL each time it is invoked but it does not need to search all " "DLLs), and with the @code{PACKAGE} argument it is again about 1.7 us." msgstr "" # #. type: Plain text #: R-exts.texi:8913 msgid "" "Next suppose the package has registered the native routine @code{foo}. Then " "@code{foo()} still has to find the appropriate DLL but can get to the entry " "point in the DLL faster, in about 4.2 us. And @code{foo2()} now takes about " "1 us. If we register the symbols in the @file{NAMESPACE} file and use" msgstr "" # #. type: example #: R-exts.texi:8915 #, no-wrap msgid "foo3 <- function(x) .Call(C_foo, x)\n" msgstr "" # #. type: Plain text #: R-exts.texi:8918 msgid "" "then the address for the native routine is looked up just once when the " "package is loaded, and @code{foo3(pi)} takes about 0.8 us." msgstr "" # #. type: Plain text #: R-exts.texi:8921 msgid "" "Versions using @code{.C()} rather than @code{.Call()} take about 0.2 us " "longer." msgstr "" # #. type: Plain text #: R-exts.texi:8925 msgid "" "These are all quite small differences, but C routines are not uncommonly " "invoked millions of times for run times of a few microseconds, and those " "doing such things may wish to be aware of the differences." msgstr "" # #. type: Plain text #: R-exts.texi:8929 msgid "" "On Linux and Solaris there is a much smaller overhead in looking up symbols " "so @code{foo(pi)} takes around 5 times as long as @code{foo3(pi)}." msgstr "" # #. type: Plain text #: R-exts.texi:8936 msgid "" "Symbol lookup on Windows used to be far slower, so @R{} maintains a small " "cache. If the cache is currently empty enough that the symbol can be stored " "in the cache then the performance is similar to Linux and Solaris: if not it " "may be slower. @R{}'s own code always uses registered symbols and so these " "never contribute to the cache: however many other packages do rely on symbol " "lookup." msgstr "" # #. type: Plain text #: R-exts.texi:8946 msgid "" "In addition to registering C routines to be called by @R{}, it can at times " "be useful for one package to make some of its C routines available to be " "called by C code in another package. The interface consists of two routines " "declared in header @file{R_ext/Rdynload.h} as" msgstr "" # #. type: findex #: R-exts.texi:8947 #, no-wrap msgid "R_RegisterCCallable" msgstr "" # #. type: findex #: R-exts.texi:8948 #, no-wrap msgid "R_GetCCallable" msgstr "" # #. type: example #: R-exts.texi:8953 #, no-wrap msgid "" "void R_RegisterCCallable(const char *package, const char *name,\n" "\t\t\t DL_FUNC fptr);\n" "DL_FUNC R_GetCCallable(const char *package, const char *name);\n" msgstr "" # #. type: Plain text #: R-exts.texi:8957 msgid "" "A package @pkg{packA} that wants to make a C routine @code{myCfun} available " "to C code in other packages would include the call" msgstr "" # #. type: example #: R-exts.texi:8960 #, no-wrap msgid "R_RegisterCCallable(\"packA\", \"myCfun\", myCfun);\n" msgstr "" # #. type: Plain text #: R-exts.texi:8965 msgid "" "in its initialization function @code{R_init_packA}. A package @pkg{packB} " "that wants to use this routine would retrieve the function pointer with a " "call of the form" msgstr "" # #. type: example #: R-exts.texi:8968 #, no-wrap msgid "p_myCfun = R_GetCCallable(\"packA\", \"myCfun\");\n" msgstr "" # #. type: Plain text #: R-exts.texi:8974 msgid "" "The author of @pkg{packB} is responsible for ensuring that @code{p_myCfun} " "has an appropriate declaration. In the future @R{} may provide some " "automated tools to simplify exporting larger numbers of routines." msgstr "" # #. type: Plain text #: R-exts.texi:8980 msgid "" "A package that wishes to make use of header files in other packages needs to " "declare them as a comma-separated list in the field @samp{LinkingTo} in the " "@file{DESCRIPTION} file. This then arranges that the @file{include} " "directories in the installed linked-to packages are added to the include " "paths for C and C++ code." msgstr "" # #. type: Plain text #: R-exts.texi:8986 msgid "" "It must specify@footnote{whether or not @samp{LinkingTo} is used.} " "@samp{Imports} or @samp{Depends} of those packages, for they have to be " "loaded@footnote{so there needs to be a corresponding @code{import} or " "@code{importFrom} entry in the @file{NAMESPACE} file.} prior to this one (so " "the path to their compiled code has been registered)." msgstr "" # #. type: Plain text #: R-exts.texi:8990 msgid "" "A @acronym{CRAN} example of the use of this mechanism is package " "@CRANpkg{lme4}, which links to @CRANpkg{Matrix}." msgstr "" # #. type: findex #: R-exts.texi:8994 #, no-wrap msgid "R CMD SHLIB" msgstr "" # #. type: Plain text #: R-exts.texi:9004 msgid "" "Shared objects for loading into @R{} can be created using @command{R CMD " "SHLIB}. This accepts as arguments a list of files which must be object " "files (with extension @file{.o}) or sources for C, C++, FORTRAN 77, Fortran " "9x, Objective C or Objective C++ (with extensions @file{.c}, @file{.cc} or " "@file{.cpp}, @file{.f}, @file{.f90} or @file{.f95}, @file{.m}, and @file{." "mm} or @file{.M}, respectively), or commands to be passed to the linker. " "See @kbd{R CMD SHLIB --help} (or the @R{} help for @code{SHLIB}) for usage " "information." msgstr "" # #. type: Plain text #: R-exts.texi:9007 msgid "" "If compiling the source files does not work ``out of the box'', you can " "specify additional flags by setting some of the variables" msgstr "" # #. type: vindex #: R-exts.texi:9007 #, no-wrap msgid "PKG_CPPFLAGS" msgstr "" # #. type: Plain text #: R-exts.texi:9009 msgid "" "@code{PKG_CPPFLAGS} (for the C preprocessor, typically @samp{-I} flags)," msgstr "" # #. type: vindex #: R-exts.texi:9009 #, no-wrap msgid "PKG_CFLAGS" msgstr "" # #. type: vindex #: R-exts.texi:9010 #, no-wrap msgid "PKG_CXXFLAGS" msgstr "" # #. type: vindex #: R-exts.texi:9011 #, no-wrap msgid "PKG_FFLAGS" msgstr "" # #. type: vindex #: R-exts.texi:9012 #, no-wrap msgid "PKG_FCFLAGS" msgstr "" # #. type: vindex #: R-exts.texi:9013 #, no-wrap msgid "PKG_OBJCFLAGS" msgstr "" # #. type: vindex #: R-exts.texi:9014 #, no-wrap msgid "PKG_OBJCXXFLAGS" msgstr "" # #. type: Plain text #: R-exts.texi:9021 msgid "" "@code{PKG_CFLAGS}, @code{PKG_CXXFLAGS}, @code{PKG_FFLAGS}, " "@code{PKG_FCFLAGS}, @code{PKG_OBJCFLAGS}, and @code{PKG_OBJCXXFLAGS} (for " "the C, C++, FORTRAN 77, Fortran 9x, Objective C, and Objective C++ " "compilers, respectively) in the file @file{Makevars} in the compilation " "directory (or, of course, create the object files directly from the command " "line)." msgstr "" # #. type: vindex #: R-exts.texi:9021 #, no-wrap msgid "PKG_LIBS" msgstr "" # #. type: Plain text #: R-exts.texi:9027 msgid "" "Similarly, variable @code{PKG_LIBS} in @file{Makevars} can be used for " "additional @samp{-l} and @samp{-L} flags to be passed to the linker when " "building the shared object. (Supplying linker commands as arguments to " "@code{R CMD SHLIB} will take precedence over @code{PKG_LIBS} in " "@file{Makevars}.)" msgstr "" # #. type: Plain text #: R-exts.texi:9032 msgid "" "It is possible to arrange to include compiled code from other languages by " "setting the macro @samp{OBJECTS} in file @file{Makevars}, together with " "suitable rules to make the objects." msgstr "" # #. type: Plain text #: R-exts.texi:9037 msgid "" "Flags which are already set (for example in file @file{etc@var{R_ARCH}/" "Makeconf}) can be overridden by the environment variable @env{MAKEFLAGS} (at " "least for systems using a POSIX-compliant @code{make}), as in (Bourne shell " "syntax)" msgstr "" # #. type: example #: R-exts.texi:9040 #, no-wrap msgid "MAKEFLAGS=\"CFLAGS=-O3\" R CMD SHLIB *.c\n" msgstr "" # #. type: Plain text #: R-exts.texi:9045 msgid "" "It is also possible to set such variables in personal @file{Makevars} files, " "which are read after the local @file{Makevars} and the system makefiles or " "in a site-wide @file{Makevars.site} file." msgstr "" # #. type: Plain text #: R-exts.texi:9054 msgid "" "Note that as @command{R CMD SHLIB} uses Make, it will not remake a shared " "object just because the flags have changed, and if @file{test.c} and " "@file{test.f} both exist in the current directory" msgstr "" # #. type: example #: R-exts.texi:9057 #, no-wrap msgid "R CMD SHLIB test.f\n" msgstr "" # #. type: Plain text #: R-exts.texi:9061 msgid "will compile @file{test.c}!" msgstr "" # #. type: Plain text #: R-exts.texi:9071 msgid "" "If the @file{src} subdirectory of an add-on package contains source code " "with one of the extensions listed above or a file @file{Makevars} but " "@strong{not} a file @file{Makefile}, @command{R CMD INSTALL} creates a " "shared object (for loading into @R{} through @code{useDynlib} in the " "@file{NAMESPACE}, or in the @code{.onLoad} function of the package) using " "the @command{R CMD SHLIB} mechanism. If file @file{Makevars} exists it is " "read first, then the system makefile and then any personal @file{Makevars} " "files." msgstr "" # #. type: Plain text #: R-exts.texi:9078 msgid "" "If the @file{src} subdirectory of package contains a file @file{Makefile}, " "this is used by @command{R CMD INSTALL} in place of the @code{R CMD SHLIB} " "mechanism. @command{make} is called with makefiles @file{@var{R_HOME}/" "etc@var{R_ARCH}/Makeconf}, @file{src/Makefile} and any personal " "@file{Makevars} files (in that order). The first target found in @file{src/" "Makefile} is used." msgstr "" # #. type: Plain text #: R-exts.texi:9081 msgid "" "It is better to make use of a @file{Makevars} file rather than a " "@file{Makefile}: the latter should be needed only exceptionally." msgstr "" # #. type: Plain text #: R-exts.texi:9098 msgid "" "Under Windows the same commands work, but @file{Makevars.win} will be used " "in preference to @file{Makevars}, and only @file{src/Makefile.win} will be " "used by @code{R CMD INSTALL} with @file{src/Makefile} being ignored. For " "past experiences of building DLLs with a variety of compilers, see file " "@samp{README.packages} and @uref{http://www.stats.uwo.ca/@/faculty/@/murdoch/" "@/software/@/compilingDLLs/} . Under Windows you can supply an exports " "definitions file called @file{@var{dllname}-win.def}: otherwise all entry " "points in objects (but not libraries) supplied to @code{R CMD SHLIB} will be " "exported from the DLL. An example is @file{stats-win.def} for the " "@pkg{stats} package: a @acronym{CRAN} example in package @CRANpkg{fastICA}." msgstr "" # #. type: Plain text #: R-exts.texi:9107 msgid "" "If you feel tempted to read the source code and subvert these mechanisms, " "please resist. Far too much developer time has been wasted in chasing down " "errors caused by failures to follow this documentation, and even more by " "package authors demanding explanations as to why their packages no longer " "work. In particular, undocumented environment or @command{make} variables " "are not for use by package writers and are subject to change without notice." msgstr "" # #. type: cindex #: R-exts.texi:9111 #, no-wrap msgid "C++ code, interfacing" msgstr "" # #. type: Plain text #: R-exts.texi:9116 msgid "" "Suppose we have the following hypothetical C++ library, consisting of the " "two files @file{X.h} and @file{X.cpp}, and implementing the two classes " "@code{X} and @code{Y} which we want to use in @R{}." msgstr "" # #. type: example #: R-exts.texi:9121 #, no-wrap msgid "" "// X.h\n" "\n" msgstr "" # #. type: example #: R-exts.texi:9125 #, no-wrap msgid "" "class X @{\n" "public: X (); ~X ();\n" "@};\n" "\n" msgstr "" # #. type: example #: R-exts.texi:9129 #, no-wrap msgid "" "class Y @{\n" "public: Y (); ~Y ();\n" "@};\n" msgstr "" # #. type: example #: R-exts.texi:9137 #, no-wrap msgid "" "// X.cpp\n" "\n" msgstr "" # #. type: example #: R-exts.texi:9140 #, no-wrap msgid "" "#include <R.h>\n" "#include \"X.h\"\n" "\n" msgstr "" # #. type: example #: R-exts.texi:9142 #, no-wrap msgid "" "static Y y;\n" "\n" msgstr "" # #. type: example #: R-exts.texi:9147 #, no-wrap msgid "" "X::X() @{ REprintf(\"constructor X\\n\"); @}\n" "X::~X() @{ REprintf(\"destructor X\\n\"); @}\n" "Y::Y() @{ REprintf(\"constructor Y\\n\"); @}\n" "Y::~Y() @{ REprintf(\"destructor Y\\n\"); @}\n" msgstr "" # #. type: Plain text #: R-exts.texi:9153 msgid "" "To use with @R{}, the only thing we have to do is writing a wrapper function " "and ensuring that the function is enclosed in" msgstr "" # #. type: example #: R-exts.texi:9157 #: R-exts.texi:9172 #, no-wrap msgid "" "extern \"C\" @{\n" "\n" msgstr "" # #. type: group #: R-exts.texi:9159 #, no-wrap msgid "@}\n" msgstr "" # #. type: example #: R-exts.texi:9168 #, no-wrap msgid "" "// X_main.cpp:\n" "\n" msgstr "" # #. type: example #: R-exts.texi:9170 #, no-wrap msgid "" "#include \"X.h\"\n" "\n" msgstr "" # #. type: example #: R-exts.texi:9176 #, no-wrap msgid "" "void X_main () @{\n" " X x;\n" "@}\n" "\n" msgstr "" # #. type: example #: R-exts.texi:9178 #, no-wrap msgid "@} // extern \"C\"\n" msgstr "" # #. type: Plain text #: R-exts.texi:9187 msgid "" "Compiling and linking should be done with the C++ compiler-linker (rather " "than the C compiler-linker or the linker itself); otherwise, the C++ " "initialization code (and hence the constructor of the static variable " "@code{Y}) are not called. On a properly configured system, one can simply " "use" msgstr "" # #. type: example #: R-exts.texi:9190 #, no-wrap msgid "R CMD SHLIB X.cpp X_main.cpp\n" msgstr "" # #. type: Plain text #: R-exts.texi:9195 msgid "" "to create the shared object, typically @file{X.so} (the file name extension " "may be different on your platform). Now starting @R{} yields" msgstr "" # #. type: group #: R-exts.texi:9202 #, no-wrap msgid "" "R version 2.14.1 Patched (2012-01-16 r58124)\n" "Copyright (C) 2012 The R Foundation for Statistical Computing\n" "...\n" "Type \"q()\" to quit R.\n" msgstr "" # #. type: group #: R-exts.texi:9214 #, no-wrap msgid "" "R> dyn.load(paste(\"X\", .Platform$dynlib.ext, sep = \"\"))\n" "constructor Y\n" "R> .C(\"X_main\")\n" "constructor X\n" "destructor X\n" "list()\n" "R> q()\n" "Save workspace image? [y/n/c]: y\n" "destructor Y\n" msgstr "" # #. type: Plain text #: R-exts.texi:9219 msgid "" "The @R{} for Windows @acronym{FAQ} (@file{rw-FAQ}) contains details of how " "to compile this example under Windows." msgstr "" # #. type: Plain text #: R-exts.texi:9227 msgid "" "Earlier version of this example used C++ iostreams: this is best avoided. " "There is no guarantee that the output will appear in the @R{} console, and " "indeed it will not on the @R{} for Windows console. Use @R{} code or the C " "entry points (@pxref{Printing}) for all I/O if at all possible. Examples " "have been seen where merely loading a DLL that contained calls to C++ I/O " "upset @R{}'s own C I/O (for example by resetting buffers on open files)." msgstr "" # #. type: Plain text #: R-exts.texi:9235 msgid "" "Most @R{} header files can be included within C++ programs, and they should " "@strong{not} be included within an @code{extern \"C\"} block (as they " "include C++ system headers). It may not be possible to include some @R{} " "headers as they in turn include C header files that may cause conflicts---if " "this happens, define @samp{NO_C_HEADERS} before including the @R{} headers, " "and include C++ versions (such as @samp{cmath}) of the appropriate headers " "yourself before the @R{} headers." msgstr "" # #. type: Plain text #: R-exts.texi:9243 msgid "" "We have already warned against the use of C++ iostreams not least because " "output is not guaranteed to appear on the @R{} console, and this warning " "applies equally to Fortran (77 or 9x) output to units @code{*} and @code{6}. " "@xref{Printing from FORTRAN}, which describes workarounds." msgstr "" # #. type: Plain text #: R-exts.texi:9253 msgid "" "In the past most Fortran compilers implemented I/O on top of the C I/O " "system and so the two interworked successfully. This was true of " "@command{g77}, but it is less true of @command{gfortran} as used in " "@code{gcc 4.y.z}. In particular, any package that makes use of Fortran I/O " "will when compiled on Windows interfere with C I/O: when the Fortran I/O is " "initialized (typically when the package is loaded) the C @code{stdout} and " "@code{stderr} are switched to LF line endings. (Function @code{init} in " "file @file{src/modules/lapack/init_win.c} shows how to mitigate this.)" msgstr "" # #. type: Plain text #: R-exts.texi:9262 msgid "" "It is not in general possible to link a DLL in package @pkg{packA} to a DLL " "provided by package @pkg{packB} (for the security reasons mentioned in " "@ref{dyn.load and dyn.unload}, and also because some platforms distinguish " "between shared objects and dynamic libraries), but it is on Windows." msgstr "" # #. type: Plain text #: R-exts.texi:9267 msgid "" "Note that there can be tricky versioning issues here, as package @pkg{packB} " "could be re-installed after package @pkg{packA} --- it is desirable that the " "API provided by package @pkg{packB} remains backwards-compatible." msgstr "" # #. type: Plain text #: R-exts.texi:9270 msgid "" "Shipping a static library in package @pkg{packB} for other packages to link " "to avoids most of the difficulties." msgstr "" # #. type: node #: R-exts.texi:9274 #: R-exts.texi:9276 #: R-exts.texi:9277 #: R-exts.texi:9350 #, no-wrap msgid "Unix-alikes" msgstr "" # #. type: subsection #: R-exts.texi:9274 #: R-exts.texi:9276 #: R-exts.texi:9350 #: R-exts.texi:9351 #, no-wrap msgid "Windows" msgstr "" # #. type: Plain text #: R-exts.texi:9283 msgid "" "It is possible to link a shared object in package @pkg{packA} to a library " "provided by package @pkg{packB} under limited circumstances on a Unix-alike " "OS. There are severe portability issues, so this is not recommended for a " "distributed package." msgstr "" # #. type: Plain text #: R-exts.texi:9295 msgid "" "This is easiest if @pkg{packB} provides a static library @file{packB/lib/" "libpackB.a}. (Note using directory @file{lib} rather than @file{libs} is " "conventional, and architecture-specific sub-directories may be needed and " "are assumed in the sample code below. The code in the static library will " "need to be compiled with @code{PIC} flags on platforms where it matters.) " "Then as the code from package @pkg{packB} is incorporated when package " "@pkg{packA} is installed, we only need to find the static library at install " "time for package @pkg{packA}. The only issue is to find package " "@pkg{packB}, and for that we can ask @R{} by something like (long lines " "broken for display here)" msgstr "" # #. type: example #: R-exts.texi:9301 #, no-wrap msgid "" "PKGB_PATH=`echo 'library(packB);\n" " cat(system.file(\"lib\", package=\"packB\", mustWork=TRUE))' \\\n" " | \"$@{R_HOME@}/bin/R\" --vanilla --slave`\n" "PKG_LIBS=\"$(PKGB_PATH)$(R_ARCH)/libpackB.a\"\n" msgstr "" # #. type: Plain text #: R-exts.texi:9306 msgid "" "For a dynamic library @file{packB/lib/libpackB.so} (@file{packB/lib/libpackB." "dylib} on OS X: note that you cannot link to a shared object, @file{.so}, on " "that platform) we could use" msgstr "" # #. type: example #: R-exts.texi:9312 #, no-wrap msgid "" "PKGB_PATH=`echo 'library(packB);\n" " cat(system.file(\"lib\", package=\"packB\", mustWork=TRUE))' \\\n" " | \"$@{R_HOME@}/bin/R\" --vanilla --slave`\n" "PKG_LIBS=-L\"$(PKGB_PATH)$(R_ARCH)\" -lpackB\n" msgstr "" #. type: Plain text #: R-exts.texi:9328 msgid "" "This will work for installation, but very likely not when package " "@code{packB} is loaded, as the path to package @pkg{packB}'s @file{lib} " "directory is not in the @command{ld.so}@footnote{@command{dyld} on OS X, and " "@env{DYLD_LIBRARY_PATHS} below.} search path. You can arrange to put it " "there @strong{before} @R{} is launched by setting (on some platforms) " "@env{LD_RUN_PATH} or @env{LD_LIBRARY_PATH} or adding to the @command{ld.so} " "cache (see @command{man ldconfig}). On platforms that support it, the path " "to the directory containing the dynamic library can be hardcoded at install " "time (which assumes that the location of package @pkg{packB} will not be " "changed nor the package updated to a changed API). On systems with the " "@command{gcc} or @command{clang} and the @acronym{GNU} linker (e.g.@: Linux) " "and some others this can be done by e.g.@:" msgstr "" # #. type: example #: R-exts.texi:9334 #, no-wrap msgid "" "PKGB_PATH=`echo 'library(packB);\n" " cat(system.file(\"lib\", package=\"packB\", mustWork=TRUE)))' \\\n" " | \"$@{R_HOME@}/bin/R\" --vanilla --slave`\n" "PKG_LIBS=-L\"$(PKGB_PATH)$(R_ARCH)\" -Wl,-rpath,\"$(PKGB_PATH)$(R_ARCH)\" -lpackB\n" msgstr "" # #. type: Plain text #: R-exts.texi:9340 msgid "" "Some other systems (e.g.@: Solaris with its native linker) use @option{-" "Rdir} rather than @option{-rpath,dir} (and this is accepted by the compiler " "as well as the linker)." msgstr "" #. type: Plain text #: R-exts.texi:9344 msgid "" "It may be possible to figure out what is required semi-automatically from " "the result of @command{R CMD libtool --config} (look for @samp{hardcode})." msgstr "" # #. type: Plain text #: R-exts.texi:9348 msgid "" "Making headers provided by package @pkg{packB} available to the code to be " "compiled in package @pkg{packA} can be done by the @code{LinkingTo} " "mechanism (@pxref{Registering native routines})." msgstr "" # #. type: Plain text #: R-exts.texi:9358 msgid "" "Suppose package @pkg{packA} wants to make use of compiled code provided by " "@pkg{packB} in DLL @file{packB/libs/exB.dll}, possibly the package's DLL " "@file{packB/libs/packB.dll}. (This can be extended to linking to more than " "one package in a similar way.) There are three issues to be addressed:" msgstr "" # #. type: itemize #: R-exts.texi:9364 msgid "" "Making headers provided by package @pkg{packB} available to the code to be " "compiled in package @pkg{packA}." msgstr "" # #. type: itemize #: R-exts.texi:9367 msgid "" "This is done by the @code{LinkingTo} mechanism (@pxref{Registering native " "routines})." msgstr "" # #. type: item #: R-exts.texi:9368 #, no-wrap msgid "preparing @code{packA.dll} to link to @file{packB/libs/exB.dll}." msgstr "" # #. type: itemize #: R-exts.texi:9371 msgid "This needs an entry in @file{Makevars.win} of the form" msgstr "" # #. type: example #: R-exts.texi:9374 #, no-wrap msgid "PKG_LIBS= -L<something> -lexB\n" msgstr "" # #. type: itemize #: R-exts.texi:9379 msgid "" "and one possibility is that @code{<something>} is the path to the installed " "@file{pkgB/libs} directory. To find that we need to ask @R{} where it is by " "something like" msgstr "" # #. type: example #: R-exts.texi:9385 #, no-wrap msgid "" "PKGB_PATH=`echo 'library(packB);\n" " cat(system.file(\"libs\", package=\"packB\", mustWork=TRUE))' \\\n" " | rterm --vanilla --slave`\n" "PKG_LIBS= -L\"$(PKGB_PATH)$(R_ARCH)\" -lexB\n" msgstr "" # #. type: itemize #: R-exts.texi:9390 msgid "" "Another possibility is to use an import library, shipping with package " "@pkg{packA} an exports file @file{exB.def}. Then @file{Makevars.win} could " "contain" msgstr "" # #. type: example #: R-exts.texi:9393 #, no-wrap msgid "" "PKG_LIBS= -L. -lexB\n" "\n" msgstr "" # #. type: example #: R-exts.texi:9395 #, no-wrap msgid "" "all: $(SHLIB) before\n" "\n" msgstr "" # #. type: example #: R-exts.texi:9398 #, no-wrap msgid "" "before: libexB.dll.a\n" "libexB.dll.a: exB.def\n" msgstr "" # #. type: itemize #: R-exts.texi:9403 msgid "" "and then installing package @pkg{packA} will make and use the import library " "for @file{exB.dll}. (One way to prepare the exports file is to use " "@file{pexports.exe}.)" msgstr "" # #. type: item #: R-exts.texi:9404 #, no-wrap msgid "loading @file{packA.dll} which depends on @file{exB.dll}." msgstr "" # #. type: itemize #: R-exts.texi:9411 msgid "" "If @code{exB.dll} was used by package @pkg{packB} (because it is in fact " "@file{packB.dll} or @file{packB.dll} depends on it) and @pkg{packB} has been " "loaded before @pkg{packA}, then nothing more needs to be done as @file{exB." "dll} will already be loaded into the @R{} executable. (This is the most " "common scenario.)" msgstr "" # #. type: itemize #: R-exts.texi:9415 msgid "" "More generally, we can use the @code{DLLpath} argument to @code{library." "dynam} to ensure that @code{exB.dll} is found, for example by setting" msgstr "" # #. type: example #: R-exts.texi:9419 #, no-wrap msgid "" "library.dynam(\"packA\", pkg, lib,\n" "\t DLLpath = system.file(\"libs\", package=\"packB\"))\n" msgstr "" # #. type: itemize #: R-exts.texi:9424 msgid "" "Note that @code{DLLpath} can only set one path, and so for linking to two or " "more packages you would need to resort to setting environment variable " "@env{PATH}." msgstr "" # #. type: Plain text #: R-exts.texi:9440 msgid "" "Using C code to speed up the execution of an @R{} function is often very " "fruitful. Traditionally this has been done @emph{via} the @code{.C} " "function in @R{}. However, if a user wants to write C code using internal " "@R{} data structures, then that can be done using the @code{.Call} and " "@code{.External} functions. The syntax for the calling function in @R{} in " "each case is similar to that of @code{.C}, but the two functions have " "different C interfaces. Generally the @code{.Call} interface is simpler to " "use, but @code{.External} is a little more general." msgstr "" # #. type: findex #: R-exts.texi:9440 #: R-exts.texi:10277 #, no-wrap msgid ".Call" msgstr "" # #. type: findex #: R-exts.texi:9441 #: R-exts.texi:10318 #, no-wrap msgid ".External" msgstr "" # #. type: Plain text #: R-exts.texi:9444 msgid "A call to @code{.Call} is very similar to @code{.C}, for example" msgstr "" # #. type: example #: R-exts.texi:9447 #, no-wrap msgid ".Call(\"convolve2\", a, b)\n" msgstr "" # #. type: Plain text #: R-exts.texi:9453 msgid "" "The first argument should be a character string giving a C symbol name of " "code that has already been loaded into @R{}. Up to 65 @R{} objects can " "passed as arguments. The C side of the interface is" msgstr "" # #. type: group #: R-exts.texi:9458 #: R-exts.texi:9477 #: R-exts.texi:9599 #: R-exts.texi:9800 #: R-exts.texi:9826 #: R-exts.texi:10294 #: R-exts.texi:10336 #, no-wrap msgid "" "#include <R.h>\n" "#include <Rinternals.h>\n" "\n" msgstr "" # #. type: group #: R-exts.texi:9461 #, no-wrap msgid "" "SEXP convolve2(SEXP a, SEXP b)\n" " ...\n" msgstr "" # #. type: Plain text #: R-exts.texi:9465 msgid "A call to @code{.External} is almost identical" msgstr "" # #. type: example #: R-exts.texi:9468 #, no-wrap msgid ".External(\"convolveE\", a, b)\n" msgstr "" # #. type: Plain text #: R-exts.texi:9472 msgid "but the C side of the interface is different, having only one argument" msgstr "" # #. type: group #: R-exts.texi:9480 #, no-wrap msgid "" "SEXP convolveE(SEXP args)\n" " ...\n" msgstr "" # #. type: Plain text #: R-exts.texi:9486 msgid "" "Here @code{args} is a @code{LISTSXP}, a Lisp-style pairlist from which the " "arguments can be extracted." msgstr "" # #. type: Plain text #: R-exts.texi:9494 msgid "" "In each case the @R{} objects are available for manipulation @emph{via} a " "set of functions and macros defined in the header file @file{Rinternals.h} " "or some @Sl{}-compatibility macros@footnote{That is, similar to those " "defined in @Sl{} version 4 from the 1990s: these are not kept up to date and " "are not recommended for new projects.} defined in @file{Rdefines.h}. See " "@ref{Interface functions .Call and .External} for details on @code{.Call} " "and @code{.External}." msgstr "" # #. type: Plain text #: R-exts.texi:9507 msgid "" "Before you decide to use @code{.Call} or @code{.External}, you should look " "at other alternatives. First, consider working in interpreted @R{} code; if " "this is fast enough, this is normally the best option. You should also see " "if using @code{.C} is enough. If the task to be performed in C is simple " "enough involving only atomic vectors and requiring no call to @R{}, @code{." "C} suffices. A great deal of useful code was written using just @code{.C} " "before @code{.Call} and @code{.External} were available. These interfaces " "allow much more control, but they also impose much greater responsibilities " "so need to be used with care. Neither @code{.Call} nor @code{.External} " "copy their arguments: you should treat arguments you receive through these " "interfaces as read-only." msgstr "" # #. type: Plain text #: R-exts.texi:9515 msgid "" "To handle @R{} objects from within C code we use the macros and functions " "that have been used to implement the core parts of @R{}. A " "public@footnote{ @pxref{The R API}: note that these are not all part of the " "API.} subset of these is defined in the header file @file{Rinternals.h} in " "the directory @file{@var{R_INCLUDE_DIR}} (default @file{@var{R_HOME}/" "include}) that should be available on any @R{} installation." msgstr "" # #. type: Plain text #: R-exts.texi:9520 msgid "" "A substantial amount of @R{}, including the standard packages, is " "implemented using the functions and macros described here, so the @R{} " "source code provides a rich source of examples and ``how to do it'': do make " "use of the source code for inspirational examples." msgstr "" # #. type: Plain text #: R-exts.texi:9538 msgid "" "It is necessary to know something about how @R{} objects are handled in C " "code. All the @R{} objects you will deal with will be handled with the type " "@dfn{SEXP}@footnote{SEXP is an acronym for @emph{S}imple @emph{EXP}ression, " "common in LISP-like language syntaxes.}, which is a pointer to a structure " "with typedef @code{SEXPREC}. Think of this structure as a @emph{variant " "type} that can handle all the usual types of @R{} objects, that is vectors " "of various modes, functions, environments, language objects and so on. The " "details are given later in this section and in @ref{R Internal Structures, , " "R Internal Structures, R-ints, R Internals}, but for most purposes the " "programmer does not need to know them. Think rather of a model such as that " "used by Visual Basic, in which @R{} objects are handed around in C code (as " "they are in interpreted @R{} code) as the variant type, and the appropriate " "part is extracted for, for example, numerical calculations, only when it is " "needed. As in interpreted @R{} code, much use is made of coercion to force " "the variant object to the right type." msgstr "" # #. type: node #: R-exts.texi:9550 #: R-exts.texi:9552 #: R-exts.texi:9670 #, no-wrap msgid "Garbage Collection" msgstr "" # #. type: node #: R-exts.texi:9550 #: R-exts.texi:9552 #: R-exts.texi:9670 #: R-exts.texi:9671 #: R-exts.texi:9672 #: R-exts.texi:9692 #, no-wrap msgid "Allocating storage" msgstr "" # #. type: node #: R-exts.texi:9550 #: R-exts.texi:9670 #: R-exts.texi:9692 #: R-exts.texi:9693 #: R-exts.texi:9694 #: R-exts.texi:9768 #, no-wrap msgid "Details of R types" msgstr "" # #. type: node #: R-exts.texi:9550 #: R-exts.texi:9692 #: R-exts.texi:9768 #: R-exts.texi:9769 #: R-exts.texi:9770 #: R-exts.texi:9909 #, no-wrap msgid "Attributes" msgstr "" # #. type: node #: R-exts.texi:9550 #: R-exts.texi:9768 #: R-exts.texi:9909 #: R-exts.texi:9910 #: R-exts.texi:9911 #: R-exts.texi:9939 #, no-wrap msgid "Classes" msgstr "" # #. type: node #: R-exts.texi:9550 #: R-exts.texi:9909 #: R-exts.texi:9939 #: R-exts.texi:9940 #: R-exts.texi:9941 #: R-exts.texi:10000 #, no-wrap msgid "Handling lists" msgstr "" # #. type: node #: R-exts.texi:9550 #: R-exts.texi:9939 #: R-exts.texi:10000 #: R-exts.texi:10001 #: R-exts.texi:10032 #, no-wrap msgid "Handling character data" msgstr "" # #. type: node #: R-exts.texi:9550 #: R-exts.texi:10000 #: R-exts.texi:10032 #: R-exts.texi:10033 #: R-exts.texi:10092 #, no-wrap msgid "Finding and setting variables" msgstr "" # #. type: node #: R-exts.texi:9550 #: R-exts.texi:10032 #: R-exts.texi:10092 #: R-exts.texi:10093 #: R-exts.texi:10158 #: R-exts.texi:10171 #, no-wrap msgid "Some convenience functions" msgstr "" # #. type: subsection #: R-exts.texi:9550 #: R-exts.texi:10092 #: R-exts.texi:10171 #: R-exts.texi:10172 #, no-wrap msgid "Named objects and copying" msgstr "" # #. type: subsection #: R-exts.texi:9553 #, no-wrap msgid "Handling the effects of garbage collection" msgstr "" # #. type: cindex #: R-exts.texi:9554 #, no-wrap msgid "Garbage collection" msgstr "" # #. type: findex #: R-exts.texi:9556 #, no-wrap msgid "PROTECT" msgstr "" # #. type: findex #: R-exts.texi:9557 #, no-wrap msgid "UNPROTECT" msgstr "" # #. type: Plain text #: R-exts.texi:9564 msgid "" "We need to know a little about the way @R{} handles memory allocation. The " "memory allocated for @R{} objects is not freed by the user; instead, the " "memory is from time to time @dfn{garbage collected}. That is, some or all " "of the allocated memory not being used is freed or marked as re-usable." msgstr "" # #. type: Plain text #: R-exts.texi:9569 msgid "" "The @R{} object types are represented by a C structure defined by a typedef " "@code{SEXPREC} in @file{Rinternals.h}. It contains several things among " "which are pointers to data blocks and to other @code{SEXPREC}s. A " "@code{SEXP} is simply a pointer to a @code{SEXPREC}." msgstr "" # #. type: Plain text #: R-exts.texi:9578 msgid "" "If you create an @R{} object in your C code, you must tell @R{} that you are " "using the object by using the @code{PROTECT} macro on a pointer to the " "object. This tells @R{} that the object is in use so it is not destroyed " "during garbage collection. Notice that it is the object which is protected, " "not the pointer variable. It is a common mistake to believe that if you " "invoked @code{PROTECT(@var{p})} at some point then @var{p} is protected from " "then on, but that is not true once a new object is assigned to @var{p}." msgstr "" # #. type: Plain text #: R-exts.texi:9582 msgid "" "Protecting an @R{} object automatically protects all the @R{} objects " "pointed to in the corresponding @code{SEXPREC}, for example all elements of " "a protected list are automatically protected." msgstr "" # #. type: Plain text #: R-exts.texi:9592 msgid "" "The programmer is solely responsible for housekeeping the calls to " "@code{PROTECT}. There is a corresponding macro @code{UNPROTECT} that takes " "as argument an @code{int} giving the number of objects to unprotect when " "they are no longer needed. The protection mechanism is stack-based, so " "@code{UNPROTECT(@var{n})} unprotects the last @var{n} objects which were " "protected. The calls to @code{PROTECT} and @code{UNPROTECT} must balance " "when the user's code returns. @R{} will warn about @code{\"stack imbalance " "in .Call\"} (or @code{.External}) if the housekeeping is wrong." msgstr "" # #. type: Plain text #: R-exts.texi:9594 msgid "Here is a small example of creating an @R{} numeric vector in C code:" msgstr "" # #. type: group #: R-exts.texi:9606 #, no-wrap msgid "" " SEXP ab;\n" " ....\n" " ab = PROTECT(allocVector(REALSXP, 2));\n" " REAL(ab)[0] = 123.45;\n" " REAL(ab)[1] = 67.89;\n" " UNPROTECT(1);\n" msgstr "" # #. type: Plain text #: R-exts.texi:9617 msgid "" "Now, the reader may ask how the @R{} object could possibly get removed " "during those manipulations, as it is just our C code that is running. As it " "happens, we can do without the protection in this example, but in general we " "do not know (nor want to know) what is hiding behind the @R{} macros and " "functions we use, and any of them might cause memory to be allocated, hence " "garbage collection and hence our object @code{ab} to be removed. It is " "usually wise to err on the side of caution and assume that any of the @R{} " "macros and functions might remove the object." msgstr "" # #. type: Plain text #: R-exts.texi:9626 msgid "" "In some cases it is necessary to keep better track of whether protection is " "really needed. Be particularly aware of situations where a large number of " "objects are generated. The pointer protection stack has a fixed size " "(default 10,000) and can become full. It is not a good idea then to just " "@code{PROTECT} everything in sight and @code{UNPROTECT} several thousand " "objects at the end. It will almost invariably be possible to either assign " "the objects as part of another object (which automatically protects them) or " "unprotect them immediately after use." msgstr "" # #. type: Plain text #: R-exts.texi:9629 msgid "" "Protection is not needed for objects which @R{} already knows are in use. " "In particular, this applies to function arguments." msgstr "" # #. type: Plain text #: R-exts.texi:9635 msgid "" "There is a less-used macro @code{UNPROTECT_PTR(@var{s})} that unprotects the " "object pointed to by the @code{SEXP} @var{s}, even if it is not the top item " "on the pointer protection stack. This is rarely needed outside the parser " "(the @R{} sources currently have three examples, one in @file{src/main/" "plot3d.c})." msgstr "" # #. type: findex #: R-exts.texi:9635 #, no-wrap msgid "UNPROTECT_PTR" msgstr "" # #. type: Plain text #: R-exts.texi:9641 msgid "" "Sometimes an object is changed (for example duplicated, coerced or grown) " "yet the current value needs to be protected. For these cases " "@code{PROTECT_WITH_INDEX} saves an index of the protection location that can " "be used to replace the protected value using @code{REPROTECT}." msgstr "" # #. type: findex #: R-exts.texi:9641 #, no-wrap msgid "PROTECT_WITH_INDEX" msgstr "" # #. type: findex #: R-exts.texi:9642 #, no-wrap msgid "REPROTECT" msgstr "" # #. type: Plain text #: R-exts.texi:9644 msgid "For example (from the internal code for @code{optim})" msgstr "" # #. type: example #: R-exts.texi:9647 #, no-wrap msgid "" " PROTECT_INDEX ipx;\n" "\n" msgstr "" # #. type: example #: R-exts.texi:9651 #, no-wrap msgid "" " ....\n" " s = PROTECT_WITH_INDEX(eval(OS->R_fcall, OS->R_env), &ipx);\n" " s = REPROTECT(coerceVector(s, REALSXP), ipx);\n" msgstr "" # #. type: Plain text #: R-exts.texi:9657 msgid "" "Note that it is dangerous to mix @code{UNPROTECT_PTR} with " "@code{PROTECT_WITH_INDEX}, as the former changes the protection locations of " "objects that were protected after the one being unprotected." msgstr "" # #. type: findex #: R-exts.texi:9658 #, no-wrap msgid "R_PreserveObject" msgstr "" # #. type: findex #: R-exts.texi:9659 #, no-wrap msgid "R_ReleaseObject" msgstr "" # #. type: Plain text #: R-exts.texi:9669 msgid "" "There is another way to avoid the affects of garbage collection: a call to " "@code{R_PreserveObject} adds an object to an internal list of objects not to " "be collects, and a subsequent call to @code{R_ReleaseObject} removes it from " "that list. This provides a way for objects which are not returned as part " "of @R{} objects to be protected across calls to compiled code: on the other " "hand it becomes the user's responsibility to release them when they are no " "longer needed (and this often requires the use of a finalizer). It is less " "efficient that the normal protection mechanism, and should be used sparingly." msgstr "" # #. type: Plain text #: R-exts.texi:9677 msgid "" "For many purposes it is sufficient to allocate @R{} objects and manipulate " "those. There are quite a few @code{alloc@var{Xxx}} functions defined in " "@file{Rinternals.h}---you may want to explore them." msgstr "" # #. type: findex #: R-exts.texi:9678 #, no-wrap msgid "allocVector" msgstr "" # #. type: Plain text #: R-exts.texi:9685 msgid "" "One that is commonly used is @code{allocVector}, the C-level equivalent of " "@R{}-level @code{vector()} and its wrappers such as @code{integer()} and " "@code{character()}. One distinction is that whereas the @R{} functions " "always initialize the elements of the vector, @code{allocVector} only does " "so for lists, expressions and character vectors (the cases where the " "elements are themselves @R{} objects)." msgstr "" # #. type: Plain text #: R-exts.texi:9691 msgid "" "If storage is required for C objects during the calculations this is best " "allocating by calling @code{R_alloc}; @pxref{Memory allocation}. All of " "these memory allocation routines do their own error-checking, so the " "programmer may assume that they will raise an error and not return if the " "memory cannot be allocated." msgstr "" # #. type: Plain text #: R-exts.texi:9701 msgid "" "Users of the @file{Rinternals.h} macros will need to know how the @R{} types " "are known internally. The different @R{} data types are represented in C by " "@dfn{SEXPTYPE}. Some of these are familiar from @R{} and some are internal " "data types. The usual @R{} object modes are given in the table." msgstr "" # #. type: multitable #: R-exts.texi:9705 msgid "@headitem SEXPTYPE" msgstr "" # #. type: multitable #: R-exts.texi:9705 msgid "@R{} equivalent" msgstr "" # #. type: item #: R-exts.texi:9705 #, no-wrap msgid "@code{REALSXP} @tab numeric with storage mode @code{double}" msgstr "" # #. type: item #: R-exts.texi:9706 #, no-wrap msgid "@code{INTSXP} @tab integer" msgstr "" # #. type: item #: R-exts.texi:9707 #, no-wrap msgid "@code{CPLXSXP} @tab complex" msgstr "" # #. type: item #: R-exts.texi:9708 #, no-wrap msgid "@code{LGLSXP} @tab logical" msgstr "" # #. type: item #: R-exts.texi:9709 #, no-wrap msgid "@code{STRSXP} @tab character" msgstr "" # #. type: item #: R-exts.texi:9710 #, no-wrap msgid "@code{VECSXP} @tab list (generic vector)" msgstr "" # #. type: item #: R-exts.texi:9711 #, no-wrap msgid "@code{LISTSXP} @tab pairlist" msgstr "" # #. type: item #: R-exts.texi:9712 #, no-wrap msgid "@code{DOTSXP} @tab a @samp{@dots{}} object" msgstr "" # #. type: item #: R-exts.texi:9713 #, no-wrap msgid "@code{NILSXP} @tab NULL" msgstr "" # #. type: item #: R-exts.texi:9714 #, no-wrap msgid "@code{SYMSXP} @tab name/symbol" msgstr "" # #. type: item #: R-exts.texi:9715 #, no-wrap msgid "@code{CLOSXP} @tab function or function closure" msgstr "" # #. type: item #: R-exts.texi:9716 #, no-wrap msgid "@code{ENVSXP} @tab environment" msgstr "" # #. type: Plain text #: R-exts.texi:9727 msgid "" "Among the important internal @code{SEXPTYPE}s are @code{LANGSXP}, " "@code{CHARSXP}, @code{PROMSXP}, etc. (@strong{N.B.}: although it is " "possible to return objects of internal types, it is unsafe to do so as " "assumptions are made about how they are handled which may be violated at " "user-level evaluation.) More details are given in @ref{R Internal " "Structures, , R Internal Structures, R-ints, R Internals}." msgstr "" # #. type: Plain text #: R-exts.texi:9736 msgid "" "Unless you are very sure about the type of the arguments, the code should " "check the data types. Sometimes it may also be necessary to check data " "types of objects created by evaluating an @R{} expression in the C code. " "You can use functions like @code{isReal}, @code{isInteger} and " "@code{isString} to do type checking. See the header file @file{Rinternals." "h} for definitions of other such functions. All of these take a @code{SEXP} " "as argument and return 1 or 0 to indicate @var{TRUE} or @var{FALSE}." msgstr "" # #. type: Plain text #: R-exts.texi:9743 msgid "" "What happens if the @code{SEXP} is not of the correct type? Sometimes you " "have no other option except to generate an error. You can use the function " "@code{error} for this. It is usually better to coerce the object to the " "correct type. For example, if you find that an @code{SEXP} is of the type " "@code{INTEGER}, but you need a @code{REAL} object, you can change the type " "by using" msgstr "" # #. type: example #: R-exts.texi:9746 #, no-wrap msgid "@var{newSexp} = PROTECT(coerceVector(@var{oldSexp}, REALSXP));\n" msgstr "" # #. type: Plain text #: R-exts.texi:9753 msgid "" "Protection is needed as a new @emph{object} is created; the object formerly " "pointed to by the @code{SEXP} is still protected but now unused.@footnote{If " "no coercion was required, @code{coerceVector} would have passed the old " "object through unchanged.}" msgstr "" # #. type: Plain text #: R-exts.texi:9756 msgid "" "All the coercion functions do their own error-checking, and generate " "@code{NA}s with a warning or stop with an error as appropriate." msgstr "" # #. type: Plain text #: R-exts.texi:9761 msgid "" "Note that these coercion functions are @emph{not} the same as calling " "@code{as.numeric} (and so on) in @R{} code, as they do not dispatch on the " "class of the object. Thus it is normally preferable to do the coercion in " "the calling @R{} code." msgstr "" # #. type: Plain text #: R-exts.texi:9767 msgid "" "So far we have only seen how to create and coerce @R{} objects from C code, " "and how to extract the numeric data from numeric @R{} vectors. These can " "suffice to take us a long way in interfacing @R{} objects to numerical " "algorithms, but we may need to know a little more to create useful return " "objects." msgstr "" # #. type: Plain text #: R-exts.texi:9776 msgid "" "Many @R{} objects have attributes: some of the most useful are classes and " "the @code{dim} and @code{dimnames} that mark objects as matrices or arrays. " "It can also be helpful to work with the @code{names} attribute of vectors." msgstr "" # #. type: Plain text #: R-exts.texi:9780 msgid "" "To illustrate this, let us write code to take the outer product of two " "vectors (which @code{outer} and @code{%o%} already do). As usual the @R{} " "code is simple" msgstr "" # #. type: example #: R-exts.texi:9787 #, no-wrap msgid "" "out <- function(x, y)\n" "@{\n" " storage.mode(x) <- storage.mode(y) <- \"double\"\n" " .Call(\"out\", x, y)\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:9793 msgid "" "where we expect @code{x} and @code{y} to be numeric vectors (possibly " "integer), possibly with names. This time we do the coercion in the calling " "@R{} code." msgstr "" # #. type: Plain text #: R-exts.texi:9795 msgid "C code to do the computations is" msgstr "" # #. type: group #: R-exts.texi:9814 #, no-wrap msgid "" "SEXP out(SEXP x, SEXP y)\n" "@{\n" " int nx = length(x), ny = length(y);\n" " SEXP ans = PROTECT(allocMatrix(REALSXP, nx, ny));\n" " double *rx = REAL(x), *ry = REAL(y), *rans = REAL(ans);\n" " for(int i = 0; i < nx; i++) @{\n" "\tdouble tmp = rx[i];\n" "\tfor(int j = 0; j < ny; j++)\n" "\t rans[i + nx*j] = tmp * ry[j];\n" " @}\n" " UNPROTECT(1);\n" " return ans;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:9820 msgid "" "Note the way @code{REAL} is used: as it is a function call it can be " "considerably faster to store the result and index that." msgstr "" # #. type: Plain text #: R-exts.texi:9822 msgid "" "However, we would like to set the @code{dimnames} of the result. We can use" msgstr "" # #. type: group #: R-exts.texi:9833 #, no-wrap msgid "" "SEXP out(SEXP x, SEXP y)\n" "@{\n" " int nx = length(x), ny = length(y);\n" " SEXP ans = PROTECT(allocMatrix(REALSXP, nx, ny));\n" " double *rx = REAL(x), *ry = REAL(y), *rans = REAL(ans);\n" "\n" msgstr "" # #. type: group #: R-exts.texi:9839 #, no-wrap msgid "" " for(int i = 0; i < nx; i++) @{\n" " double tmp = rx[i];\n" " for(int j = 0; j < ny; j++)\n" "\trans[i + nx*j] = tmp * ry[j];\n" " @}\n" "\n" msgstr "" # #. type: group #: R-exts.texi:9844 #, no-wrap msgid "" " SEXP dimnames = PROTECT(allocVector(VECSXP, 2));\n" " SET_VECTOR_ELT(dimnames, 0, getAttrib(x, R_NamesSymbol));\n" " SET_VECTOR_ELT(dimnames, 1, getAttrib(y, R_NamesSymbol));\n" " setAttrib(ans, R_DimNamesSymbol, dimnames);\n" msgstr "" # #. type: group #: R-exts.texi:9850 #, no-wrap msgid "" " UNPROTECT(3);\n" " return ans;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:9855 msgid "" "This example introduces several new features. The @code{getAttrib} and " "@code{setAttrib}" msgstr "" # #. type: findex #: R-exts.texi:9855 #, no-wrap msgid "getAttrib" msgstr "" # #. type: findex #: R-exts.texi:9856 #, no-wrap msgid "setAttrib" msgstr "" # #. type: Plain text #: R-exts.texi:9861 msgid "" "functions get and set individual attributes. Their second argument is a " "@code{SEXP} defining the name in the symbol table of the attribute we want; " "these and many such symbols are defined in the header file @file{Rinternals." "h}." msgstr "" # #. type: Plain text #: R-exts.texi:9867 msgid "" "There are shortcuts here too: the functions @code{namesgets}, @code{dimgets} " "and @code{dimnamesgets} are the internal versions of the default methods of " "@code{names<-}, @code{dim<-} and @code{dimnames<-} (for vectors and arrays), " "and there are functions such as @code{GetMatrixDimnames} and " "@code{GetArrayDimnames}." msgstr "" # #. type: Plain text #: R-exts.texi:9870 msgid "" "What happens if we want to add an attribute that is not pre-defined? We need " "to add a symbol for it @emph{via} a call to" msgstr "" # #. type: findex #: R-exts.texi:9870 #, no-wrap msgid "install" msgstr "" # #. type: Plain text #: R-exts.texi:9873 msgid "" "@code{install}. Suppose for illustration we wanted to add an attribute " "@code{\"version\"} with value @code{3.0}. We could use" msgstr "" # #. type: group #: R-exts.texi:9881 #, no-wrap msgid "" " SEXP version;\n" " version = PROTECT(allocVector(REALSXP, 1));\n" " REAL(version)[0] = 3.0;\n" " setAttrib(ans, install(\"version\"), version);\n" " UNPROTECT(1);\n" msgstr "" # #. type: Plain text #: R-exts.texi:9888 msgid "" "Using @code{install} when it is not needed is harmless and provides a simple " "way to retrieve the symbol from the symbol table if it is already installed. " "However, the lookup takes a non-trivial amount of time, so consider code " "such as" msgstr "" # #. type: example #: R-exts.texi:9893 #, no-wrap msgid "" "static SEXP VerSymbol = NULL;\n" "...\n" " if (VerSymbol == NULL) VerSymbol = install(\"version\");\n" msgstr "" # #. type: Plain text #: R-exts.texi:9897 msgid "if it is to be done frequently." msgstr "" # #. type: Plain text #: R-exts.texi:9899 msgid "This example can be simplified by another convenience function:" msgstr "" # #. type: group #: R-exts.texi:9905 #, no-wrap msgid "" " SEXP version = PROTECT(ScalarReal(3.0));\n" " setAttrib(ans, install(\"version\"), version);\n" " UNPROTECT(1);\n" msgstr "" # #. type: Plain text #: R-exts.texi:9917 msgid "" "In @R{} the class is just the attribute named @code{\"class\"} so it can be " "handled as such, but there is a shortcut @code{classgets}. Suppose we want " "to give the return value in our example the class @code{\"mat\"}. We can use" msgstr "" # #. type: group #: R-exts.texi:9931 #, no-wrap msgid "" "#include <R.h>\n" "#include <Rinternals.h>\n" " ....\n" " SEXP ans, dim, dimnames, class;\n" " ....\n" " class = PROTECT(allocVector(STRSXP, 1));\n" " SET_STRING_ELT(class, 0, mkChar(\"mat\"));\n" " classgets(ans, class);\n" " UNPROTECT(4);\n" " return ans;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:9938 msgid "" "As the value is a character vector, we have to know how to create that from " "a C character array, which we do using the function @code{mkChar}." msgstr "" # #. type: Plain text #: R-exts.texi:9948 msgid "" "Some care is needed with lists, as @R{} moved early on from using LISP-like " "lists (now called ``pairlists'') to S-like generic vectors. As a result, " "the appropriate test for an object of mode @code{list} is @code{isNewList}, " "and we need @code{allocVector(VECSXP, @var{n}}) and @emph{not} " "@code{allocList(@var{n})}." msgstr "" # #. type: Plain text #: R-exts.texi:9951 msgid "" "List elements can be retrieved or set by direct access to the elements of " "the generic vector. Suppose we have a list object" msgstr "" # #. type: example #: R-exts.texi:9954 #, no-wrap msgid "a <- list(f = 1, g = 2, h = 3)\n" msgstr "" # #. type: Plain text #: R-exts.texi:9958 msgid "Then we can access @code{a$g} as @code{a[[2]]} by" msgstr "" # #. type: group #: R-exts.texi:9964 #, no-wrap msgid "" " double g;\n" " ....\n" " g = REAL(VECTOR_ELT(a, 1))[0];\n" msgstr "" # #. type: Plain text #: R-exts.texi:9969 msgid "" "This can rapidly become tedious, and the following function (based on one in " "package @pkg{stats}) is very useful:" msgstr "" # #. type: group #: R-exts.texi:9973 #, no-wrap msgid "" "/* get the list element named str, or return NULL */\n" "\n" msgstr "" # #. type: group #: R-exts.texi:9977 #, no-wrap msgid "" "SEXP getListElement(SEXP list, const char *str)\n" "@{\n" " SEXP elmt = R_NilValue, names = getAttrib(list, R_NamesSymbol);\n" msgstr "" # #. type: group #: R-exts.texi:9987 #, no-wrap msgid "" " for (int i = 0; i < length(list); i++)\n" "\tif(strcmp(CHAR(STRING_ELT(names, i)), str) == 0) @{\n" "\t elmt = VECTOR_ELT(list, i);\n" "\t break;\n" "\t@}\n" " return elmt;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:9992 msgid "and enables us to say" msgstr "" # #. type: group #: R-exts.texi:9997 #, no-wrap msgid "" " double g;\n" " g = REAL(getListElement(a, \"g\"))[0];\n" msgstr "" # #. type: cindex #: R-exts.texi:10002 #, no-wrap msgid "handling character data" msgstr "" # #. type: Plain text #: R-exts.texi:10008 msgid "" "R character vectors are stored as @code{STRSXP}s, a vector type like " "@code{VECSXP} where every element is of type @code{CHARSXP}. The " "@code{CHARSXP} elements of @code{STRSXP}s are accessed using " "@code{STRING_ELT} and @code{SET_STRING_ELT}." msgstr "" # #. type: Plain text #: R-exts.texi:10018 msgid "" "@code{CHARSXP}s are read-only objects and must never be modified. In " "particular, the C-style string contained in a @code{CHARSXP} should be " "treated as read-only and for this reason the @code{CHAR} function used to " "access the character data of a @code{CHARSXP} returns @code{(const char *)} " "(this also allows compilers to issue warnings about improper use). Since " "@code{CHARSXP}s are immutable, the same @code{CHARSXP} can be shared by any " "@code{STRSXP} needing an element representing the same string. @R{} " "maintains a global cache of @code{CHARSXP}s so that there is only ever one " "@code{CHARSXP} representing a given string in memory." msgstr "" # #. type: findex #: R-exts.texi:10019 #, no-wrap msgid "mkChar" msgstr "" # #. type: findex #: R-exts.texi:10020 #, no-wrap msgid "mkCharLen" msgstr "" # #. type: Plain text #: R-exts.texi:10027 msgid "" "You can obtain a @code{CHARSXP} by calling @code{mkChar} and providing a nul-" "terminated C-style string. This function will return a pre-existing " "@code{CHARSXP} if one with a matching string already exists, otherwise it " "will create a new one and add it to the cache before returning it to you. " "The variant @code{mkCharLen} can be used to create a @code{CHARSXP} from " "part of a buffer and will ensure null-termination." msgstr "" # #. type: Plain text #: R-exts.texi:10031 msgid "" "Note that @R{} character strings are restricted to @code{2^31 - 1} bytes, " "and hence so should the input to @code{mkChar} be (C allows longer strings " "on 64-bit platforms)." msgstr "" # #. type: cindex #: R-exts.texi:10034 #, no-wrap msgid "Finding variables" msgstr "" # #. type: cindex #: R-exts.texi:10035 #, no-wrap msgid "Setting variables" msgstr "" # #. type: Plain text #: R-exts.texi:10042 msgid "" "It will be usual that all the @R{} objects needed in our C computations are " "passed as arguments to @code{.Call} or @code{.External}, but it is possible " "to find the values of @R{} objects from within the C given their names. The " "following code is the equivalent of @code{get(name, envir = rho)}." msgstr "" # #. type: group #: R-exts.texi:10048 #, no-wrap msgid "" "SEXP getvar(SEXP name, SEXP rho)\n" "@{\n" " SEXP ans;\n" "\n" msgstr "" # #. type: group #: R-exts.texi:10057 #, no-wrap msgid "" " if(!isString(name) || length(name) != 1)\n" "\terror(\"name is not a single string\");\n" " if(!isEnvironment(rho))\n" "\terror(\"rho should be an environment\");\n" " ans = findVar(installChar(STRING_ELT(name, 0)), rho);\n" " Rprintf(\"first value is %f\\n\", REAL(ans)[0]);\n" " return R_NilValue;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:10061 msgid "The main work is done by" msgstr "" # #. type: findex #: R-exts.texi:10061 #, no-wrap msgid "findVar" msgstr "" # #. type: Plain text #: R-exts.texi:10065 msgid "" "@code{findVar}, but to use it we need to install @code{name} as a name in " "the symbol table. As we wanted the value for internal use, we return " "@code{NULL}." msgstr "" # #. type: Plain text #: R-exts.texi:10067 msgid "Similar functions with syntax" msgstr "" # #. type: group #: R-exts.texi:10072 #, no-wrap msgid "" "void defineVar(SEXP symbol, SEXP value, SEXP rho)\n" "void setVar(SEXP symbol, SEXP value, SEXP rho)\n" msgstr "" # #. type: findex #: R-exts.texi:10074 #, no-wrap msgid "defineVar" msgstr "" # #. type: findex #: R-exts.texi:10075 #, no-wrap msgid "setVar" msgstr "" # #. type: Plain text #: R-exts.texi:10091 msgid "" "can be used to assign values to @R{} variables. @code{defineVar} creates a " "new binding or changes the value of an existing binding in the specified " "environment frame; it is the analogue of @code{assign(symbol, value, envir = " "rho, inherits = FALSE)}, but unlike @code{assign}, @code{defineVar} does not " "make a copy of the object @code{value}.@footnote{You can assign a " "@emph{copy} of the object in the environment frame @code{rho} using " "@code{defineVar(symbol, duplicate(value), rho)}).} @code{setVar} searches " "for an existing binding for @code{symbol} in @code{rho} or its enclosing " "environments. If a binding is found, its value is changed to @code{value}. " "Otherwise, a new binding with the specified value is created in the global " "environment. This corresponds to @code{assign(symbol, value, envir = rho, " "inherits = TRUE)}." msgstr "" # #. type: Plain text #: R-exts.texi:10098 msgid "" "Some operations are done so frequently that there are convenience functions " "to handle them. (All these are provided via the header file @file{Rinternals." "h}.)" msgstr "" # #. type: Plain text #: R-exts.texi:10101 msgid "" "Suppose we wanted to pass a single logical argument @code{ignore_quotes}: we " "could use" msgstr "" # #. type: example #: R-exts.texi:10105 #, no-wrap msgid "" " int ign = asLogical(ignore_quotes);\n" " if(ign == NA_LOGICAL) error(\"'ignore_quotes' must be TRUE or FALSE\");\n" msgstr "" # #. type: Plain text #: R-exts.texi:10114 msgid "" "which will do any coercion needed (at least from a vector argument), and " "return @code{NA_LOGICAL} if the value passed was @code{NA} or coercion " "failed. There are also @code{asInteger}, @code{asReal} and " "@code{asComplex}. The function @code{asChar} returns a @code{CHARSXP}. All " "of these functions ignore any elements of an input vector after the first." msgstr "" # #. type: Plain text #: R-exts.texi:10116 msgid "To return a length-one real vector we can use" msgstr "" # #. type: example #: R-exts.texi:10119 #, no-wrap msgid "" " double x;\n" "\n" msgstr "" # #. type: example #: R-exts.texi:10122 #, no-wrap msgid "" " ...\n" " return ScalarReal(x);\n" msgstr "" # #. type: Plain text #: R-exts.texi:10128 msgid "" "and there are versions of this for all the atomic vector types (those for a " "length-one character vector being @code{ScalarString} with argument a " "@code{CHARSXP} and @code{mkString} with argument @code{const char *})." msgstr "" # #. type: Plain text #: R-exts.texi:10134 msgid "" "Some of the @code{is@var{XXXX}} functions differ from their apparent @R{}-" "level counterparts: for example @code{isVector} is true for any atomic " "vector type (@code{isVectorAtomic}) and for lists and expressions " "(@code{isVectorList}) (with no check on attributes). @code{isMatrix} is a " "test of a length-2 @code{\"dim\"} attribute." msgstr "" # #. type: Plain text #: R-exts.texi:10147 msgid "" "There are a series of small macros/functions to help construct pairlists and " "language objects (whose internal structures just differ by " "@code{SEXPTYPE}). Function @code{CONS(u, v)} is the basic building block: " "it constructs a pairlist from @code{u} followed by @code{v} (which is a " "pairlist or @code{R_NilValue}). @code{LCONS} is a variant that constructs a " "language object. Functions @code{list1} to @code{list5} construct a " "pairlist from one to five items, and @code{lang1} to @code{lang6} do the " "same for a language object (a function to call plus zero to five " "arguments). Functions @code{elt} and @code{lastElt} find the @var{i}th " "element and the last element of a pairlist, and @code{nthcdr} returns a " "pointer to the @var{n}th position in the pairlist (whose @code{CAR} is the " "@var{n}th item)." msgstr "" # #. type: Plain text #: R-exts.texi:10151 msgid "" "Functions @code{str2type} and @code{type2str} map @R{} length-one character " "strings to and from @code{SEXPTYPE} numbers, and @code{type2char} maps " "numbers to C character strings." msgstr "" # #. type: subsubsection #: R-exts.texi:10156 #: R-exts.texi:10158 #: R-exts.texi:10159 #, no-wrap msgid "Semi-internal convenience functions" msgstr "" # #. type: Plain text #: R-exts.texi:10164 msgid "" "There is quite a collection of functions that may be used in your C code " "@emph{if} you are willing to adapt to rare ``API'' changes. These typically " "contain ``workhorses'' of their @R{} counterparts." msgstr "" # #. type: Plain text #: R-exts.texi:10167 msgid "" "Functions @code{any_duplicated} and @code{any_duplicated3} are fast versions " "of @R{}'s @code{any(duplicated(.))}." msgstr "" # #. type: Plain text #: R-exts.texi:10169 msgid "" "Function @code{R_compute_identical} corresponds to @R{}'s @code{identical} " "function." msgstr "" # #. type: findex #: R-exts.texi:10173 #, no-wrap msgid "duplicate" msgstr "" # #. type: cindex #: R-exts.texi:10174 #, no-wrap msgid "Copying objects" msgstr "" # #. type: Plain text #: R-exts.texi:10177 msgid "When assignments are done in @R{} such as" msgstr "" # #. type: example #: R-exts.texi:10181 #, no-wrap msgid "" "x <- 1:10\n" "y <- x\n" msgstr "" # #. type: Plain text #: R-exts.texi:10193 msgid "" "the named object is not necessarily copied, so after those two assignments " "@code{y} and @code{x} are bound to the same @code{SEXPREC} (the structure a " "@code{SEXP} points to). This means that any code which alters one of them " "has to make a copy before modifying the copy if the usual @R{} semantics are " "to apply. Note that whereas @code{.C} and @code{.Fortran} do copy their " "arguments (unless the dangerous @code{dup = FALSE} is used), @code{.Call} " "and @code{.External} do not. So @code{duplicate} is commonly called on " "arguments to @code{.Call} before modifying them." msgstr "" # #. type: Plain text #: R-exts.texi:10202 msgid "" "However, at least some of this copying is unneeded. In the first assignment " "shown, @code{x <- 1:10}, @R{} first creates an object with value @code{1:10} " "and then assigns it to @code{x} but if @code{x} is modified no copy is " "necessary as the temporary object with value @code{1:10} cannot be referred " "to again. @R{} distinguishes between named and unnamed objects @emph{via} a " "field in a @code{SEXPREC} that can be accessed @emph{via} the macros " "@code{NAMED} and @code{SET_NAMED}. This can take values" msgstr "" # #. type: item #: R-exts.texi:10204 #, no-wrap msgid "0" msgstr "" # #. type: table #: R-exts.texi:10206 msgid "The object is not bound to any symbol" msgstr "" # #. type: item #: R-exts.texi:10206 #, no-wrap msgid "1" msgstr "" # #. type: table #: R-exts.texi:10208 msgid "The object has been bound to exactly one symbol" msgstr "" # #. type: item #: R-exts.texi:10208 #, no-wrap msgid "2" msgstr "" # #. type: table #: R-exts.texi:10211 msgid "" "The object has potentially been bound to two or more symbols, and one should " "act as if another variable is currently bound to this value." msgstr "" # #. type: Plain text #: R-exts.texi:10216 msgid "" "Note the past tenses: @R{} does not do full reference counting and there may " "currently be fewer bindings." msgstr "" # #. type: Plain text #: R-exts.texi:10223 msgid "" "It is safe to modify the value of any @code{SEXP} for which " "@code{NAMED(foo)} is zero, and if @code{NAMED(foo)} is two, the value should " "be duplicated (@emph{via} a call to @code{duplicate}) before any " "modification. Note that it is the responsibility of the author of the code " "making the modification to do the duplication, even if it is @code{x} whose " "value is being modified after @code{y <- x}." msgstr "" # #. type: Plain text #: R-exts.texi:10228 msgid "" "The case @code{NAMED(foo) == 1} allows some optimization, but it can be " "ignored (and duplication done whenever @code{NAMED(foo) > 0}). (This " "optimization is not currently usable in user code.) It is intended for use " "within replacement functions. Suppose we used" msgstr "" # #. type: example #: R-exts.texi:10232 #, no-wrap msgid "" "x <- 1:10\n" "foo(x) <- 3\n" msgstr "" # #. type: Plain text #: R-exts.texi:10236 msgid "which is computed as" msgstr "" # #. type: example #: R-exts.texi:10240 #, no-wrap msgid "" "x <- 1:10\n" "x <- \"foo<-\"(x, 3)\n" msgstr "" # #. type: Plain text #: R-exts.texi:10249 msgid "" "Then inside @code{\"foo<-\"} the object pointing to the current value of " "@code{x} will have @code{NAMED(foo)} as one, and it would be safe to modify " "it as the only symbol bound to it is @code{x} and that will be rebound " "immediately. (Provided the remaining code in @code{\"foo<-\"} make no " "reference to @code{x}, and no one is going to attempt a direct call such as " "@code{y <- \"foo<-\"(x)}.)" msgstr "" # #. type: Plain text #: R-exts.texi:10251 msgid "This mechanism is likely to be replaced in future versions of @R{}." msgstr "" # #. type: section #: R-exts.texi:10258 #, no-wrap msgid "Interface functions @code{.Call} and @code{.External}" msgstr "" # #. type: Plain text #: R-exts.texi:10262 msgid "In this section we consider the details of the @R{}/C interfaces." msgstr "" # #. type: Plain text #: R-exts.texi:10267 msgid "" "These two interfaces have almost the same functionality. @code{.Call} is " "based on the interface of the same name in @Sl{} version 4, and @code{." "External} is based on @R{}'s @code{.Internal}. @code{.External} is more " "complex but allows a variable number of arguments." msgstr "" # #. type: node #: R-exts.texi:10272 #: R-exts.texi:10274 #: R-exts.texi:10315 #, no-wrap msgid "Calling .Call" msgstr "" # #. type: node #: R-exts.texi:10272 #: R-exts.texi:10274 #: R-exts.texi:10315 #: R-exts.texi:10456 #, no-wrap msgid "Calling .External" msgstr "" # #. type: subsection #: R-exts.texi:10272 #: R-exts.texi:10315 #: R-exts.texi:10456 #: R-exts.texi:10457 #, no-wrap msgid "Missing and special values" msgstr "" # #. type: subsection #: R-exts.texi:10275 #, no-wrap msgid "Calling @code{.Call}" msgstr "" # #. type: Plain text #: R-exts.texi:10281 msgid "" "Let us convert our finite convolution example to use @code{.Call}. The " "calling function in @R{} is" msgstr "" # #. type: example #: R-exts.texi:10284 #, no-wrap msgid "conv <- function(a, b) .Call(\"convolve2\", a, b)\n" msgstr "" # #. type: Plain text #: R-exts.texi:10289 msgid "" "which could hardly be simpler, but as we shall see all the type coercion is " "transferred to the C code, which is" msgstr "" # #. type: group #: R-exts.texi:10300 #, no-wrap msgid "" "SEXP convolve2(SEXP a, SEXP b)\n" "@{\n" " int na, nb, nab;\n" " double *xa, *xb, *xab;\n" " SEXP ab;\n" "\n" msgstr "" # #. type: group #: R-exts.texi:10312 #, no-wrap msgid "" " a = PROTECT(coerceVector(a, REALSXP));\n" " b = PROTECT(coerceVector(b, REALSXP));\n" " na = length(a); nb = length(b); nab = na + nb - 1;\n" " ab = PROTECT(allocVector(REALSXP, nab));\n" " xa = REAL(a); xb = REAL(b); xab = REAL(ab);\n" " for(int i = 0; i < nab; i++) xab[i] = 0.0;\n" " for(int i = 0; i < na; i++)\n" "\tfor(int j = 0; j < nb; j++) xab[i + j] += xa[i] * xb[j];\n" " UNPROTECT(3);\n" " return ab;\n" "@}\n" msgstr "" # #. type: subsection #: R-exts.texi:10316 #, no-wrap msgid "Calling @code{.External}" msgstr "" # #. type: Plain text #: R-exts.texi:10322 msgid "" "We can use the same example to illustrate @code{.External}. The @R{} code " "changes only by replacing @code{.Call} by @code{.External}" msgstr "" # #. type: example #: R-exts.texi:10325 #, no-wrap msgid "conv <- function(a, b) .External(\"convolveE\", a, b)\n" msgstr "" # #. type: Plain text #: R-exts.texi:10331 msgid "" "but the main change is how the arguments are passed to the C code, this time " "as a single SEXP. The only change to the C code is how we handle the " "arguments." msgstr "" # #. type: group #: R-exts.texi:10342 #, no-wrap msgid "" "SEXP convolveE(SEXP args)\n" "@{\n" " int i, j, na, nb, nab;\n" " double *xa, *xb, *xab;\n" " SEXP a, b, ab;\n" "\n" msgstr "" # #. type: group #: R-exts.texi:10347 #, no-wrap msgid "" " a = PROTECT(coerceVector(CADR(args), REALSXP));\n" " b = PROTECT(coerceVector(CADDR(args), REALSXP));\n" " ...\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:10353 msgid "" "Once again we do not need to protect the arguments, as in the @R{} side of " "the interface they are objects that are already in use. The macros" msgstr "" # #. type: group #: R-exts.texi:10360 #, no-wrap msgid "" " first = CADR(args);\n" " second = CADDR(args);\n" " third = CADDDR(args);\n" " fourth = CAD4R(args);\n" msgstr "" # #. type: Plain text #: R-exts.texi:10366 msgid "" "provide convenient ways to access the first four arguments. More generally " "we can use the" msgstr "" # #. type: findex #: R-exts.texi:10366 #, no-wrap msgid "CAR" msgstr "" # #. type: findex #: R-exts.texi:10367 #, no-wrap msgid "CDR" msgstr "" # #. type: Plain text #: R-exts.texi:10369 msgid "@code{CDR} and @code{CAR} macros as in" msgstr "" # #. type: group #: R-exts.texi:10374 #, no-wrap msgid "" " args = CDR(args); a = CAR(args);\n" " args = CDR(args); b = CAR(args);\n" msgstr "" # #. type: Plain text #: R-exts.texi:10380 msgid "" "which clearly allows us to extract an unlimited number of arguments (whereas " "@code{.Call} has a limit, albeit at 65 not a small one)." msgstr "" # #. type: Plain text #: R-exts.texi:10388 msgid "" "More usefully, the @code{.External} interface provides an easy way to handle " "calls with a variable number of arguments, as @code{length(args)} will give " "the number of arguments supplied (of which the first is ignored). We may " "need to know the names (`tags') given to the actual arguments, which we can " "by using the @code{TAG} macro and using something like the following " "example, that prints the names and the first value of its arguments if they " "are vector types." msgstr "" # #. type: group #: R-exts.texi:10402 #, no-wrap msgid "" "SEXP showArgs(SEXP args)\n" "@{\n" " args = CDR(args); /* skip 'name' */\n" " for(int i = 0; args != R_NilValue; i++, args = CDR(args)) @{\n" "\tconst char *name =\n" "\t isNull(TAG(args)) ? \"\" : CHAR(PRINTNAME(TAG(args)));\n" "\tSEXP el = CAR(args);\n" "\tif (length(el) == 0) @{\n" "\t Rprintf(\"[%d] '%s' R type, length 0\\n\", i+1, name);\n" "\t continue;\n" "\t@}\n" msgstr "" # #. type: group #: R-exts.texi:10408 #, no-wrap msgid "" "\tswitch(TYPEOF(el)) @{\n" "\tcase REALSXP:\n" "\t Rprintf(\"[%d] '%s' %f\\n\", i+1, name, REAL(el)[0]);\n" "\t break;\n" msgstr "" # #. type: group #: R-exts.texi:10414 #, no-wrap msgid "" "\tcase LGLSXP:\n" "\tcase INTSXP:\n" "\t Rprintf(\"[%d] '%s' %d\\n\", i+1, name, INTEGER(el)[0]);\n" "\t break;\n" msgstr "" # #. type: group #: R-exts.texi:10422 #, no-wrap msgid "" "\tcase CPLXSXP:\n" "\t@{\n" "\t Rcomplex cpl = COMPLEX(el)[0];\n" "\t Rprintf(\"[%d] '%s' %f + %fi\\n\", i+1, name, cpl.r, cpl.i);\n" "\t@}\n" "\t break;\n" msgstr "" # #. type: group #: R-exts.texi:10428 #, no-wrap msgid "" "\tcase STRSXP:\n" "\t Rprintf(\"[%d] '%s' %s\\n\", i+1, name,\n" "\t\t CHAR(STRING_ELT(el, 0)));\n" "\t break;\n" msgstr "" # #. type: group #: R-exts.texi:10436 #, no-wrap msgid "" "\tdefault:\n" "\t Rprintf(\"[%d] '%s' R type\\n\", i+1, name);\n" " @}\n" " @}\n" " return R_NilValue;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:10440 msgid "This can be called by the wrapper function" msgstr "" # #. type: example #: R-exts.texi:10443 #, no-wrap msgid "showArgs <- function(...) invisible(.External(\"showArgs\", ...))\n" msgstr "" # #. type: Plain text #: R-exts.texi:10448 msgid "" "Note that this style of programming is convenient but not necessary, as an " "alternative style is" msgstr "" # #. type: example #: R-exts.texi:10451 #, no-wrap msgid "showArgs1 <- function(...) invisible(.Call(\"showArgs1\", list(...)))\n" msgstr "" # #. type: Plain text #: R-exts.texi:10455 msgid "The (very similar) C code is in the scripts." msgstr "" # #. type: cindex #: R-exts.texi:10458 #: R-exts.texi:11666 #, no-wrap msgid "Missing values" msgstr "" # #. type: cindex #: R-exts.texi:10459 #: R-exts.texi:11667 #, no-wrap msgid "IEEE special values" msgstr "" # #. type: Plain text #: R-exts.texi:10471 msgid "" "One piece of error-checking the @code{.C} call does (unless @code{NAOK} is " "true) is to check for missing (@code{NA}) and @acronym{IEEE} special values " "(@code{Inf}, @code{-Inf} and @code{NaN}) and give an error if any are " "found. With the @code{.Call} interface these will be passed to our code. " "In this example the special values are no problem, as @acronym{IEC60559} " "arithmetic will handle them correctly. In the current implementation this " "is also true of @code{NA} as it is a type of @code{NaN}, but it is unwise to " "rely on such details. Thus we will re-write the code to handle @code{NA}s " "using macros defined in @file{R_ext/Arith.h} included by @file{R.h}." msgstr "" # #. type: Plain text #: R-exts.texi:10474 msgid "" "The code changes are the same in any of the versions of @code{convolve2} or " "@code{convolveE}:" msgstr "" # #. type: group #: R-exts.texi:10485 #, no-wrap msgid "" " ...\n" " for(int i = 0; i < na; i++)\n" " for(int j = 0; j < nb; j++)\n" "\tif(ISNA(xa[i]) || ISNA(xb[j]) || ISNA(xab[i + j]))\n" "\t xab[i + j] = NA_REAL;\n" "\telse\n" "\t xab[i + j] += xa[i] * xb[j];\n" " ...\n" msgstr "" # #. type: findex #: R-exts.texi:10488 #: R-exts.texi:11668 #, no-wrap msgid "ISNA" msgstr "" # #. type: findex #: R-exts.texi:10489 #: R-exts.texi:11669 #, no-wrap msgid "ISNAN" msgstr "" # #. type: Plain text #: R-exts.texi:10498 msgid "" "Note that the @code{ISNA} macro, and the similar macros @code{ISNAN} (which " "checks for @code{NaN} or @code{NA}) and @code{R_FINITE} (which is false for " "@code{NA} and all the special values), only apply to numeric values of type " "@code{double}. Missingness of integers, logicals and character strings can " "be tested by equality to the constants @code{NA_INTEGER}, @code{NA_LOGICAL} " "and @code{NA_STRING}. These and @code{NA_REAL} can be used to set elements " "of @R{} vectors to @code{NA}." msgstr "" # #. type: Plain text #: R-exts.texi:10501 msgid "" "The constants @code{R_NaN}, @code{R_PosInf} and @code{R_NegInf} can be used " "to set @code{double}s to the special values." msgstr "" # #. type: Plain text #: R-exts.texi:10507 msgid "The main function we will use is" msgstr "" # #. type: example #: R-exts.texi:10510 #, no-wrap msgid "SEXP eval(SEXP expr, SEXP rho);\n" msgstr "" # #. type: Plain text #: R-exts.texi:10517 msgid "" "the equivalent of the interpreted @R{} code @code{eval(expr, envir = rho)} " "(so @code{rho} must be an environment), although we can also make use of " "@code{findVar}, @code{defineVar} and @code{findFun} (which restricts the " "search to functions)." msgstr "" # #. type: Plain text #: R-exts.texi:10520 msgid "" "To see how this might be applied, here is a simplified internal version of " "@code{lapply} for expressions, used as" msgstr "" # #. type: group #: R-exts.texi:10525 #, no-wrap msgid "" "a <- list(a = 1:5, b = rnorm(10), test = runif(100))\n" ".Call(\"lapply\", a, quote(sum(x)), new.env())\n" msgstr "" # #. type: group #: R-exts.texi:10537 #, no-wrap msgid "" "SEXP lapply(SEXP list, SEXP expr, SEXP rho)\n" "@{\n" " int n = length(list);\n" " SEXP ans;\n" "\n" msgstr "" # #. type: group #: R-exts.texi:10549 #, no-wrap msgid "" " if(!isNewList(list)) error(\"'list' must be a list\");\n" " if(!isEnvironment(rho)) error(\"'rho' should be an environment\");\n" " ans = PROTECT(allocVector(VECSXP, n));\n" " for(int i = 0; i < n; i++) @{\n" "\tdefineVar(install(\"x\"), VECTOR_ELT(list, i), rho);\n" "\tSET_VECTOR_ELT(ans, i, eval(expr, rho));\n" " @}\n" " setAttrib(ans, R_NamesSymbol, getAttrib(list, R_NamesSymbol));\n" " UNPROTECT(1);\n" " return ans;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:10557 msgid "" "It would be closer to @code{lapply} if we could pass in a function rather " "than an expression. One way to do this is @emph{via} interpreted @R{} code " "as in the next example, but it is possible (if somewhat obscure) to do this " "in C code. The following is based on the code in @file{src/main/optimize.c}." msgstr "" # #. type: group #: R-exts.texi:10564 #, no-wrap msgid "" "SEXP lapply2(SEXP list, SEXP fn, SEXP rho)\n" "@{\n" " int n = length(list);\n" " SEXP R_fcall, ans;\n" "\n" msgstr "" # #. type: group #: R-exts.texi:10578 #, no-wrap msgid "" " if(!isNewList(list)) error(\"'list' must be a list\");\n" " if(!isFunction(fn)) error(\"'fn' must be a function\");\n" " if(!isEnvironment(rho)) error(\"'rho' should be an environment\");\n" " R_fcall = PROTECT(lang2(fn, R_NilValue));\n" " ans = PROTECT(allocVector(VECSXP, n));\n" " for(int i = 0; i < n; i++) @{\n" "\tSETCADR(R_fcall, VECTOR_ELT(list, i));\n" "\tSET_VECTOR_ELT(ans, i, eval(R_fcall, rho));\n" " @}\n" " setAttrib(ans, R_NamesSymbol, getAttrib(list, R_NamesSymbol));\n" " UNPROTECT(2);\n" " return ans;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:10583 msgid "used by" msgstr "" # #. type: example #: R-exts.texi:10586 #, no-wrap msgid ".Call(\"lapply2\", a, sum, new.env())\n" msgstr "" # #. type: Plain text #: R-exts.texi:10592 msgid "" "Function @code{lang2} creates an executable pairlist of two elements, but " "this will only be clear to those with a knowledge of a LISP-like language." msgstr "" # #. type: Plain text #: R-exts.texi:10596 msgid "" "As a more comprehensive example of constructing an @R{} call in C code and " "evaluating, consider the following fragment of @code{printAttributes} in " "@file{src/main/print.c}." msgstr "" # #. type: example #: R-exts.texi:10612 #, no-wrap msgid "" " /* Need to construct a call to\n" " print(CAR(a), digits=digits)\n" " based on the R_print structure, then eval(call, env).\n" " See do_docall for the template for this sort of thing.\n" " */\n" " SEXP s, t;\n" " t = s = PROTECT(allocList(3));\n" " SET_TYPEOF(s, LANGSXP);\n" " SETCAR(t, install(\"print\")); t = CDR(t);\n" " SETCAR(t, CAR(a)); t = CDR(t);\n" " SETCAR(t, ScalarInteger(digits));\n" " SET_TAG(t, install(\"digits\"));\n" " eval(s, env);\n" " UNPROTECT(1);\n" msgstr "" # #. type: Plain text #: R-exts.texi:10619 msgid "" "At this point @code{CAR(a)} is the @R{} object to be printed, the current " "attribute. There are three steps: the call is constructed as a pairlist of " "length 3, the list is filled in, and the expression represented by the " "pairlist is evaluated." msgstr "" # #. type: Plain text #: R-exts.texi:10627 msgid "" "A pairlist is quite distinct from a generic vector list, the only user-" "visible form of list in @R{}. A pairlist is a linked list (with " "@code{CDR(t)} computing the next entry), with items (accessed by " "@code{CAR(t)}) and names or tags (set by @code{SET_TAG}). In this call " "there are to be three items, a symbol (pointing to the function to be " "called) and two argument values, the first unnamed and the second named. " "Setting the type to @code{LANGSXP} makes this a call which can be evaluated." msgstr "" # #. type: node #: R-exts.texi:10631 #: R-exts.texi:10633 #: R-exts.texi:10634 #: R-exts.texi:10635 #: R-exts.texi:10716 #, no-wrap msgid "Zero-finding" msgstr "" # #. type: subsection #: R-exts.texi:10631 #: R-exts.texi:10633 #: R-exts.texi:10716 #: R-exts.texi:10717 #, no-wrap msgid "Calculating numerical derivatives" msgstr "" # #. type: Plain text #: R-exts.texi:10640 msgid "" "In this section we re-work the example of Becker, Chambers & Wilks (1988, pp." "~205--10) on finding a zero of a univariate function. The @R{} code and an " "example are" msgstr "" # #. type: example #: R-exts.texi:10651 #, no-wrap msgid "" "zero <- function(f, guesses, tol = 1e-7) @{\n" " f.check <- function(x) @{\n" "\tx <- f(x)\n" "\tif(!is.numeric(x)) stop(\"Need a numeric result\")\n" "\tas.double(x)\n" " @}\n" " .Call(\"zero\", body(f.check), as.double(guesses), as.double(tol),\n" "\t new.env())\n" "@}\n" "\n" msgstr "" # #. type: example #: R-exts.texi:10654 #, no-wrap msgid "" "cube1 <- function(x) (x^2 + 1) * (x - 1.5)\n" "zero(cube1, c(0, 5))\n" msgstr "" # #. type: Plain text #: R-exts.texi:10659 msgid "" "where this time we do the coercion and error-checking in the @R{} code. The " "C code is" msgstr "" #. type: group #: R-exts.texi:10669 #, no-wrap msgid "" "SEXP mkans(double x)\n" "@{\n" " // no need for PROTECT() here, as REAL(.) does not allocate:\n" " SEXP ans = allocVector(REALSXP, 1);\n" " REAL(ans)[0] = x;\n" " return ans;\n" "@}\n" msgstr "" # #. type: group #: R-exts.texi:10682 #, no-wrap msgid "" "double feval(double x, SEXP f, SEXP rho)\n" "@{\n" " // a version with (too) much PROTECT()ion .. \"better safe than sorry\"\n" " SEXP symbol, value;\n" " PROTECT(symbol = install(\"x\"));\n" " PROTECT(value = mkans(x));\n" " defineVar(symbol, value, rho);\n" " UNPROTECT(2);\n" " return(REAL(eval(f, rho))[0]);\n" "@}\n" msgstr "" # #. type: group #: R-exts.texi:10690 #, no-wrap msgid "" "SEXP zero(SEXP f, SEXP guesses, SEXP stol, SEXP rho)\n" "@{\n" " double x0 = REAL(guesses)[0], x1 = REAL(guesses)[1],\n" "\t tol = REAL(stol)[0];\n" " double f0, f1, fc, xc;\n" msgstr "" # #. type: group #: R-exts.texi:10698 #, no-wrap msgid "" " if(tol <= 0.0) error(\"non-positive tol value\");\n" " f0 = feval(x0, f, rho); f1 = feval(x1, f, rho);\n" " if(f0 == 0.0) return mkans(x0);\n" " if(f1 == 0.0) return mkans(x1);\n" " if(f0*f1 > 0.0) error(\"x[0] and x[1] have the same sign\");\n" msgstr "" # #. type: group #: R-exts.texi:10713 #, no-wrap msgid "" " for(;;) @{\n" "\txc = 0.5*(x0+x1);\n" "\tif(fabs(x0-x1) < tol) return mkans(xc);\n" "\tfc = feval(xc, f, rho);\n" "\tif(fc == 0) return mkans(xc);\n" "\tif(f0*fc > 0.0) @{\n" "\t x0 = xc; f0 = fc;\n" "\t@} else @{\n" "\t x1 = xc; f1 = fc;\n" "\t@}\n" " @}\n" "@}\n" msgstr "" # #. type: cindex #: R-exts.texi:10718 #, no-wrap msgid "Numerical derivatives" msgstr "" # #. type: Plain text #: R-exts.texi:10724 msgid "" "We will use a longer example (by Saikat DebRoy) to illustrate the use of " "evaluation and @code{.External}. This calculates numerical derivatives, " "something that could be done as effectively in interpreted @R{} code but may " "be needed as part of a larger C calculation." msgstr "" # #. type: Plain text #: R-exts.texi:10726 msgid "An interpreted @R{} version and an example are" msgstr "" # #. type: group #: R-exts.texi:10748 #, no-wrap msgid "" "numeric.deriv <- function(expr, theta, rho=sys.frame(sys.parent()))\n" "@{\n" " eps <- sqrt(.Machine$double.eps)\n" " ans <- eval(substitute(expr), rho)\n" " grad <- matrix(, length(ans), length(theta),\n" "\t\t dimnames=list(NULL, theta))\n" " for (i in seq_along(theta)) @{\n" "\told <- get(theta[i], envir=rho)\n" "\tdelta <- eps * max(1, abs(old))\n" "\tassign(theta[i], old+delta, envir=rho)\n" "\tans1 <- eval(substitute(expr), rho)\n" "\tassign(theta[i], old, envir=rho)\n" "\tgrad[, i] <- (ans1 - ans)/delta\n" " @}\n" " attr(ans, \"gradient\") <- grad\n" " ans\n" "@}\n" "omega <- 1:5; x <- 1; y <- 2\n" "numeric.deriv(sin(omega*x*y), c(\"x\", \"y\"))\n" msgstr "" # #. type: Plain text #: R-exts.texi:10754 msgid "" "where @code{expr} is an expression, @code{theta} a character vector of " "variable names and @code{rho} the environment to be used." msgstr "" # #. type: Plain text #: R-exts.texi:10756 msgid "For the compiled version the call from @R{} will be" msgstr "" # #. type: example #: R-exts.texi:10759 #, no-wrap msgid ".External(\"numeric_deriv\", @var{expr}, @var{theta}, @var{rho})\n" msgstr "" # #. type: Plain text #: R-exts.texi:10763 msgid "with example usage" msgstr "" # #. type: example #: R-exts.texi:10767 #, no-wrap msgid "" ".External(\"numeric_deriv\", quote(sin(omega*x*y)),\n" "\t c(\"x\", \"y\"), .GlobalEnv)\n" msgstr "" # #. type: Plain text #: R-exts.texi:10772 msgid "" "Note the need to quote the expression to stop it being evaluated in the " "caller." msgstr "" # #. type: Plain text #: R-exts.texi:10774 msgid "Here is the complete C code which we will explain section by section." msgstr "" # #. type: group #: R-exts.texi:10779 #, no-wrap msgid "" "#include <R.h> /* for DOUBLE_EPS */\n" "#include <Rinternals.h>\n" "\n" msgstr "" # #. type: group #: R-exts.texi:10785 #, no-wrap msgid "" "SEXP numeric_deriv(SEXP args)\n" "@{\n" " SEXP theta, expr, rho, ans, ans1, gradient, par, dimnames;\n" " double tt, xx, delta, eps = sqrt(DOUBLE_EPS), *rgr, *rans;\n" " int i, start;\n" msgstr "" # #. type: group #: R-exts.texi:10793 #: R-exts.texi:10836 #, no-wrap msgid "" " expr = CADR(args);\n" " if(!isString(theta = CADDR(args)))\n" "\terror(\"theta should be of type character\");\n" " if(!isEnvironment(rho = CADDDR(args)))\n" "\terror(\"rho should be an environment\");\n" msgstr "" # #. type: group #: R-exts.texi:10799 #, no-wrap msgid "" " ans = PROTECT(coerceVector(eval(expr, rho), REALSXP));\n" " gradient = PROTECT(allocMatrix(REALSXP, LENGTH(ans), LENGTH(theta)));\n" " rgr = REAL(gradient); rans = REAL(ans);\n" msgstr "" # #. type: group #: R-exts.texi:10814 #, no-wrap msgid "" " for(i = 0, start = 0; i < LENGTH(theta); i++, start += LENGTH(ans)) @{\n" "\tpar = PROTECT(findVar(installChar(STRING_ELT(theta, i)), rho));\n" "\ttt = REAL(par)[0];\n" "\txx = fabs(tt);\n" "\tdelta = (xx < 1) ? eps : xx*eps;\n" "\tREAL(par)[0] += delta;\n" "\tans1 = PROTECT(coerceVector(eval(expr, rho), REALSXP));\n" "\tfor(int j = 0; j < LENGTH(ans); j++)\n" "\t rgr[j + start] = (REAL(ans1)[j] - rans[j])/delta;\n" "\tREAL(par)[0] = tt;\n" "\tUNPROTECT(2); /* par, ans1 */\n" " @}\n" msgstr "" # #. type: group #: R-exts.texi:10824 #, no-wrap msgid "" " dimnames = PROTECT(allocVector(VECSXP, 2));\n" " SET_VECTOR_ELT(dimnames, 1, theta);\n" " dimnamesgets(gradient, dimnames);\n" " setAttrib(ans, install(\"gradient\"), gradient);\n" " UNPROTECT(3); /* ans gradient dimnames */\n" " return ans;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:10828 msgid "The code to handle the arguments is" msgstr "" # #. type: Plain text #: R-exts.texi:10845 msgid "" "Note that we check for correct types of @code{theta} and @code{rho} but do " "not check the type of @code{expr}. That is because @code{eval} can handle " "many types of @R{} objects other than @code{EXPRSXP}. There is no useful " "coercion we can do, so we stop with an error message if the arguments are " "not of the correct mode." msgstr "" # #. type: Plain text #: R-exts.texi:10848 msgid "" "The first step in the code is to evaluate the expression in the environment " "@code{rho}, by" msgstr "" # #. type: example #: R-exts.texi:10851 #, no-wrap msgid " ans = PROTECT(coerceVector(eval(expr, rho), REALSXP));\n" msgstr "" # #. type: Plain text #: R-exts.texi:10855 msgid "We then allocate space for the calculated derivative by" msgstr "" # #. type: example #: R-exts.texi:10858 #, no-wrap msgid " gradient = PROTECT(allocMatrix(REALSXP, LENGTH(ans), LENGTH(theta)));\n" msgstr "" # #. type: Plain text #: R-exts.texi:10866 msgid "" "The first argument to @code{allocMatrix} gives the @code{SEXPTYPE} of the " "matrix: here we want it to be @code{REALSXP}. The other two arguments are " "the numbers of rows and columns. (Note that @code{LENGTH} is intended to be " "used for vectors: @code{length} is more generally applicable.)" msgstr "" # #. type: group #: R-exts.texi:10871 #, no-wrap msgid "" " for(i = 0, start = 0; i < LENGTH(theta); i++, start += LENGTH(ans)) @{\n" "\tpar = PROTECT(findVar(installChar(STRING_ELT(theta, i)), rho));\n" msgstr "" # #. type: Plain text #: R-exts.texi:10884 msgid "" "Here, we are entering a for loop. We loop through each of the variables. " "In the @code{for} loop, we first create a symbol corresponding to the " "@code{i}'th element of the @code{STRSXP} @code{theta}. Here, " "@code{STRING_ELT(theta, i)} accesses the @code{i}'th element of the " "@code{STRSXP} @code{theta}. Macro @code{CHAR()} extracts the actual " "character representation@footnote{@pxref{Character encoding issues} for why " "this might not be what is required.} of it: it returns a pointer. We then " "install the name and use @code{findVar} to find its value." msgstr "" # #. type: group #: R-exts.texi:10892 #, no-wrap msgid "" "\ttt = REAL(par)[0];\n" "\txx = fabs(tt);\n" "\tdelta = (xx < 1) ? eps : xx*eps;\n" "\tREAL(par)[0] += delta;\n" "\tans1 = PROTECT(coerceVector(eval(expr, rho), REALSXP));\n" msgstr "" # #. type: Plain text #: R-exts.texi:10903 msgid "" "We first extract the real value of the parameter, then calculate " "@code{delta}, the increment to be used for approximating the numerical " "derivative. Then we change the value stored in @code{par} (in environment " "@code{rho}) by @code{delta} and evaluate @code{expr} in environment " "@code{rho} again. Because we are directly dealing with original @R{} memory " "locations here, @R{} does the evaluation for the changed parameter value." msgstr "" # #. type: group #: R-exts.texi:10911 #, no-wrap msgid "" "\tfor(int j = 0; j < LENGTH(ans); j++)\n" "\t rgr[j + start] = (REAL(ans1)[j] - rans[j])/delta;\n" "\tREAL(par)[0] = tt;\n" "\tUNPROTECT(2);\n" " @}\n" msgstr "" # #. type: Plain text #: R-exts.texi:10917 msgid "" "Now, we compute the @code{i}'th column of the gradient matrix. Note how it " "is accessed: @R{} stores matrices by column (like FORTRAN)." msgstr "" # #. type: group #: R-exts.texi:10927 #, no-wrap msgid "" " dimnames = PROTECT(allocVector(VECSXP, 2));\n" " SET_VECTOR_ELT(dimnames, 1, theta);\n" " dimnamesgets(gradient, dimnames);\n" " setAttrib(ans, install(\"gradient\"), gradient);\n" " UNPROTECT(3);\n" " return ans;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:10938 msgid "" "First we add column names to the gradient matrix. This is done by " "allocating a list (a @code{VECSXP}) whose first element, the row names, is " "@code{NULL} (the default) and the second element, the column names, is set " "as @code{theta}. This list is then assigned as the attribute having the " "symbol @code{R_DimNamesSymbol}. Finally we set the gradient matrix as the " "gradient attribute of @code{ans}, unprotect the remaining protected " "locations and return the answer @code{ans}." msgstr "" # #. type: Plain text #: R-exts.texi:10949 msgid "" "Suppose an @R{} extension want to accept an @R{} expression from the user " "and evaluate it. The previous section covered evaluation, but the " "expression will be entered as text and needs to be parsed first. A small " "part of @R{}'s parse interface is declared in header file @file{R_ext/Parse." "h}@footnote{This is only guaranteed to show the current interface: it is " "liable to change.}." msgstr "" # #. type: Plain text #: R-exts.texi:10952 msgid "" "An example of the usage can be found in the (example) Windows package " "@pkg{windlgs} included in the @R{} source tree. The essential part is" msgstr "" # #. type: group #: R-exts.texi:10958 #, no-wrap msgid "" "#include <R.h>\n" "#include <Rinternals.h>\n" "#include <R_ext/Parse.h>\n" "\n" msgstr "" # #. type: group #: R-exts.texi:10980 #, no-wrap msgid "" "SEXP menu_ttest3()\n" "@{\n" " char cmd[256];\n" " SEXP cmdSexp, cmdexpr, ans = R_NilValue;\n" " ParseStatus status;\n" " ...\n" " if(done == 1) @{\n" "\tcmdSexp = PROTECT(allocVector(STRSXP, 1));\n" "\tSET_STRING_ELT(cmdSexp, 0, mkChar(cmd));\n" "\tcmdexpr = PROTECT(R_ParseVector(cmdSexp, -1, &status, R_NilValue));\n" "\tif (status != PARSE_OK) @{\n" "\t UNPROTECT(2);\n" "\t error(\"invalid call %s\", cmd);\n" "\t@}\n" "\t/* Loop is needed here as EXPSEXP will be of length > 1 */\n" "\tfor(int i = 0; i < length(cmdexpr); i++)\n" "\t ans = eval(VECTOR_ELT(cmdexpr, i), R_GlobalEnv);\n" "\tUNPROTECT(2);\n" " @}\n" " return ans;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:10985 msgid "" "Note that a single line of text may give rise to more than one @R{} " "expression." msgstr "" # #. type: findex #: R-exts.texi:10986 #, no-wrap msgid "R_ParseVector" msgstr "" # #. type: Plain text #: R-exts.texi:11003 msgid "" "@code{R_ParseVector} is essentially the code used to implement " "@code{parse(text=)} at @R{} level. The first argument is a character vector " "(corresponding to @code{text}) and the second the maximal number of " "expressions to parse (corresponding to @code{n}). The third argument is a " "pointer to a variable of an enumeration type, and it is normal (as " "@code{parse} does) to regard all values other than @code{PARSE_OK} as an " "error. Other values which might be returned are @code{PARSE_INCOMPLETE} (an " "incomplete expression was found) and @code{PARSE_ERROR} (a syntax error), in " "both cases the value returned being @code{R_NilValue}. The fourth argument " "is a length one character vector to be used as a filename in error messages, " "a @code{srcfile} object or the @R{} @code{NULL} object (as in the example " "above). If a @code{srcfile} object was used, a @code{srcref} attribute would " "be attached to the result, containing a list of @code{srcref} objects of the " "same length as the expression, to allow it to be echoed with its original " "formatting." msgstr "" # #. type: subsection #: R-exts.texi:11006 #: R-exts.texi:11008 #: R-exts.texi:11009 #, no-wrap msgid "Accessing source references" msgstr "" # #. type: Plain text #: R-exts.texi:11014 msgid "" "The source references added by the parser are recorded by @R{}'s evaluator " "as it evaluates code. Two functions make these available to debuggers " "running C code:" msgstr "" # #. type: findex #: R-exts.texi:11014 #, no-wrap msgid "R_Srcref" msgstr "" # #. type: findex #: R-exts.texi:11015 #, no-wrap msgid "R_GetCurrentSrcref" msgstr "" # #. type: findex #: R-exts.texi:11016 #, no-wrap msgid "R_GetSrcFilename" msgstr "" # #. type: example #: R-exts.texi:11020 #, no-wrap msgid "SEXP R_GetCurrentSrcref(int skip);\n" msgstr "" # #. type: Plain text #: R-exts.texi:11029 msgid "" "This function checks @code{R_Srcref} and the current evaluation stack for " "entries that contain source reference information. The @code{skip} argument " "tells how many source references to skip before returning the @code{SEXP} of " "the @code{srcref} object, counting from the top of the stack. If @code{skip " "< 0}, @code{abs(skip)} locations are counted up from the bottom of the " "stack. If too few or no source references are found, @code{NULL} is returned." msgstr "" # #. type: example #: R-exts.texi:11032 #, no-wrap msgid "SEXP R_GetSrcFilename(SEXP srcref);\n" msgstr "" # #. type: Plain text #: R-exts.texi:11037 msgid "" "This function extracts the filename from the source reference for display, " "returning a length 1 character vector containing the filename. If no name " "is found, @code{\"\"} is returned." msgstr "" # #. type: Plain text #: R-exts.texi:11043 msgid "" "The @code{SEXPTYPE}s @code{EXTPTRSXP} and @code{WEAKREFSXP} can be " "encountered at @R{} level, but are created in C code." msgstr "" # #. type: cindex #: R-exts.texi:11044 #, no-wrap msgid "external pointer" msgstr "" # #. type: Plain text #: R-exts.texi:11052 msgid "" "External pointer @code{SEXP}s are intended to handle references to C " "structures such as `handles', and are used for this purpose in package " "@CRANpkg{RODBC} for example. They are unusual in their copying semantics in " "that when an @R{} object is copied, the external pointer object is not " "duplicated. (For this reason external pointers should only be used as part " "of an object with normal semantics, for example an attribute or an element " "of a list.)" msgstr "" # #. type: Plain text #: R-exts.texi:11054 msgid "An external pointer is created by" msgstr "" # #. type: example #: R-exts.texi:11057 #, no-wrap msgid "SEXP R_MakeExternalPtr(void *p, SEXP tag, SEXP prot);\n" msgstr "" # #. type: Plain text #: R-exts.texi:11069 msgid "" "where @code{p} is the pointer (and hence this cannot portably be a function " "pointer), and @code{tag} and @code{prot} are references to ordinary @R{} " "objects which will remain in existence (be protected from garbage " "collection) for the lifetime of the external pointer object. A useful " "convention is to use the @code{tag} field for some form of type " "identification and the @code{prot} field for protecting the memory that the " "external pointer represents, if that memory is allocated from the @R{} " "heap. Both @code{tag} and @code{prot} can be @code{R_NilValue}, and often " "are." msgstr "" # #. type: Plain text #: R-exts.texi:11071 msgid "The elements of an external pointer can be accessed and set @emph{via}" msgstr "" # #. type: example #: R-exts.texi:11080 #, no-wrap msgid "" "void *R_ExternalPtrAddr(SEXP s);\n" "SEXP R_ExternalPtrTag(SEXP s);\n" "SEXP R_ExternalPtrProtected(SEXP s);\n" "void R_ClearExternalPtr(SEXP s);\n" "void R_SetExternalPtrAddr(SEXP s, void *p);\n" "void R_SetExternalPtrTag(SEXP s, SEXP tag);\n" "void R_SetExternalPtrProtected(SEXP s, SEXP p);\n" msgstr "" # #. type: Plain text #: R-exts.texi:11084 msgid "Clearing a pointer sets its value to the C @code{NULL} pointer." msgstr "" # #. type: cindex #: R-exts.texi:11085 #, no-wrap msgid "finalizer" msgstr "" # #. type: Plain text #: R-exts.texi:11089 msgid "" "An external pointer object can have a @emph{finalizer}, a piece of code to " "be run when the object is garbage collected. This can be @R{} code or C " "code, and the various interfaces are, respectively." msgstr "" # #. type: example #: R-exts.texi:11092 #, no-wrap msgid "" "void R_RegisterFinalizerEx(SEXP s, SEXP fun, Rboolean onexit);\n" "\n" msgstr "" # #. type: example #: R-exts.texi:11095 #, no-wrap msgid "" "typedef void (*R_CFinalizer_t)(SEXP);\n" "void R_RegisterCFinalizerEx(SEXP s, R_CFinalizer_t fun, Rboolean onexit);\n" msgstr "" # #. type: Plain text #: R-exts.texi:11104 msgid "" "The @R{} function indicated by @code{fun} should be a function of a single " "argument, the object to be finalized. @R{} does not perform a garbage " "collection when shutting down, and the @code{onexit} argument of the " "extended forms can be used to ask that the finalizer be run during a normal " "shutdown of the @R{} session. It is suggested that it is good practice to " "clear the pointer on finalization." msgstr "" # #. type: Plain text #: R-exts.texi:11107 msgid "" "The only @R{} level function for interacting with external pointers is " "@code{reg.finalizer} which can be used to set a finalizer." msgstr "" # #. type: Plain text #: R-exts.texi:11111 msgid "" "It is probably not a good idea to allow an external pointer to be @code{save}" "d and then reloaded, but if this happens the pointer will be set to the C " "@code{NULL} pointer." msgstr "" # #. type: Plain text #: R-exts.texi:11117 msgid "" "Finalizers can be run at many places in the code base and much of it, " "including the @R{} interpreter, is not re-entrant. So great care is needed " "in choosing the code to be run in a finalizer. As from @R{} 3.0.3 finalizers " "are marked to be run at garbage collection but only run at a somewhat safe " "point thereafter." msgstr "" # #. type: cindex #: R-exts.texi:11118 #, no-wrap msgid "weak reference" msgstr "" # #. type: Plain text #: R-exts.texi:11122 msgid "" "Weak references are used to allow the programmer to maintain information on " "entities without preventing the garbage collection of the entities once they " "become unreachable." msgstr "" # #. type: Plain text #: R-exts.texi:11128 msgid "" "A weak reference contains a key and a value. The value is reachable is if " "it either reachable directly or @emph{via} weak references with reachable " "keys. Once a value is determined to be unreachable during garbage " "collection, the key and value are set to @code{R_NilValue} and the finalizer " "will be run later in the garbage collection." msgstr "" # #. type: Plain text #: R-exts.texi:11130 msgid "Weak reference objects are created by one of" msgstr "" # #. type: example #: R-exts.texi:11135 #, no-wrap msgid "" "SEXP R_MakeWeakRef(SEXP key, SEXP val, SEXP fin, Rboolean onexit);\n" "SEXP R_MakeWeakRefC(SEXP key, SEXP val, R_CFinalizer_t fin,\n" "\t\t Rboolean onexit);\n" msgstr "" # #. type: Plain text #: R-exts.texi:11141 msgid "" "where the @R{} or C finalizer are specified in exactly the same way as for " "an external pointer object (whose finalization interface is implemented " "@emph{via} weak references)." msgstr "" # #. type: Plain text #: R-exts.texi:11143 msgid "The parts can be accessed @emph{via}" msgstr "" # #. type: example #: R-exts.texi:11148 #, no-wrap msgid "" "SEXP R_WeakRefKey(SEXP w);\n" "SEXP R_WeakRefValue(SEXP w);\n" "void R_RunWeakRefFinalizer(SEXP w);\n" msgstr "" #. type: Plain text #: R-exts.texi:11156 msgid "" "A toy example of the use of weak references can be found at @uref{http://" "homepage.stat.uiowa.edu/~luke/R/references/weakfinex.html, @code{homepage.@/" "stat.@/uiowa.@/edu/@/~luke/@/R/references/@/weakfinex.html}}, but that is " "used to add finalizers to external pointers which can now be done more " "directly. At the time of writing no @acronym{CRAN} or Bioconductor package " "uses weak references." msgstr "" # #. type: node #: R-exts.texi:11160 #: R-exts.texi:11162 #, no-wrap msgid "An external pointer example" msgstr "" # #. type: Plain text #: R-exts.texi:11172 msgid "" "Package @CRANpkg{RODBC} uses external pointers to maintain its " "@emph{channels}, connections to databases. There can be several connections " "open at once, and the status information for each is stored in a C structure " "(pointed to by @code{this_handle}) in the code extract below) that is " "returned @emph{via} an external pointer as part of the RODBC `channel' (as " "the @code{\"handle_ptr\"} attribute). The external pointer is created by" msgstr "" # #. type: example #: R-exts.texi:11187 #, no-wrap msgid "" " SEXP ans, ptr;\n" " ans = PROTECT(allocVector(INTSXP, 1));\n" " ptr = R_MakeExternalPtr(thisHandle, install(\"RODBC_channel\"), R_NilValue);\n" " PROTECT(ptr);\n" " R_RegisterCFinalizerEx(ptr, chanFinalizer, TRUE);\n" "\t ...\n" " /* return the channel no */\n" " INTEGER(ans)[0] = nChannels;\n" " /* and the connection string as an attribute */\n" " setAttrib(ans, install(\"connection.string\"), constr);\n" " setAttrib(ans, install(\"handle_ptr\"), ptr);\n" " UNPROTECT(3);\n" " return ans;\n" msgstr "" #. type: Plain text #: R-exts.texi:11195 msgid "" "Note the symbol given to identify the usage of the external pointer, and the " "use of the finalizer. Since the final argument when registering the " "finalizer is @code{TRUE}, the finalizer will be run at the of the @R{} " "session (unless it crashes). This is used to close and clean up the " "connection to the database. The finalizer code is simply" msgstr "" # #. type: example #: R-exts.texi:11203 #, no-wrap msgid "" "static void chanFinalizer(SEXP ptr)\n" "@{\n" " if(!R_ExternalPtrAddr(ptr)) return;\n" " inRODBCClose(R_ExternalPtrAddr(ptr));\n" " R_ClearExternalPtr(ptr); /* not really needed */\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:11208 msgid "" "Clearing the pointer and checking for a @code{NULL} pointer avoids any " "possibility of attempting to close an already-closed channel." msgstr "" # #. type: Plain text #: R-exts.texi:11212 msgid "" "@R{}'s connections provide another example of using external pointers, in " "that case purely to be able to use a finalizer to close and destroy the " "connection if it is no longer is use." msgstr "" # #. type: Plain text #: R-exts.texi:11221 msgid "" "The vector accessors like @code{REAL} and @code{INTEGER} and " "@code{VECTOR_ELT} are @emph{functions} when used in @R{} extensions. (For " "efficiency they are macros when used in the @R{} source code, apart from " "@code{SET_STRING_ELT} and @code{SET_VECTOR_ELT} which are always functions.)" msgstr "" # #. type: Plain text #: R-exts.texi:11224 msgid "" "The accessor functions check that they are being used on an appropriate type " "of @code{SEXP}." msgstr "" # #. type: Plain text #: R-exts.texi:11233 msgid "" "If efficiency is essential, the macro versions of the accessors can be " "obtained by defining @samp{USE_RINTERNALS} before including @file{Rinternals." "h}. If you find it necessary to do so, please do test that your code " "compiles without @samp{USE_RINTERNALS} defined, as this provides a stricter " "test that the accessors have been used correctly. Note too that the use of " "@samp{USE_RINTERNALS} when the header is included in C++ code is not " "supported: doing so uses C99 features which are not necessarily in C++." msgstr "" # #. type: findex #: R-exts.texi:11237 #, no-wrap msgid "translateChar" msgstr "" # #. type: findex #: R-exts.texi:11238 #, no-wrap msgid "translateCharUTF8" msgstr "" # #. type: Plain text #: R-exts.texi:11250 msgid "" "@code{CHARSXP}s can be marked as coming from a known encoding (Latin-1 or " "UTF-8). This is mainly intended for human-readable output, and most " "packages can just treat such @code{CHARSXP}s as a whole. However, if they " "need to be interpreted as characters or output at C level then it would " "normally be correct to ensure that they are converted to the encoding of the " "current locale: this can be done by accessing the data in the @code{CHARSXP} " "by @code{translateChar} rather than by @code{CHAR}. If re-encoding is " "needed this allocates memory with @code{R_alloc} which thus persists to the " "end of the @code{.Call}/@code{.External} call unless @code{vmaxset} is used " "(@pxref{Transient storage allocation})." msgstr "" # #. type: Plain text #: R-exts.texi:11255 msgid "" "There is a similar function @code{translateCharUTF8} which converts to " "UTF-8: this has the advantage that a faithful translation is almost always " "possible (whereas only a few languages can be represented in the encoding of " "the current locale unless that is UTF-8)." msgstr "" # #. type: findex #: R-exts.texi:11256 #, no-wrap msgid "getCharCE" msgstr "" # #. type: findex #: R-exts.texi:11257 #, no-wrap msgid "mkCharCE" msgstr "" # #. type: Plain text #: R-exts.texi:11260 msgid "" "There is a public interface to the encoding marked on @code{CHARXSXPs} " "@emph{via}" msgstr "" # #. type: example #: R-exts.texi:11265 #, no-wrap msgid "" "typedef enum @{CE_NATIVE, CE_UTF8, CE_LATIN1, CE_SYMBOL, CE_ANY@} cetype_t;\n" "cetype_t getCharCE(SEXP);\n" "SEXP mkCharCE(const char *, cetype_t);\n" msgstr "" # #. type: Plain text #: R-exts.texi:11277 msgid "" "Only @code{CE_UTF8} and @code{CE_LATIN1} are marked on @code{CHARSXPs} (and " "so @code{Rf_getCharCE} will only return one of the first three), and these " "should only be used on non-@acronym{ASCII} strings. Value @code{CE_SYMBOL} " "is used internally to indicate Adobe Symbol encoding. Value @code{CE_ANY} " "is used to indicate a character string that will not need re-encoding -- " "this is used for character strings known to be in @acronym{ASCII}, and can " "also be used as an input parameter where the intention is that the string is " "treated as a series of bytes. (See the comments under @code{mkChar} about " "the length of input allowed.)" msgstr "" # #. type: Plain text #: R-exts.texi:11279 msgid "Function" msgstr "" # #. type: findex #: R-exts.texi:11280 #, no-wrap msgid "reEnc" msgstr "" # #. type: example #: R-exts.texi:11284 #, no-wrap msgid "" "const char *reEnc(const char *x, cetype_t ce_in, cetype_t ce_out,\n" "\t\t int subst);\n" msgstr "" # #. type: Plain text #: R-exts.texi:11294 msgid "" "can be used to re-encode character strings: like @code{translateChar} it " "returns a string allocated by @code{R_alloc}. This can translate from " "@code{CE_SYMBOL} to @code{CE_UTF8}, but not conversely. Argument " "@code{subst} controls what to do with untranslatable characters or invalid " "input: this is done byte-by-byte with @code{1} indicates to output hex of " "the form @code{<a0>}, and @code{2} to replace by @code{.}, with any other " "value causing the byte to produce no output." msgstr "" # #. type: findex #: R-exts.texi:11295 #, no-wrap msgid "mkCharLenCE" msgstr "" # #. type: Plain text #: R-exts.texi:11297 msgid "There is also" msgstr "" # #. type: example #: R-exts.texi:11300 #, no-wrap msgid "SEXP mkCharLenCE(const char *, size_t, cetype_t);\n" msgstr "" # #. type: Plain text #: R-exts.texi:11304 msgid "to create marked character strings of a given length." msgstr "" # #. type: chapter #: R-exts.texi:11307 #, no-wrap msgid "The R @acronym{API}: entry points for C code" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:11398 #: R-exts.texi:11399 #: R-exts.texi:11411 #: R-exts.texi:11504 #: R-exts.texi:11548 #, no-wrap msgid "Memory allocation" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:11398 #: R-exts.texi:11548 #: R-exts.texi:11549 #: R-exts.texi:11589 #: R-exts.texi:11607 #, no-wrap msgid "Error handling" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:11548 #: R-exts.texi:11607 #: R-exts.texi:11664 #, no-wrap msgid "Random numbers" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:11607 #: R-exts.texi:11664 #: R-exts.texi:11709 #, no-wrap msgid "Missing and IEEE values" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:11664 #: R-exts.texi:11709 #: R-exts.texi:11710 #: R-exts.texi:11742 #: R-exts.texi:11772 #, no-wrap msgid "Printing" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:11709 #: R-exts.texi:11772 #: R-exts.texi:11773 #: R-exts.texi:11774 #: R-exts.texi:11845 #, no-wrap msgid "Calling C from FORTRAN and vice versa" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:11772 #: R-exts.texi:11845 #: R-exts.texi:11846 #: R-exts.texi:11872 #: R-exts.texi:11996 #: R-exts.texi:12056 #: R-exts.texi:12181 #: R-exts.texi:12237 #, no-wrap msgid "Numerical analysis subroutines" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:11845 #: R-exts.texi:12237 #: R-exts.texi:12238 #: R-exts.texi:12324 #, no-wrap msgid "Optimization" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:12237 #: R-exts.texi:12324 #: R-exts.texi:12325 #: R-exts.texi:12411 #, no-wrap msgid "Integration" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:12324 #: R-exts.texi:12411 #: R-exts.texi:12412 #: R-exts.texi:12549 #, no-wrap msgid "Utility functions" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:12411 #: R-exts.texi:12549 #: R-exts.texi:12550 #: R-exts.texi:12582 #, no-wrap msgid "Re-encoding" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:12549 #: R-exts.texi:12582 #: R-exts.texi:12583 #: R-exts.texi:12611 #, no-wrap msgid "Allowing interrupts" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:12582 #: R-exts.texi:12611 #: R-exts.texi:12612 #: R-exts.texi:12674 #, no-wrap msgid "Platform and version information" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:12611 #: R-exts.texi:12674 #: R-exts.texi:12675 #: R-exts.texi:12702 #, no-wrap msgid "Inlining C functions" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:12674 #: R-exts.texi:12702 #: R-exts.texi:12703 #: R-exts.texi:12760 #, no-wrap msgid "Controlling visibility" msgstr "" # #. type: node #: R-exts.texi:11327 #: R-exts.texi:12702 #: R-exts.texi:12760 #: R-exts.texi:12811 #, no-wrap msgid "Standalone Mathlib" msgstr "" # #. type: section #: R-exts.texi:11327 #: R-exts.texi:12760 #: R-exts.texi:12811 #: R-exts.texi:12812 #, no-wrap msgid "Organization of header files" msgstr "" # #. type: Plain text #: R-exts.texi:11333 msgid "" "There are a large number of entry points in the @R{} executable/DLL that can " "be called from C code (and some that can be called from FORTRAN code). Only " "those documented here are stable enough that they will only be changed with " "considerable notice." msgstr "" # #. type: Plain text #: R-exts.texi:11336 msgid "" "The recommended procedure to use these is to include the header file @file{R." "h} in your C code by" msgstr "" # #. type: example #: R-exts.texi:11339 #, no-wrap msgid "#include <R.h>\n" msgstr "" # #. type: Plain text #: R-exts.texi:11346 msgid "" "This will include several other header files from the directory " "@file{@var{R_INCLUDE_DIR}/R_ext}, and there are other header files there " "that can be included too, but many of the features they contain should be " "regarded as undocumented and unstable." msgstr "" # #. type: Plain text #: R-exts.texi:11351 msgid "" "An alternative is to include the header file @file{S.h}, which may be useful " "when porting code from @Sl{}. This includes rather less than @file{R.h}, " "and has some extra compatibility definitions (for example the " "@code{S_complex} type from @Sl{})." msgstr "" # #. type: Plain text #: R-exts.texi:11355 msgid "" "The defines used for compatibility with @Sl{} sometimes causes conflicts " "(notably with Windows headers), and the known problematic defines can be " "removed by defining @code{STRICT_R_HEADERS}." msgstr "" # #. type: Plain text #: R-exts.texi:11360 msgid "" "Most of these header files, including all those included by @file{R.h}, can " "be used from C++ code. Some others need to be included within an " "@code{extern \"C\"} declaration, and for clarity this is advisable for all " "@R{} header files." msgstr "" # #. type: quotation #: R-exts.texi:11365 msgid "" "Because @R{} re-maps many of its external names to avoid clashes with user " "code, it is @emph{essential} to include the appropriate header files when " "using these entry points." msgstr "" # #. type: Plain text #: R-exts.texi:11374 msgid "" "This remapping can cause problems@footnote{Known problems are redefining " "@code{LENGTH}, @code{error}, @code{length}, @code{vector} and " "@code{warning}}, and can be eliminated by defining @code{R_NO_REMAP} and " "prepending @samp{Rf_} to @emph{all} the function names used from " "@file{Rinternals.h} and @file{R_ext/Error.h}. These problems can usually be " "avoided by including other headers (such as system headers and those for " "external software used by the package) before @file{R.h}." msgstr "" # #. type: Plain text #: R-exts.texi:11376 msgid "We can classify the entry points as" msgstr "" # #. type: item #: R-exts.texi:11378 #, no-wrap msgid "API" msgstr "" # #. type: table #: R-exts.texi:11382 msgid "" "Entry points which are documented in this manual and declared in an " "installed header file. These can be used in distributed packages and will " "only be changed after deprecation." msgstr "" # #. type: item #: R-exts.texi:11383 #, no-wrap msgid "public" msgstr "" # #. type: table #: R-exts.texi:11387 msgid "" "Entry points declared in an installed header file that are exported on all " "@R{} platforms but are not documented and subject to change without notice." msgstr "" # #. type: item #: R-exts.texi:11388 #, no-wrap msgid "private" msgstr "" # #. type: table #: R-exts.texi:11392 msgid "" "Entry points that are used when building @R{} and exported on all @R{} " "platforms but are not declared in the installed header files. Do not use " "these in distributed code." msgstr "" # #. type: item #: R-exts.texi:11393 #, no-wrap msgid "hidden" msgstr "" # #. type: table #: R-exts.texi:11396 msgid "" "Entry points that are where possible (Windows and some modern Unix-alike " "compilers/loaders when using @R{} as a shared library) not exported." msgstr "" # #. type: cindex #: R-exts.texi:11400 #, no-wrap msgid "Memory allocation from C" msgstr "" # #. type: node #: R-exts.texi:11405 #: R-exts.texi:11411 #: R-exts.texi:11412 #: R-exts.texi:11504 #, no-wrap msgid "Transient storage allocation" msgstr "" # #. type: subsection #: R-exts.texi:11405 #: R-exts.texi:11411 #: R-exts.texi:11504 #: R-exts.texi:11505 #, no-wrap msgid "User-controlled memory" msgstr "" # #. type: Plain text #: R-exts.texi:11410 msgid "" "There are two types of memory allocation available to the C programmer, one " "in which @R{} manages the clean-up and the other in which user has full " "control (and responsibility)." msgstr "" # #. type: findex #: R-exts.texi:11413 #, no-wrap msgid "R_alloc" msgstr "" # #. type: findex #: R-exts.texi:11414 #, no-wrap msgid "R_allocLD" msgstr "" # #. type: findex #: R-exts.texi:11415 #, no-wrap msgid "S_alloc" msgstr "" # #. type: findex #: R-exts.texi:11416 #, no-wrap msgid "S_realloc" msgstr "" # #. type: findex #: R-exts.texi:11417 #, no-wrap msgid "vmaxget" msgstr "" # #. type: findex #: R-exts.texi:11418 #, no-wrap msgid "vmaxset" msgstr "" # #. type: Plain text #: R-exts.texi:11422 msgid "" "Here @R{} will reclaim the memory at the end of the call to @code{.C}, " "@code{.Call} or @code{.External}. Use" msgstr "" # #. type: example #: R-exts.texi:11425 #, no-wrap msgid "char *R_alloc(size_t @var{n}, int @var{size})\n" msgstr "" # #. type: Plain text #: R-exts.texi:11430 msgid "" "which allocates @var{n} units of @var{size} bytes each. A typical usage " "(from package @pkg{stats}) is" msgstr "" # #. type: example #: R-exts.texi:11433 #, no-wrap msgid "x = (int *) R_alloc(nrows(merge)+2, sizeof(int));\n" msgstr "" # #. type: Plain text #: R-exts.texi:11438 msgid "" "(@code{size_t} is defined in @file{stddef.h} which the header defining " "@code{R_alloc} includes.)" msgstr "" # #. type: Plain text #: R-exts.texi:11441 msgid "" "There is a similar call, @code{S_alloc} (for compatibility with older " "versions of @Sl{}) which zeroes the memory allocated," msgstr "" # #. type: example #: R-exts.texi:11444 #, no-wrap msgid "char *S_alloc(long @var{n}, int @var{size})\n" msgstr "" # #. type: example #: R-exts.texi:11451 #, no-wrap msgid "char *S_realloc(char *@var{p}, long @var{new}, long @var{old}, int @var{size})\n" msgstr "" # #. type: Plain text #: R-exts.texi:11456 msgid "" "which changes the allocation size from @var{old} to @var{new} units, and " "zeroes the additional units." msgstr "" # #. type: Plain text #: R-exts.texi:11459 msgid "" "For compatibility with current versions of @Sl{}, header @file{S.h} (only) " "defines wrapper macros equivalent to" msgstr "" # #. type: example #: R-exts.texi:11463 #, no-wrap msgid "" "type* Salloc(long @var{n}, int @var{type})\n" "type* Srealloc(char *@var{p}, long @var{new}, long @var{old}, int @var{type})\n" msgstr "" # #. type: Plain text #: R-exts.texi:11470 msgid "" "This memory is taken from the heap, and released at the end of the @code{." "C}, @code{.Call} or @code{.External} call. Users can also manage it, by " "noting the current position with a call to @code{vmaxget} and subsequently " "clearing memory allocated by a call to @code{vmaxset}. An example might be" msgstr "" # #. type: example #: R-exts.texi:11475 #, no-wrap msgid "" "void *vmax = vmaxget()\n" "// a loop involving the use of R_alloc at each iteration\n" "vmaxset(vmax)\n" msgstr "" # #. type: Plain text #: R-exts.texi:11479 msgid "This is only recommended for experts." msgstr "" # #. type: Plain text #: R-exts.texi:11482 msgid "" "Note that this memory will be freed on error or user interrupt (if allowed: " "@pxref{Allowing interrupts})." msgstr "" # #. type: Plain text #: R-exts.texi:11487 msgid "" "Note that although @var{n} is @code{size_t}, there may be limits imposed by " "@R{}'s internal allocation mechanism. These will only come into play on 64-" "bit systems, where the limit for @var{n} prior to @R{} 3.0.0 was just under " "16Gb." msgstr "" #. type: Plain text #: R-exts.texi:11491 msgid "" "The memory returned is only guaranteed to be aligned as required for " "@code{double} pointers: take precautions if casting to a pointer which needs " "more. As from @R{} 3.2.0 there is also" msgstr "" # #. type: example #: R-exts.texi:11494 #, no-wrap msgid "long double *R_allocLD(size_t @var{n})\n" msgstr "" # #. type: Plain text #: R-exts.texi:11499 msgid "" "which is guaranteed to have the 16-byte alignment needed for @code{long " "double} pointers on some platforms." msgstr "" # #. type: Plain text #: R-exts.texi:11503 msgid "" "These functions should only be used in code called by @code{.C} etc, never " "from front-ends. They are not thread-safe." msgstr "" # #. type: findex #: R-exts.texi:11506 #, no-wrap msgid "Calloc" msgstr "" # #. type: findex #: R-exts.texi:11507 #, no-wrap msgid "Realloc" msgstr "" # #. type: findex #: R-exts.texi:11508 #, no-wrap msgid "Free" msgstr "" # #. type: Plain text #: R-exts.texi:11514 msgid "" "The other form of memory allocation is an interface to @code{malloc}, the " "interface providing @R{} error handling. This memory lasts until freed by " "the user and is additional to the memory allocated for the @R{} workspace." msgstr "" # #. type: Plain text #: R-exts.texi:11516 msgid "The interface functions are" msgstr "" # #. type: group #: R-exts.texi:11522 #, no-wrap msgid "" "@var{type}* Calloc(size_t @var{n}, @var{type})\n" "@var{type}* Realloc(@var{any} *@var{p}, size_t @var{n}, @var{type})\n" "void Free(@var{any} *@var{p})\n" msgstr "" # #. type: Plain text #: R-exts.texi:11531 msgid "" "providing analogues of @code{calloc}, @code{realloc} and @code{free}. If " "there is an error during allocation it is handled by @R{}, so if these " "routines return the memory has been successfully allocated or freed. " "@code{Free} will set the pointer @var{p} to @code{NULL}. (Some but not all " "versions of @Sl{} do so.)" msgstr "" # #. type: Plain text #: R-exts.texi:11536 msgid "" "Users should arrange to @code{Free} this memory when no longer needed, " "including on error or user interrupt. This can often be done most " "conveniently from an @code{on.exit} action in the calling @R{} function -- " "see @code{pwilcox} for an example." msgstr "" # #. type: Plain text #: R-exts.texi:11540 msgid "" "Do not assume that memory allocated by @code{Calloc}/@code{Realloc} comes " "from the same pool as used by @code{malloc}: in particular do not use " "@code{free} or @code{strdup} with it." msgstr "" # #. type: Plain text #: R-exts.texi:11543 msgid "" "Memory obtained by these functions should be aligned in the same way as " "@code{malloc}, that is `suitably aligned for any kind of variable'." msgstr "" # #. type: Plain text #: R-exts.texi:11546 msgid "" "These entry points need to be prefixed by @code{R_} if " "@code{STRICT_R_HEADERS} has been defined." msgstr "" # #. type: cindex #: R-exts.texi:11550 #, no-wrap msgid "Error handling from C" msgstr "" # #. type: Plain text #: R-exts.texi:11554 msgid "" "The basic error handling routines are the equivalents of @code{stop} and " "@code{warning} in @R{} code, and use the same interface." msgstr "" # #. type: group #: R-exts.texi:11559 #, no-wrap msgid "" "void error(const char * @var{format}, ...);\n" "void warning(const char * @var{format}, ...);\n" msgstr "" # #. type: Plain text #: R-exts.texi:11567 msgid "" "These have the same call sequences as calls to @code{printf}, but in the " "simplest case can be called with a single character string argument giving " "the error message. (Don't do this if the string contains @samp{%} or might " "otherwise be interpreted as a format.)" msgstr "" # #. type: Plain text #: R-exts.texi:11570 msgid "" "If @code{STRICT_R_HEADERS} is not defined there is also an @Sl{}-" "compatibility interface which uses calls of the form" msgstr "" # #. type: group #: R-exts.texi:11577 #, no-wrap msgid "" "PROBLEM ...... ERROR\n" "MESSAGE ...... WARN\n" "PROBLEM ...... RECOVER(NULL_ENTRY)\n" "MESSAGE ...... WARNING(NULL_ENTRY)\n" msgstr "" # #. type: Plain text #: R-exts.texi:11584 msgid "" "the last two being the forms available in all @Sl{} versions. Here " "@samp{......} is a set of arguments to @code{printf}, so can be a string or " "a format string followed by arguments separated by commas." msgstr "" # #. type: cindex #: R-exts.texi:11587 #: R-exts.texi:11589 #: R-exts.texi:11590 #: R-exts.texi:11591 #, no-wrap msgid "Error handling from FORTRAN" msgstr "" # #. type: Plain text #: R-exts.texi:11596 msgid "" "There are two interface function provided to call @code{error} and " "@code{warning} from FORTRAN code, in each case with a simple character " "string argument. They are defined as" msgstr "" # #. type: group #: R-exts.texi:11601 #, no-wrap msgid "" "subroutine rexit(@var{message})\n" "subroutine rwarn(@var{message})\n" msgstr "" # #. type: Plain text #: R-exts.texi:11605 msgid "Messages of more than 255 characters are truncated, with a warning." msgstr "" # #. type: section #: R-exts.texi:11608 #, no-wrap msgid "Random number generation" msgstr "" # #. type: cindex #: R-exts.texi:11609 #: R-exts.texi:11920 #, no-wrap msgid "Random numbers in C" msgstr "" # #. type: findex #: R-exts.texi:11610 #, no-wrap msgid "unif_rand" msgstr "" # #. type: findex #: R-exts.texi:11611 #, no-wrap msgid "norm_rand" msgstr "" # #. type: findex #: R-exts.texi:11612 #, no-wrap msgid "exp_rand" msgstr "" # #. type: findex #: R-exts.texi:11613 #, no-wrap msgid "GetRNGstate" msgstr "" # #. type: findex #: R-exts.texi:11614 #, no-wrap msgid "PutRNGstate" msgstr "" # #. type: findex #: R-exts.texi:11615 #, no-wrap msgid ".Random.seed" msgstr "" # #. type: findex #: R-exts.texi:11616 #, no-wrap msgid "seed_in" msgstr "" # #. type: findex #: R-exts.texi:11617 #, no-wrap msgid "seed_out" msgstr "" # #. type: Plain text #: R-exts.texi:11620 msgid "The interface to @R{}'s internal random number generation routines is" msgstr "" # #. type: group #: R-exts.texi:11626 #, no-wrap msgid "" "double unif_rand();\n" "double norm_rand();\n" "double exp_rand();\n" msgstr "" # #. type: Plain text #: R-exts.texi:11632 msgid "" "giving one uniform, normal or exponential pseudo-random variate. However, " "before these are used, the user must call" msgstr "" # #. type: example #: R-exts.texi:11635 #, no-wrap msgid "GetRNGstate();\n" msgstr "" # #. type: Plain text #: R-exts.texi:11639 msgid "and after all the required variates have been generated, call" msgstr "" # #. type: example #: R-exts.texi:11642 #, no-wrap msgid "PutRNGstate();\n" msgstr "" # #. type: Plain text #: R-exts.texi:11647 msgid "" "These essentially read in (or create) @code{.Random.seed} and write it out " "after use." msgstr "" # #. type: Plain text #: R-exts.texi:11652 msgid "" "File @file{S.h} defines @code{seed_in} and @code{seed_out} for @Sl{}-" "compatibility rather than @code{GetRNGstate} and @code{PutRNGstate}. These " "take a @code{long *} argument which is ignored." msgstr "" # #. type: Plain text #: R-exts.texi:11656 msgid "" "The random number generator is private to @R{}; there is no way to select " "the kind of RNG or set the seed except by evaluating calls to the @R{} " "functions." msgstr "" # #. type: Plain text #: R-exts.texi:11661 msgid "" "The C code behind @R{}'s @code{r@var{xxx}} functions can be accessed by " "including the header file @file{Rmath.h}; @xref{Distribution functions}. " "Those calls generate a single variate and should also be enclosed in calls " "to @code{GetRNGstate} and @code{PutRNGstate}." msgstr "" # #. type: section #: R-exts.texi:11665 #, no-wrap msgid "Missing and @acronym{IEEE} special values" msgstr "" # #. type: findex #: R-exts.texi:11670 #, no-wrap msgid "R_FINITE" msgstr "" # #. type: findex #: R-exts.texi:11671 #, no-wrap msgid "R_IsNaN" msgstr "" # #. type: findex #: R-exts.texi:11672 #, no-wrap msgid "R_PosInf" msgstr "" # #. type: findex #: R-exts.texi:11673 #, no-wrap msgid "R_NegInf" msgstr "" # #. type: findex #: R-exts.texi:11674 #, no-wrap msgid "NA_REAL" msgstr "" # #. type: Plain text #: R-exts.texi:11678 msgid "" "A set of functions is provided to test for @code{NA}, @code{Inf}, @code{-" "Inf} and @code{NaN}. These functions are accessed @emph{via} macros:" msgstr "" # #. type: group #: R-exts.texi:11684 #, no-wrap msgid "" "ISNA(@var{x}) @r{True for R's @code{NA} only}\n" "ISNAN(@var{x}) @r{True for R's @code{NA} and @acronym{IEEE} @code{NaN}}\n" "R_FINITE(@var{x}) @r{False for @code{Inf}, @code{-Inf}, @code{NA}, @code{NaN}}\n" msgstr "" # #. type: Plain text #: R-exts.texi:11690 msgid "" "and @emph{via} function @code{R_IsNaN} which is true for @code{NaN} but not " "@code{NA}." msgstr "" # #. type: Plain text #: R-exts.texi:11695 msgid "" "Do use @code{R_FINITE} rather than @code{isfinite} or @code{finite}; the " "latter is often mendacious and @code{isfinite} is only available on a some " "platforms, on which @code{R_FINITE} is a macro expanding to @code{isfinite}." msgstr "" # #. type: Plain text #: R-exts.texi:11699 msgid "" "Currently in C code @code{ISNAN} is a macro calling @code{isnan}. (Since " "this gives problems on some C++ systems, if the @R{} headers is called from C" "++ code a function call is used.)" msgstr "" # #. type: Plain text #: R-exts.texi:11703 msgid "" "You can check for @code{Inf} or @code{-Inf} by testing equality to " "@code{R_PosInf} or @code{R_NegInf}, and set (but not test) an @code{NA} as " "@code{NA_REAL}." msgstr "" # #. type: Plain text #: R-exts.texi:11707 msgid "" "All of the above apply to @emph{double} variables only. For integer " "variables there is a variable accessed by the macro @code{NA_INTEGER} which " "can used to set or test for missingness." msgstr "" # #. type: cindex #: R-exts.texi:11711 #, no-wrap msgid "Printing from C" msgstr "" # #. type: findex #: R-exts.texi:11712 #, no-wrap msgid "Rprintf" msgstr "" # #. type: findex #: R-exts.texi:11713 #, no-wrap msgid "REprintf" msgstr "" # #. type: findex #: R-exts.texi:11714 #, no-wrap msgid "Rvprintf" msgstr "" # #. type: findex #: R-exts.texi:11715 #, no-wrap msgid "REvprintf" msgstr "" # #. type: Plain text #: R-exts.texi:11724 msgid "" "The most useful function for printing from a C routine compiled into @R{} is " "@code{Rprintf}. This is used in exactly the same way as @code{printf}, but " "is guaranteed to write to @R{}'s output (which might be a @acronym{GUI} " "console rather than a file, and can be re-directed by @code{sink}). It is " "wise to write complete lines (including the @code{\"\\n\"}) before returning " "to @R{}. It is defined in @file{R_ext/Print.h}." msgstr "" # #. type: Plain text #: R-exts.texi:11728 msgid "" "The function @code{REprintf} is similar but writes on the error stream " "(@code{stderr}) which may or may not be different from the standard output " "stream." msgstr "" # #. type: Plain text #: R-exts.texi:11733 msgid "" "Functions @code{Rvprintf} and @code{REvprintf} are analogues using the " "@code{vprintf} interface. Because that is a C99 interface, they are only " "defined by @file{R_ext/Print.h} in C++ code if the macro " "@code{R_USE_C99_IN_CXX} is defined when it is included." msgstr "" # #. type: Plain text #: R-exts.texi:11737 msgid "" "Another circumstance when it may be important to use these functions is when " "using parallel computation on a cluster of computational nodes, as their " "output will be re-directed/logged appropriately." msgstr "" # #. type: cindex #: R-exts.texi:11740 #: R-exts.texi:11742 #: R-exts.texi:11743 #: R-exts.texi:11744 #, no-wrap msgid "Printing from FORTRAN" msgstr "" # #. type: Plain text #: R-exts.texi:11750 msgid "" "On many systems FORTRAN @code{write} and @code{print} statements can be " "used, but the output may not interleave well with that of C, and will be " "invisible on @acronym{GUI} interfaces. They are not portable and best " "avoided." msgstr "" # #. type: Plain text #: R-exts.texi:11753 msgid "" "Three subroutines are provided to ease the output of information from " "FORTRAN code." msgstr "" # #. type: group #: R-exts.texi:11759 #, no-wrap msgid "" "subroutine dblepr(@var{label}, @var{nchar}, @var{data}, @var{ndata})\n" "subroutine realpr(@var{label}, @var{nchar}, @var{data}, @var{ndata})\n" "subroutine intpr (@var{label}, @var{nchar}, @var{data}, @var{ndata})\n" msgstr "" # #. type: Plain text #: R-exts.texi:11771 msgid "" "Here @var{label} is a character label of up to 255 characters, @var{nchar} " "is its length (which can be @code{-1} if the whole label is to be used), and " "@var{data} is an array of length at least @var{ndata} of the appropriate " "type (@code{double precision}, @code{real} and @code{integer} " "respectively). These routines print the label on one line and then print " "@var{data} as if it were an @R{} vector on subsequent line(s). They work " "with zero @var{ndata}, and so can be used to print a label alone." msgstr "" # #. type: Plain text #: R-exts.texi:11780 msgid "" "Naming conventions for symbols generated by FORTRAN differ by platform: it " "is not safe to assume that FORTRAN names appear to C with a trailing " "underscore. To help cover up the platform-specific differences there is a " "set of macros that should be used." msgstr "" # #. type: item #: R-exts.texi:11782 #, no-wrap msgid "F77_SUB(@var{name})" msgstr "" # #. type: table #: R-exts.texi:11784 msgid "to define a function in C to be called from FORTRAN" msgstr "" # #. type: item #: R-exts.texi:11784 #, no-wrap msgid "F77_NAME(@var{name})" msgstr "" # #. type: table #: R-exts.texi:11786 msgid "to declare a FORTRAN routine in C before use" msgstr "" # #. type: item #: R-exts.texi:11786 #, no-wrap msgid "F77_CALL(@var{name})" msgstr "" # #. type: table #: R-exts.texi:11788 msgid "to call a FORTRAN routine from C" msgstr "" # #. type: item #: R-exts.texi:11788 #, no-wrap msgid "F77_COMDECL(@var{name})" msgstr "" # #. type: table #: R-exts.texi:11790 msgid "to declare a FORTRAN common block in C" msgstr "" # #. type: item #: R-exts.texi:11790 #, no-wrap msgid "F77_COM(@var{name})" msgstr "" # #. type: table #: R-exts.texi:11792 msgid "to access a FORTRAN common block from C" msgstr "" # #. type: Plain text #: R-exts.texi:11799 msgid "" "On most current platforms these are all the same, but it is unwise to rely " "on this. Note that names with underscores are not legal in FORTRAN 77, and " "are not portably handled by the above macros. (Also, all FORTRAN names for " "use by @R{} are lower case, but this is not enforced by the macros.)" msgstr "" # #. type: Plain text #: R-exts.texi:11802 msgid "" "For example, suppose we want to call R's normal random numbers from " "FORTRAN. We need a C wrapper along the lines of" msgstr "" # #. type: cindex #: R-exts.texi:11803 #, no-wrap msgid "Random numbers in FORTRAN" msgstr "" # #. type: example #: R-exts.texi:11807 #: R-exts.texi:12686 #, no-wrap msgid "" "#include <R.h>\n" "\n" msgstr "" # #. type: group #: R-exts.texi:11811 #, no-wrap msgid "" "void F77_SUB(rndstart)(void) @{ GetRNGstate(); @}\n" "void F77_SUB(rndend)(void) @{ PutRNGstate(); @}\n" "double F77_SUB(normrnd)(void) @{ return norm_rand(); @}\n" msgstr "" # #. type: Plain text #: R-exts.texi:11816 msgid "to be called from FORTRAN as in" msgstr "" # #. type: group #: R-exts.texi:11826 #, no-wrap msgid "" " subroutine testit()\n" " double precision normrnd, x\n" " call rndstart()\n" " x = normrnd()\n" " call dblepr(\"X was\", 5, x, 1)\n" " call rndend()\n" " end\n" msgstr "" # #. type: Plain text #: R-exts.texi:11833 msgid "" "Note that this is not guaranteed to be portable, for the return conventions " "might not be compatible between the C and FORTRAN compilers used. (Passing " "values @emph{via} arguments is safer.)" msgstr "" # #. type: Plain text #: R-exts.texi:11836 msgid "" "The standard packages, for example @pkg{stats}, are a rich source of further " "examples." msgstr "" # #. type: Plain text #: R-exts.texi:11843 msgid "" "Passing character strings from C to FORTRAN 77 or @emph{vice versa} is not " "portable (and to Fortran 90 or later is even less so). We have found that " "it helps to ensure that a C string to be passed is followed by several " "@code{nul}s (and not just the one needed as a C terminator). But for " "maximal portability character strings in FORTRAN should be avoided." msgstr "" # #. type: cindex #: R-exts.texi:11847 #, no-wrap msgid "Numerical analysis subroutines from C" msgstr "" # #. type: Plain text #: R-exts.texi:11851 msgid "" "@R{} contains a large number of mathematical functions for its own use, for " "example numerical linear algebra computations and special functions." msgstr "" # #. type: Plain text #: R-exts.texi:11859 msgid "" "The header files @file{R_ext/BLAS.h}, @file{R_ext/Lapack.h} and @file{R_ext/" "Linpack.h} contains declarations of the BLAS, LAPACK and LINPACK linear " "algebra functions included in @R{}. These are expressed as calls to FORTRAN " "subroutines, and they will also be usable from users' FORTRAN code. " "Although not part of the official @acronym{API}, this set of subroutines is " "unlikely to change (but might be supplemented)." msgstr "" # #. type: Plain text #: R-exts.texi:11864 msgid "" "The header file @file{Rmath.h} lists many other functions that are available " "and documented in the following subsections. Many of these are C interfaces " "to the code behind @R{} functions, so the @R{} function documentation may " "give further details." msgstr "" # #. type: node #: R-exts.texi:11870 #: R-exts.texi:11872 #: R-exts.texi:11873 #: R-exts.texi:11996 #, no-wrap msgid "Distribution functions" msgstr "" # #. type: node #: R-exts.texi:11870 #: R-exts.texi:11872 #: R-exts.texi:11996 #: R-exts.texi:11997 #: R-exts.texi:12056 #, no-wrap msgid "Mathematical functions" msgstr "" # #. type: node #: R-exts.texi:11870 #: R-exts.texi:11996 #: R-exts.texi:12056 #: R-exts.texi:12057 #: R-exts.texi:12181 #, no-wrap msgid "Numerical Utilities" msgstr "" # #. type: subsection #: R-exts.texi:11870 #: R-exts.texi:12056 #: R-exts.texi:12181 #: R-exts.texi:12182 #, no-wrap msgid "Mathematical constants" msgstr "" # #. type: cindex #: R-exts.texi:11874 #, no-wrap msgid "Distribution functions from C" msgstr "" # #. type: Plain text #: R-exts.texi:11879 msgid "" "The routines used to calculate densities, cumulative distribution functions " "and quantile functions for the standard statistical distributions are " "available as entry points." msgstr "" # #. type: Plain text #: R-exts.texi:11882 msgid "" "The arguments for the entry points follow the pattern of those for the " "normal distribution:" msgstr "" # #. type: group #: R-exts.texi:11891 #, no-wrap msgid "" "double dnorm(double @var{x}, double @var{mu}, double @var{sigma}, int @var{give_log});\n" "double pnorm(double @var{x}, double @var{mu}, double @var{sigma}, int @var{lower_tail},\n" "\t int @var{give_log});\n" "double qnorm(double @var{p}, double @var{mu}, double @var{sigma}, int @var{lower_tail},\n" "\t int @var{log_p});\n" "double rnorm(double @var{mu}, double @var{sigma});\n" msgstr "" # #. type: Plain text #: R-exts.texi:11900 msgid "" "That is, the first argument gives the position for the density and CDF and " "probability for the quantile function, followed by the distribution's " "parameters. Argument @var{lower_tail} should be @code{TRUE} (or @code{1}) " "for normal use, but can be @code{FALSE} (or @code{0}) if the probability of " "the upper tail is desired or specified." msgstr "" # #. type: Plain text #: R-exts.texi:11904 msgid "" "Finally, @var{give_log} should be non-zero if the result is required on log " "scale, and @var{log_p} should be non-zero if @var{p} has been specified on " "log scale." msgstr "" # #. type: Plain text #: R-exts.texi:11908 msgid "" "Note that you directly get the cumulative (or ``integrated'') @emph{hazard} " "function, @eqn{H(t) = - \\log(1 - F(t)), H(t) = - log(1 - F(t))}, by using" msgstr "" # #. type: example #: R-exts.texi:11911 #, no-wrap msgid "- p@var{dist}(t, ..., /*lower_tail = */ FALSE, /* give_log = */ TRUE)\n" msgstr "" # #. type: Plain text #: R-exts.texi:11915 msgid "or shorter (and more cryptic) @code{- p@var{dist}(t, ..., 0, 1)}." msgstr "" # #. type: cindex #: R-exts.texi:11915 #, no-wrap msgid "cumulative hazard" msgstr "" # #. type: Plain text #: R-exts.texi:11920 msgid "" "The random-variate generation routine @code{rnorm} returns one normal " "variate. @xref{Random numbers}, for the protocol in using the random-variate " "routines." msgstr "" # #. type: Plain text #: R-exts.texi:11927 msgid "" "Note that these argument sequences are (apart from the names and that " "@code{rnorm} has no @var{n}) mainly the same as the corresponding @R{} " "functions of the same name, so the documentation of the @R{} functions can " "be used. Note that the exponential and gamma distributions are parametrized " "by @code{scale} rather than @code{rate}." msgstr "" # #. type: Plain text #: R-exts.texi:11933 msgid "" "For reference, the following table gives the basic name (to be prefixed by " "@samp{d}, @samp{p}, @samp{q} or @samp{r} apart from the exceptions noted) " "and distribution-specific arguments for the complete set of distributions." msgstr "" # #. type: item #: R-exts.texi:11936 #, no-wrap msgid "beta @tab @code{beta} @tab @code{a}, @code{b}" msgstr "" # #. type: item #: R-exts.texi:11937 #, no-wrap msgid "non-central beta @tab @code{nbeta} @tab @code{a}, @code{b}, @code{ncp}" msgstr "" # #. type: item #: R-exts.texi:11939 #, no-wrap msgid "binomial @tab @code{binom} @tab @code{n}, @code{p}" msgstr "" # #. type: item #: R-exts.texi:11940 #, no-wrap msgid "Cauchy @tab @code{cauchy} @tab @code{location}, @code{scale}" msgstr "" # #. type: item #: R-exts.texi:11941 #, no-wrap msgid "chi-squared @tab @code{chisq} @tab @code{df}" msgstr "" # #. type: item #: R-exts.texi:11942 #, no-wrap msgid "non-central chi-squared @tab @code{nchisq} @tab @code{df}, @code{ncp}" msgstr "" # #. type: item #: R-exts.texi:11943 #, no-wrap msgid "exponential @tab @code{exp} @tab @code{scale} (and @strong{not} @code{rate})" msgstr "" # #. type: item #: R-exts.texi:11944 #, no-wrap msgid "F @tab @code{f} @tab @code{n1}, @code{n2}" msgstr "" # #. type: item #: R-exts.texi:11945 #, no-wrap msgid "non-central F @tab @code{nf} @tab @code{n1}, @code{n2}, @code{ncp}" msgstr "" # #. type: item #: R-exts.texi:11946 #, no-wrap msgid "gamma @tab @code{gamma} @tab @code{shape}, @code{scale}" msgstr "" # #. type: item #: R-exts.texi:11947 #, no-wrap msgid "geometric @tab @code{geom} @tab @code{p}" msgstr "" # #. type: item #: R-exts.texi:11948 #, no-wrap msgid "hypergeometric @tab @code{hyper} @tab @code{NR}, @code{NB}, @code{n}" msgstr "" # #. type: item #: R-exts.texi:11950 #, no-wrap msgid "logistic @tab @code{logis} @tab @code{location}, @code{scale}" msgstr "" # #. type: item #: R-exts.texi:11951 #, no-wrap msgid "lognormal @tab @code{lnorm} @tab @code{logmean}, @code{logsd}" msgstr "" # #. type: item #: R-exts.texi:11952 #, no-wrap msgid "negative binomial @tab @code{nbinom} @tab @code{size}, @code{prob}" msgstr "" # #. type: item #: R-exts.texi:11953 #, no-wrap msgid "normal @tab @code{norm} @tab @code{mu}, @code{sigma}" msgstr "" # #. type: item #: R-exts.texi:11954 #, no-wrap msgid "Poisson @tab @code{pois} @tab @code{lambda}" msgstr "" # #. type: item #: R-exts.texi:11955 #, no-wrap msgid "Student's t @tab @code{t} @tab @code{n}" msgstr "" # #. type: item #: R-exts.texi:11956 #, no-wrap msgid "non-central t @tab @code{nt} @tab @code{df}, @code{delta}" msgstr "" # #. type: item #: R-exts.texi:11957 #, no-wrap msgid "Studentized range @tab @code{tukey} (*) @tab @code{rr}, @code{cc}, @code{df}" msgstr "" # #. type: item #: R-exts.texi:11959 #, no-wrap msgid "uniform @tab @code{unif} @tab @code{a}, @code{b}" msgstr "" # #. type: item #: R-exts.texi:11961 #, no-wrap msgid "Weibull @tab @code{weibull} @tab @code{shape}, @code{scale}" msgstr "" # #. type: item #: R-exts.texi:11962 #, no-wrap msgid "Wilcoxon rank sum @tab @code{wilcox} @tab @code{m}, @code{n}" msgstr "" # #. type: item #: R-exts.texi:11963 #, no-wrap msgid "Wilcoxon signed rank @tab @code{signrank} @tab @code{n}" msgstr "" # #. type: Plain text #: R-exts.texi:11973 msgid "" "Entries marked with an asterisk only have @samp{p} and @samp{q} functions " "available, and none of the non-central distributions have @samp{r} " "functions. After a call to @code{dwilcox}, @code{pwilcox} or @code{qwilcox} " "the function @code{wilcox_free()} should be called, and similarly for the " "signed rank functions." msgstr "" # #. type: Plain text #: R-exts.texi:11976 msgid "" "(If remapping is suppressed, the Normal distribution names are " "@code{Rf_dnorm4}, @code{Rf_pnorm5} and @code{Rf_qnorm5}.)" msgstr "" # #. type: Plain text #: R-exts.texi:11981 msgid "" "For the negative binomial distribution (@samp{nbinom}), in addition to the " "@code{(size, prob)} parametrization, the alternative @code{(size, mu)} " "parametrization is provided as well by functions @samp{[dpqr]nbinom_mu()}, " "see @kbd{?NegBinomial} in @R{}." msgstr "" # #. type: Plain text #: R-exts.texi:11986 msgid "" "Functions @code{dpois_raw(x, *)} and @code{dbinom_raw(x, *)} are versions of " "the Poisson and binomial probability mass functions which work continuously " "in @code{x}, whereas @code{dbinom(x,*)} and @code{dpois(x,*)} only return " "non zero values for integer @code{x}." msgstr "" # #. type: group #: R-exts.texi:11990 #, no-wrap msgid "" "double dbinom_raw(double x, double n, double p, double q, int give_log)\n" "double dpois_raw (double x, double lambda, int give_log)\n" msgstr "" # #. type: Plain text #: R-exts.texi:11994 msgid "" "Note that @code{dbinom_raw()} gets both @eqn{p, p} and @eqn{q = 1-p, q = 1-" "p} which may be advantageous when one of them is close to @eqn{1, 1}." msgstr "" # #. type: findex #: R-exts.texi:11999 #, no-wrap msgid "gammafn" msgstr "" # #. type: findex #: R-exts.texi:12000 #, no-wrap msgid "lgammafn" msgstr "" # #. type: findex #: R-exts.texi:12001 #, no-wrap msgid "digamma" msgstr "" # #. type: findex #: R-exts.texi:12002 #, no-wrap msgid "trigamma" msgstr "" # #. type: findex #: R-exts.texi:12003 #, no-wrap msgid "tetragamma" msgstr "" # #. type: findex #: R-exts.texi:12004 #, no-wrap msgid "pentagamma" msgstr "" # #. type: findex #: R-exts.texi:12005 #, no-wrap msgid "psigamma" msgstr "" # #. type: cindex #: R-exts.texi:12006 #, no-wrap msgid "Gamma function" msgstr "" # #. type: deftypefun #: R-exts.texi:12007 #, no-wrap msgid "double gammafn (double @var{x})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12008 #, no-wrap msgid "double lgammafn (double @var{x})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12009 #, no-wrap msgid "double digamma (double @var{x})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12010 #, no-wrap msgid "double trigamma (double @var{x})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12011 #, no-wrap msgid "double tetragamma (double @var{x})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12012 #, no-wrap msgid "double pentagamma (double @var{x})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12013 #, no-wrap msgid "double psigamma (double @var{x}, double @var{deriv})" msgstr "" # #. type: deftypefun #: R-exts.texi:12019 msgid "" "The Gamma function, the natural logarithm of its absolute value and first " "four derivatives and the n-th derivative of Psi, the digamma function, which " "is the derivative of @code{lgammafn}. In other words, @code{digamma(x)} is " "the same as @code{(psigamma(x,0)}, @code{trigamma(x) == psigamma(x,1)}, etc." msgstr "" # #. type: findex #: R-exts.texi:12021 #, no-wrap msgid "beta" msgstr "" # #. type: findex #: R-exts.texi:12022 #, no-wrap msgid "lbeta" msgstr "" # #. type: cindex #: R-exts.texi:12023 #, no-wrap msgid "Beta function" msgstr "" # #. type: deftypefun #: R-exts.texi:12024 #, no-wrap msgid "double beta (double @var{a}, double @var{b})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12025 #, no-wrap msgid "double lbeta (double @var{a}, double @var{b})" msgstr "" # #. type: deftypefun #: R-exts.texi:12027 msgid "The (complete) Beta function and its natural logarithm." msgstr "" # #. type: findex #: R-exts.texi:12029 #, no-wrap msgid "choose" msgstr "" # #. type: findex #: R-exts.texi:12030 #, no-wrap msgid "lchoose" msgstr "" # #. type: deftypefun #: R-exts.texi:12031 #, no-wrap msgid "double choose (double @var{n}, double @var{k})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12032 #, no-wrap msgid "double lchoose (double @var{n}, double @var{k})" msgstr "" # #. type: deftypefun #: R-exts.texi:12037 msgid "" "The number of combinations of @var{k} items chosen from from @var{n} and the " "natural logarithm of its absolute value, generalized to arbitrary real " "@var{n}. @var{k} is rounded to the nearest integer (with a warning if " "needed)." msgstr "" # #. type: findex #: R-exts.texi:12039 #, no-wrap msgid "bessel_i" msgstr "" # #. type: findex #: R-exts.texi:12040 #, no-wrap msgid "bessel_j" msgstr "" # #. type: findex #: R-exts.texi:12041 #, no-wrap msgid "bessel_k" msgstr "" # #. type: findex #: R-exts.texi:12042 #, no-wrap msgid "bessel_y" msgstr "" # #. type: cindex #: R-exts.texi:12043 #, no-wrap msgid "Bessel functions" msgstr "" # #. type: deftypefun #: R-exts.texi:12044 #, no-wrap msgid "double bessel_i (double @var{x}, double @var{nu}, double @var{expo})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12045 #, no-wrap msgid "double bessel_j (double @var{x}, double @var{nu})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12046 #, no-wrap msgid "double bessel_k (double @var{x}, double @var{nu}, double @var{expo})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12047 #, no-wrap msgid "double bessel_y (double @var{x}, double @var{nu})" msgstr "" # #. type: deftypefun #: R-exts.texi:12053 msgid "" "Bessel functions of types I, J, K and Y with index @var{nu}. For " "@code{bessel_i} and @code{bessel_k} there is the option to return @w{exp(-" "@var{x}) I(@var{x}; @var{nu})} or @w{exp(@var{x}) K(@var{x}; @var{nu})} if " "@var{expo} is 2. (Use @code{@var{expo} == 1} for unscaled values.)" msgstr "" # #. type: Plain text #: R-exts.texi:12059 msgid "" "There are a few other numerical utility functions available as entry points." msgstr "" # #. type: deftypefun #: R-exts.texi:12061 #, no-wrap msgid "double R_pow (double @var{x}, double @var{y})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12062 #, no-wrap msgid "double R_pow_di (double @var{x}, int @var{i})" msgstr "" # #. type: deftypefun #: R-exts.texi:12068 msgid "" "@code{R_pow(@var{x}, @var{y})} and @code{R_pow_di(@var{x}, @var{i})} compute " "@code{@var{x}^@var{y}} and @code{@var{x}^@var{i}}, respectively using " "@code{R_FINITE} checks and returning the proper result (the same as @R{}) " "for the cases where @var{x}, @var{y} or @var{i} are 0 or missing or infinite " "or @code{NaN}." msgstr "" # #. type: deftypefun #: R-exts.texi:12070 #, no-wrap msgid "double log1p (double @var{x})" msgstr "" # #. type: deftypefun #: R-exts.texi:12073 msgid "" "Computes @code{log(1 + @var{x})} (@emph{log 1 @b{p}lus x}), accurately even " "for small @var{x}, i.e., @eqn{|x| \\ll 1, |x| << 1}." msgstr "" # #. type: deftypefun #: R-exts.texi:12077 #: R-exts.texi:12098 msgid "" "This should be provided by your platform, in which case it is not included " "in @file{Rmath.h}, but is (probably) in @file{math.h} which @file{Rmath.h} " "includes." msgstr "" # #. type: deftypefun #: R-exts.texi:12079 #, no-wrap msgid "double log1pmx (double @var{x})" msgstr "" # #. type: deftypefun #: R-exts.texi:12082 msgid "" "Computes @code{log(1 + @var{x}) - @var{x}} (@emph{log 1 @b{p}lus x @b{m}inus " "@b{x}}), accurately even for small @var{x}, i.e., @eqn{|x| \\ll 1, |x| << 1}." msgstr "" # #. type: deftypefun #: R-exts.texi:12084 #, no-wrap msgid "double log1pexp (double @var{x})" msgstr "" # #. type: deftypefun #: R-exts.texi:12087 msgid "" "Computes @code{log(1 + exp(@var{x}))} (@emph{log 1 @b{p}lus @b{exp}}), " "accurately, notably for large @var{x}, e.g., @eqn{x > 720, x > 720}." msgstr "" # #. type: deftypefun #: R-exts.texi:12091 #, no-wrap msgid "double expm1 (double @var{x})" msgstr "" # #. type: deftypefun #: R-exts.texi:12094 msgid "" "Computes @code{exp(@var{x}) - 1} (@emph{exp x @b{m}inus 1}), accurately even " "for small @var{x}, i.e., @eqn{|x| \\ll 1, |x| << 1}." msgstr "" # #. type: deftypefun #: R-exts.texi:12100 #, no-wrap msgid "double lgamma1p (double @var{x})" msgstr "" # #. type: deftypefun #: R-exts.texi:12103 msgid "" "Computes @code{log(gamma(@var{x} + 1))} (@emph{log(gamma(1 @b{p}lus x))}), " "accurately even for small @var{x}, i.e., @eqn{0 < x < 0.5, 0 < x < 0.5}." msgstr "" # #. type: deftypefun #: R-exts.texi:12105 #, no-wrap msgid "double cospi (double @var{x})" msgstr "" # #. type: deftypefun #: R-exts.texi:12108 msgid "" "Computes @code{cos(pi * x)} (where @code{pi} is 3.14159...), accurately, " "notably for half integer @var{x}." msgstr "" # #. type: deftypefun #: R-exts.texi:12112 msgid "" "This might be provided by your platform@footnote{It is an optional C11 " "extension.}, in which case it is not included in @file{Rmath.h}, but is in " "@file{math.h} which @file{Rmath.h} includes." msgstr "" # #. type: deftypefun #: R-exts.texi:12114 #, no-wrap msgid "double sinpi (double @var{x})" msgstr "" # #. type: deftypefun #: R-exts.texi:12116 msgid "" "Computes @code{sin(pi * x)} accurately, notably for (half) integer @var{x}." msgstr "" # #. type: deftypefun #: R-exts.texi:12119 #: R-exts.texi:12126 msgid "" "This might be provided by your platform, in which case it is not included in " "@file{Rmath.h}, but is in @file{math.h} which @file{Rmath.h} includes." msgstr "" # #. type: deftypefun #: R-exts.texi:12121 #, no-wrap msgid "double tanpi (double @var{x})" msgstr "" # #. type: deftypefun #: R-exts.texi:12123 msgid "" "Computes @code{tan(pi * x)} accurately, notably for (half) integer @var{x}." msgstr "" # #. type: deftypefun #: R-exts.texi:12128 #, no-wrap msgid "double logspace_add (double @var{logx}, double @var{logy})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12129 #, no-wrap msgid "double logspace_sub (double @var{logx}, double @var{logy})" msgstr "" #. type: deftypefunx #: R-exts.texi:12130 #, no-wrap msgid "double logspace_sum (const double* @var{logx}, int @var{n})" msgstr "" # #. type: deftypefun #: R-exts.texi:12136 msgid "" "Compute the log of a sum or difference from logs of terms, i.e., ``x + y'' " "as @code{log (exp(@var{logx}) + exp(@var{logy}))} and ``x - y'' as @code{log " "(exp(@var{logx}) - exp(@var{logy}))}, and ``sum_i x[i]'' as @code{log (sum[i " "= 1:@var{n} exp(@var{logx}[i])] )} without causing unnecessary overflows or " "throwing away too much accuracy." msgstr "" # #. type: deftypefun #: R-exts.texi:12138 #, no-wrap msgid "int imax2 (int @var{x}, int @var{y})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12139 #, no-wrap msgid "int imin2 (int @var{x}, int @var{y})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12140 #, no-wrap msgid "double fmax2 (double @var{x}, double @var{y})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12141 #, no-wrap msgid "double fmin2 (double @var{x}, double @var{y})" msgstr "" # #. type: deftypefun #: R-exts.texi:12146 msgid "" "Return the larger (@code{max}) or smaller (@code{min}) of two integer or " "double numbers, respectively. Note that @code{fmax2} and @code{fmin2} " "differ from C99's @code{fmax} and @code{fmin} when one of the arguments is a " "@code{NaN}: these versions return @code{NaN}." msgstr "" # #. type: deftypefun #: R-exts.texi:12148 #, no-wrap msgid "double sign (double @var{x})" msgstr "" # #. type: deftypefun #: R-exts.texi:12152 msgid "" "Compute the @emph{signum} function, where sign(@var{x}) is 1, 0, or " "@math{-1}, when @var{x} is positive, 0, or negative, respectively, and " "@code{NaN} if @code{x} is a @code{NaN}." msgstr "" # #. type: deftypefun #: R-exts.texi:12154 #, no-wrap msgid "double fsign (double @var{x}, double @var{y})" msgstr "" # #. type: deftypefun #: R-exts.texi:12157 msgid "" "Performs ``transfer of sign'' and is defined as @eqn{|x| * \\hbox{sign}(y), |" "x| * sign(y)}." msgstr "" # #. type: deftypefun #: R-exts.texi:12159 #, no-wrap msgid "double fprec (double @var{x}, double @var{digits})" msgstr "" # #. type: deftypefun #: R-exts.texi:12162 msgid "" "Returns the value of @var{x} rounded to @var{digits} decimal digits (after " "the decimal point)." msgstr "" # #. type: deftypefun #: R-exts.texi:12164 msgid "This is the function used by @R{}'s @code{signif()}." msgstr "" # #. type: deftypefun #: R-exts.texi:12166 #, no-wrap msgid "double fround (double @var{x}, double @var{digits})" msgstr "" # #. type: deftypefun #: R-exts.texi:12169 msgid "" "Returns the value of @var{x} rounded to @var{digits} @emph{significant} " "decimal digits." msgstr "" # #. type: deftypefun #: R-exts.texi:12171 msgid "This is the function used by @R{}'s @code{round()}." msgstr "" # #. type: deftypefun #: R-exts.texi:12173 #, no-wrap msgid "double ftrunc (double @var{x})" msgstr "" # #. type: deftypefun #: R-exts.texi:12176 msgid "" "Returns the value of @var{x} truncated (to an integer value) towards zero." msgstr "" # #. type: deftypefun #: R-exts.texi:12179 msgid "" "Note that this is no longer needed in C code, as C99 provide a @code{trunc} " "function. It is needed for portable C++98 code." msgstr "" # #. type: findex #: R-exts.texi:12183 #, no-wrap msgid "M_E" msgstr "" # #. type: findex #: R-exts.texi:12184 #, no-wrap msgid "M_PI" msgstr "" # #. type: Plain text #: R-exts.texi:12192 msgid "" "@R{} has a set of commonly used mathematical constants encompassing " "constants usually found @file{math.h} and contains further ones that are " "used in statistical computations. All these are defined to (at least) 30 " "digits accuracy in @file{Rmath.h}. The following definitions use " "@code{ln(x)} for the natural logarithm (@code{log(x)} in @R{})." msgstr "" # #. type: multitable #: R-exts.texi:12197 msgid "@headitem Name" msgstr "" # #. type: multitable #: R-exts.texi:12197 msgid "Definition (@code{ln = log})" msgstr "" # #. type: multitable #: R-exts.texi:12197 msgid "round(@emph{value}, 7)" msgstr "" # #. type: item #: R-exts.texi:12197 #, no-wrap msgid "@code{M_E} @tab @math{e} @tab 2.7182818" msgstr "" # #. type: item #: R-exts.texi:12198 #, no-wrap msgid "@code{M_LOG2E} @tab log2(@math{e}) @tab 1.4426950" msgstr "" # #. type: item #: R-exts.texi:12199 #, no-wrap msgid "@code{M_LOG10E} @tab log10(@math{e}) @tab 0.4342945" msgstr "" # #. type: item #: R-exts.texi:12200 #, no-wrap msgid "@code{M_LN2} @tab ln(2) @tab 0.6931472" msgstr "" # #. type: item #: R-exts.texi:12201 #, no-wrap msgid "@code{M_LN10} @tab ln(10) @tab 2.3025851" msgstr "" # #. type: item #: R-exts.texi:12202 #, no-wrap msgid "@code{M_PI} @tab @eqn{\\pi, pi} @tab 3.1415927" msgstr "" # #. type: item #: R-exts.texi:12203 #, no-wrap msgid "@code{M_PI_2} @tab @eqn{\\pi/2, pi/2} @tab 1.5707963" msgstr "" # #. type: item #: R-exts.texi:12204 #, no-wrap msgid "@code{M_PI_4} @tab @eqn{\\pi/4, pi/4} @tab 0.7853982" msgstr "" # #. type: item #: R-exts.texi:12205 #, no-wrap msgid "@code{M_1_PI} @tab @eqn{1/\\pi, 1/pi} @tab 0.3183099" msgstr "" # #. type: item #: R-exts.texi:12206 #, no-wrap msgid "@code{M_2_PI} @tab @eqn{2/\\pi, 2/pi} @tab 0.6366198" msgstr "" # #. type: item #: R-exts.texi:12207 #, no-wrap msgid "@code{M_2_SQRTPI} @tab 2/sqrt(@eqn{\\pi, pi}) @tab 1.1283792" msgstr "" # #. type: item #: R-exts.texi:12208 #, no-wrap msgid "@code{M_SQRT2} @tab sqrt(2) @tab 1.4142136" msgstr "" # #. type: item #: R-exts.texi:12209 #, no-wrap msgid "@code{M_SQRT1_2} @tab 1/sqrt(2) @tab 0.7071068" msgstr "" # #. type: item #: R-exts.texi:12211 #, no-wrap msgid "@code{M_SQRT_3} @tab sqrt(3) @tab 1.7320508" msgstr "" # #. type: item #: R-exts.texi:12212 #, no-wrap msgid "@code{M_SQRT_32} @tab sqrt(32) @tab 5.6568542" msgstr "" # #. type: item #: R-exts.texi:12213 #, no-wrap msgid "@code{M_LOG10_2} @tab log10(2) @tab 0.3010300" msgstr "" # #. type: item #: R-exts.texi:12214 #, no-wrap msgid "@code{M_2PI} @tab @eqn{2\\pi, 2*pi} @tab 6.2831853" msgstr "" # #. type: item #: R-exts.texi:12215 #, no-wrap msgid "@code{M_SQRT_PI} @tab sqrt(@eqn{\\pi, pi}) @tab 1.7724539" msgstr "" # #. type: item #: R-exts.texi:12216 #, no-wrap msgid "@code{M_1_SQRT_2PI} @tab 1/sqrt(@eqn{2\\pi, 2*pi}) @tab 0.3989423" msgstr "" # #. type: item #: R-exts.texi:12217 #, no-wrap msgid "@code{M_SQRT_2dPI} @tab sqrt(2/@eqn{\\pi, pi}) @tab 0.7978846" msgstr "" # #. type: item #: R-exts.texi:12218 #, no-wrap msgid "@code{M_LN_SQRT_PI} @tab ln(sqrt(@eqn{\\pi, pi})) @tab 0.5723649" msgstr "" # #. type: item #: R-exts.texi:12219 #, no-wrap msgid "@code{M_LN_SQRT_2PI} @tab ln(sqrt(@eqn{2\\pi, 2*pi})) @tab 0.9189385" msgstr "" # #. type: item #: R-exts.texi:12220 #, no-wrap msgid "@code{M_LN_SQRT_PId2} @tab ln(sqrt(@eqn{\\pi, pi}/2)) @tab 0.2257914" msgstr "" # #. type: Plain text #: R-exts.texi:12227 msgid "" "There are a set of constants (@code{PI}, @code{DOUBLE_EPS}) (and so on) " "defined (unless @code{STRICT_R_HEADERS} is defined) in the included header " "@file{R_ext/Constants.h}, mainly for compatibility with @Sl{}." msgstr "" # #. type: findex #: R-exts.texi:12228 #, no-wrap msgid "TRUE" msgstr "" # #. type: findex #: R-exts.texi:12229 #, no-wrap msgid "FALSE" msgstr "" # #. type: Plain text #: R-exts.texi:12235 msgid "" "Further, the included header @file{R_ext/Boolean.h} has enumeration " "constants @code{TRUE} and @code{FALSE} of type @code{Rboolean} in order to " "provide a way of using ``logical'' variables in C consistently. This can " "conflict with other software: for example it conflicts with the headers in " "IJG's @code{jpeg-9} (but not earlier versions)." msgstr "" # #. type: cindex #: R-exts.texi:12239 #, no-wrap msgid "optimization" msgstr "" # #. type: Plain text #: R-exts.texi:12244 msgid "" "The C code underlying @code{optim} can be accessed directly. The user needs " "to supply a function to compute the function to be minimized, of the type" msgstr "" # #. type: example #: R-exts.texi:12247 #, no-wrap msgid "typedef double optimfn(int n, double *par, void *ex);\n" msgstr "" # #. type: Plain text #: R-exts.texi:12253 msgid "" "where the first argument is the number of parameters in the second " "argument. The third argument is a pointer passed down from the calling " "routine, normally used to carry auxiliary information." msgstr "" # #. type: Plain text #: R-exts.texi:12255 msgid "Some of the methods also require a gradient function" msgstr "" # #. type: example #: R-exts.texi:12258 #, no-wrap msgid "typedef void optimgr(int n, double *par, double *gr, void *ex);\n" msgstr "" # #. type: Plain text #: R-exts.texi:12264 msgid "" "which passes back the gradient in the @code{gr} argument. No function is " "provided for finite-differencing, nor for approximating the Hessian at the " "result." msgstr "" # #. type: Plain text #: R-exts.texi:12266 msgid "The interfaces (defined in header @file{R_ext/Applic.h}) are" msgstr "" # #. type: item #: R-exts.texi:12268 #, no-wrap msgid "Nelder Mead:" msgstr "" # #. type: findex #: R-exts.texi:12269 #, no-wrap msgid "nmmin" msgstr "" # #. type: example #: R-exts.texi:12275 #, no-wrap msgid "" "void nmmin(int n, double *xin, double *x, double *Fmin, optimfn fn,\n" "\t int *fail, double abstol, double intol, void *ex,\n" "\t double alpha, double beta, double gamma, int trace,\n" "\t int *fncount, int maxit);\n" msgstr "" # #. type: item #: R-exts.texi:12277 #, no-wrap msgid "BFGS:" msgstr "" # #. type: findex #: R-exts.texi:12278 #, no-wrap msgid "vmmin" msgstr "" # #. type: example #: R-exts.texi:12284 #, no-wrap msgid "" "void vmmin(int n, double *x, double *Fmin,\n" "\t optimfn fn, optimgr gr, int maxit, int trace,\n" "\t int *mask, double abstol, double reltol, int nREPORT,\n" "\t void *ex, int *fncount, int *grcount, int *fail);\n" msgstr "" # #. type: item #: R-exts.texi:12286 #, no-wrap msgid "Conjugate gradients:" msgstr "" # #. type: findex #: R-exts.texi:12287 #, no-wrap msgid "cgmin" msgstr "" # #. type: example #: R-exts.texi:12293 #, no-wrap msgid "" "void cgmin(int n, double *xin, double *x, double *Fmin,\n" "\t optimfn fn, optimgr gr, int *fail, double abstol,\n" "\t double intol, void *ex, int type, int trace,\n" "\t int *fncount, int *grcount, int maxit);\n" msgstr "" # #. type: item #: R-exts.texi:12295 #, no-wrap msgid "Limited-memory BFGS with bounds:" msgstr "" # #. type: findex #: R-exts.texi:12296 #, no-wrap msgid "lbfgsb" msgstr "" # #. type: example #: R-exts.texi:12303 #, no-wrap msgid "" "void lbfgsb(int n, int lmm, double *x, double *lower,\n" "\t double *upper, int *nbd, double *Fmin, optimfn fn,\n" "\t optimgr gr, int *fail, void *ex, double factr,\n" "\t double pgtol, int *fncount, int *grcount,\n" "\t int maxit, char *msg, int trace, int nREPORT);\n" msgstr "" # #. type: item #: R-exts.texi:12305 #, no-wrap msgid "Simulated annealing:" msgstr "" # #. type: findex #: R-exts.texi:12306 #, no-wrap msgid "samin" msgstr "" # #. type: example #: R-exts.texi:12310 #, no-wrap msgid "" "void samin(int n, double *x, double *Fmin, optimfn fn, int maxit,\n" "\t int tmax, double temp, int trace, void *ex);\n" msgstr "" # #. type: Plain text #: R-exts.texi:12322 msgid "" "Many of the arguments are common to the various methods. @code{n} is the " "number of parameters, @code{x} or @code{xin} is the starting parameters on " "entry and @code{x} the final parameters on exit, with final value returned " "in @code{Fmin}. Most of the other parameters can be found from the help " "page for @code{optim}: see the source code @file{src/appl/lbfgsb.c} for the " "values of @code{nbd}, which specifies which bounds are to be used." msgstr "" # #. type: cindex #: R-exts.texi:12326 #, no-wrap msgid "integration" msgstr "" # #. type: Plain text #: R-exts.texi:12331 msgid "" "The C code underlying @code{integrate} can be accessed directly. The user " "needs to supply a @emph{vectorizing} C function to compute the function to " "be integrated, of the type" msgstr "" # #. type: example #: R-exts.texi:12334 #, no-wrap msgid "typedef void integr_fn(double *x, int n, void *ex);\n" msgstr "" # #. type: Plain text #: R-exts.texi:12345 msgid "" "where @code{x[]} is both input and output and has length @code{n}, i.e., a C " "function, say @code{fn}, of type @code{integr_fn} must basically do " "@code{for(i in 1:n) x[i] := f(x[i], ex)}. The vectorization requirement can " "be used to speed up the integrand instead of calling it @code{n} times. " "Note that in the current implementation built on QUADPACK, @code{n} will be " "either 15 or 21. The @code{ex} argument is a pointer passed down from the " "calling routine, normally used to carry auxiliary information." msgstr "" #. type: Plain text #: R-exts.texi:12349 msgid "" "There are interfaces (defined in header @file{R_ext/Applic.h}) for integrals " "over finite and infinite intervals (or ``ranges'' or ``integration " "boundaries'')." msgstr "" # #. type: item #: R-exts.texi:12351 #, no-wrap msgid "Finite:" msgstr "" # #. type: findex #: R-exts.texi:12352 #, no-wrap msgid "Rdqags" msgstr "" # #. type: example #: R-exts.texi:12359 #, no-wrap msgid "" "void Rdqags(integr_fn f, void *ex, double *a, double *b,\n" "\t double *epsabs, double *epsrel,\n" "\t double *result, double *abserr, int *neval, int *ier,\n" "\t int *limit, int *lenw, int *last,\n" "\t int *iwork, double *work);\n" msgstr "" #. type: item #: R-exts.texi:12361 #, no-wrap msgid "Infinite:" msgstr "" # #. type: findex #: R-exts.texi:12362 #, no-wrap msgid "Rdqagi" msgstr "" # #. type: example #: R-exts.texi:12369 #, no-wrap msgid "" "void Rdqagi(integr_fn f, void *ex, double *bound, int *inf,\n" "\t double *epsabs, double *epsrel,\n" "\t double *result, double *abserr, int *neval, int *ier,\n" "\t int *limit, int *lenw, int *last,\n" "\t int *iwork, double *work);\n" msgstr "" #. type: Plain text #: R-exts.texi:12380 msgid "" "Only the 3rd and 4th argument differ for the two integrators; for the finite " "range integral using @code{Rdqags}, @code{a} and @code{b} are the " "integration interval bounds, whereas for an infinite range integral using " "@code{Rdqagi}, @code{bound} is the finite bound of the integration (if the " "integral is not doubly-infinite) and @code{inf} is a code indicating the " "kind of integration range," msgstr "" # #. type: item #: R-exts.texi:12382 #, no-wrap msgid "inf = 1" msgstr "" # #. type: table #: R-exts.texi:12384 msgid "corresponds to (bound, +Inf)," msgstr "" # #. type: item #: R-exts.texi:12384 #, no-wrap msgid "inf = -1" msgstr "" # #. type: table #: R-exts.texi:12386 msgid "corresponds to (-Inf, bound)," msgstr "" # #. type: item #: R-exts.texi:12386 #, no-wrap msgid "inf = 2" msgstr "" # #. type: table #: R-exts.texi:12388 msgid "corresponds to (-Inf, +Inf)," msgstr "" # #. type: Plain text #: R-exts.texi:12400 msgid "" "@code{f} and @code{ex} define the integrand function, see above; " "@code{epsabs} and @code{epsrel} specify the absolute and relative accuracy " "requested, @code{result}, @code{abserr} and @code{last} are the output " "components @code{value}, @code{abs.err} and @code{subdivisions} of the @R{} " "function integrate, where @code{neval} gives the number of integrand " "function evaluations, and the error code @code{ier} is translated to @R{}'s " "@code{integrate() $ message}, look at that function definition. " "@code{limit} corresponds to @code{integrate(..., subdivisions = *)}. It " "seems you should always define the two work arrays and the length of the " "second one as" msgstr "" # #. type: example #: R-exts.texi:12405 #, no-wrap msgid "" " lenw = 4 * limit;\n" " iwork = (int *) R_alloc(limit, sizeof(int));\n" " work = (double *) R_alloc(lenw, sizeof(double));\n" msgstr "" # #. type: Plain text #: R-exts.texi:12409 msgid "" "The comments in the source code in @file{src/appl/integrate.c} give more " "details, particularly about reasons for failure (@code{ier >= 1})." msgstr "" # #. type: cindex #: R-exts.texi:12413 #, no-wrap msgid "Sort functions from C" msgstr "" # #. type: Plain text #: R-exts.texi:12418 msgid "" "@R{} has a fairly comprehensive set of sort routines which are made " "available to users' C code. The following is declared in header file " "@file{Rinternals.h}." msgstr "" # #. type: deftypefun #: R-exts.texi:12419 #, no-wrap msgid "void R_orderVector (int* @var{indx}, int @var{n}, SEXP @var{arglist}, Rboolean @var{nalast}, Rboolean @var{decreasing})" msgstr "" # #. type: deftypefun #: R-exts.texi:12425 msgid "" "This corresponds to @R{}'s @code{order(..., na.last, decreasing)}. More " "specifically, @code{indx <- order(x, y, na.last, decreasing)} corresponds to " "@code{R_orderVector(indx, n, Rf_lang2(x, y), nalast, decreasing)} and for " "three vectors, @code{Rf_lang3(x,y,z)} is used as @var{arglist}." msgstr "" # #. type: deftypefun #: R-exts.texi:12430 msgid "" "Note that @code{R_orderVector()} assumes the vector @code{indx} to be " "allocated to length @eqn{\\ge n, >= n}. On return, @code{indx[]} contains a " "permutation of @code{0:(n-1)}, i.e., 0-based C indices (and not 1-based @R{} " "indices, as @R{}'s @code{order()})." msgstr "" # #. type: Plain text #: R-exts.texi:12434 msgid "" "All other sort routines are declared in header file @file{R_ext/Utils.h} " "(included by @file{R.h}) and include the following." msgstr "" # #. type: deftypefun #: R-exts.texi:12435 #, no-wrap msgid "void R_isort (int* @var{x}, int @var{n})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12436 #, no-wrap msgid "void R_rsort (double* @var{x}, int @var{n})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12437 #, no-wrap msgid "void R_csort (Rcomplex* @var{x}, int @var{n})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12438 #, no-wrap msgid "void rsort_with_index (double* @var{x}, int* @var{index}, int @var{n})" msgstr "" # #. type: deftypefun #: R-exts.texi:12442 msgid "" "The first three sort integer, real (double) and complex data respectively. " "(Complex numbers are sorted by the real part first then the imaginary " "part.) @code{NA}s are sorted last." msgstr "" # #. type: deftypefun #: R-exts.texi:12445 msgid "" "@code{rsort_with_index} sorts on @var{x}, and applies the same permutation " "to @var{index}. @code{NA}s are sorted last." msgstr "" # #. type: deftypefun #: R-exts.texi:12447 #, no-wrap msgid "void revsort (double* @var{x}, int* @var{index}, int @var{n})" msgstr "" # #. type: deftypefun #: R-exts.texi:12450 msgid "" "Is similar to @code{rsort_with_index} but sorts into decreasing order, and " "@code{NA}s are not handled." msgstr "" # #. type: deftypefun #: R-exts.texi:12452 #, no-wrap msgid "void iPsort (int* @var{x}, int @var{n}, int @var{k})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12453 #, no-wrap msgid "void rPsort (double* @var{x}, int @var{n}, int @var{k})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12454 #, no-wrap msgid "void cPsort (Rcomplex* @var{x}, int @var{n}, int @var{k})" msgstr "" # #. type: deftypefun #: R-exts.texi:12458 msgid "" "These all provide (very) partial sorting: they permute @var{x} so that " "@code{@var{x}[@var{k}]} is in the correct place with smaller values to the " "left, larger ones to the right." msgstr "" # #. type: deftypefun #: R-exts.texi:12461 #, no-wrap msgid "void R_qsort (double *@var{v}, size_t @var{i}, size_t @var{j})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12462 #, no-wrap msgid "void R_qsort_I (double *@var{v}, int *@var{I}, int @var{i}, int @var{j})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12463 #, no-wrap msgid "void R_qsort_int (int *@var{iv}, size_t @var{i}, size_t @var{j})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12464 #, no-wrap msgid "void R_qsort_int_I (int *@var{iv}, int *@var{I}, int @var{i}, int @var{j})" msgstr "" # #. type: deftypefun #: R-exts.texi:12474 msgid "" "These routines sort @code{@var{v}[@var{i}:@var{j}]} or @code{@var{iv}" "[@var{i}:@var{j}]} (using 1-indexing, i.e., @code{@var{v}[1]} is the first " "element) calling the quicksort algorithm as used by @R{}'s @code{sort(v, " "method = \"quick\")} and documented on the help page for the @R{} function " "@code{sort}. The @code{..._I()} versions also return the @code{sort." "index()} vector in @code{I}. Note that the ordering is @emph{not} stable, " "so tied values may be permuted." msgstr "" # #. type: deftypefun #: R-exts.texi:12477 msgid "" "Note that @code{NA}s are not handled (explicitly) and you should use " "different sorting functions if @code{NA}s can be present." msgstr "" # #. type: deftypefun #: R-exts.texi:12479 #, no-wrap msgid "subroutine qsort4 (double precision @var{v}, integer @var{indx}, integer @var{ii}, integer @var{jj})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12480 #, no-wrap msgid "subroutine qsort3 (double precision @var{v}, integer @var{ii}, integer @var{jj})" msgstr "" # #. type: deftypefun #: R-exts.texi:12485 msgid "" "The FORTRAN interface routines for sorting double precision vectors are " "@code{qsort3} and @code{qsort4}, equivalent to @code{R_qsort} and " "@code{R_qsort_I}, respectively." msgstr "" # #. type: deftypefun #: R-exts.texi:12487 #, no-wrap msgid "void R_max_col (double* @var{matrix}, int* @var{nr}, int* @var{nc}, int* @var{maxes}, int* @var{ties_meth})" msgstr "" # #. type: deftypefun #: R-exts.texi:12496 msgid "" "Given the @var{nr} by @var{nc} matrix @code{matrix} in column-major " "(``FORTRAN'') order, @code{R_max_col()} returns in @code{@var{maxes}" "[@var{i}-1]} the column number of the maximal element in the @var{i}-th row " "(the same as @R{}'s @code{max.col()} function). In the case of ties " "(multiple maxima), @code{*ties_meth} is an integer code in @code{1:3} " "determining the method: 1 = ``random'', 2 = ``first'' and 3 = ``last''. See " "@R{}'s help page @code{?max.col}." msgstr "" # #. type: deftypefun #: R-exts.texi:12498 #, no-wrap msgid "int findInterval (double* @var{xt}, int @var{n}, double @var{x}, Rboolean @var{rightmost_closed}, Rboolean @var{all_inside}, int @var{ilo}, int* @var{mflag})" msgstr "" # #. type: deftypefun #: R-exts.texi:12509 msgid "" "Given the ordered vector @var{xt} of length @var{n}, return the interval or " "index of @var{x} in @code{@var{xt}[]}, typically max(@math{i}; @eqn{1 \\le i " "\\le @var{n}, 1 <= i <= @var{n}} & @math{@var{xt}[i]} @eqn{\\le, <=} " "@var{x}) where we use 1-indexing as in @R{} and FORTRAN (but not C). If " "@var{rightmost_closed} is true, also returns @math{@var{n}-1} if @var{x} " "equals @math{@var{xt}[@var{n}]}. If @var{all_inside} is not 0, the result " "is coerced to lie in @code{1:(@var{n}-1)} even when @var{x} is outside the " "@var{xt}[] range. On return, @code{*@var{mflag}} equals @math{-1} if " "@var{x} < @var{xt}[1], @math{+1} if @var{x} >= @var{xt}[@var{n}], and 0 " "otherwise." msgstr "" # #. type: deftypefun #: R-exts.texi:12513 msgid "" "The algorithm is particularly fast when @var{ilo} is set to the last result " "of @code{findInterval()} and @var{x} is a value of a sequence which is " "increasing or decreasing for subsequent calls." msgstr "" # #. type: deftypefun #: R-exts.texi:12516 msgid "" "There is also an @code{F77_CALL(interv)()} version of @code{findInterval()} " "with the same arguments, but all pointers." msgstr "" # #. type: Plain text #: R-exts.texi:12520 msgid "" "A system-independent interface to produce the name of a temporary file is " "provided as" msgstr "" # #. type: deftypefun #: R-exts.texi:12521 #, no-wrap msgid "{char *} R_tmpnam (const char *@var{prefix}, const char *@var{tmpdir})" msgstr "" # #. type: deftypefunx #: R-exts.texi:12522 #, no-wrap msgid "{char *} R_tmpnam2 (const char *@var{prefix}, const char *@var{tmpdir}, const char *@var{fileext})" msgstr "" # #. type: deftypefun #: R-exts.texi:12528 msgid "" "Return a pathname for a temporary file with name beginning with @var{prefix} " "and ending with @var{fileext} in directory @var{tmpdir}. A @code{NULL} " "prefix or extension is replaced by @code{\"\"}. Note that the return value " "is @code{malloc}ed and should be @code{free}d when no longer needed (unlike " "the system call @code{tmpnam})." msgstr "" # #. type: Plain text #: R-exts.texi:12534 msgid "" "There is also the internal function used to expand file names in several " "@R{} functions, and called directly by @code{path.expand}." msgstr "" # #. type: deftypefun #: R-exts.texi:12535 #, no-wrap msgid "{const char *} R_ExpandFileName (const char *@var{fn})" msgstr "" # #. type: deftypefun #: R-exts.texi:12540 msgid "" "Expand a path name @var{fn} by replacing a leading tilde by the user's home " "directory (if defined). The precise meaning is platform-specific; it will " "usually be taken from the environment variable @env{HOME} if this is defined." msgstr "" # #. type: Plain text #: R-exts.texi:12548 msgid "" "For historical reasons there are FORTRAN interfaces to functions " "@code{D1MACH} and @code{I1MACH}. These can be called from C code as e.g.@: " "@code{F77_CALL(d1mach)(4)}. Note that these are emulations of the original " "functions by Fox, Hall and Schryer on NetLib at @uref{http://www.netlib.org/" "slatec/src/} for IEC 60559 arithmetic (required by @R{})." msgstr "" # #. type: Plain text #: R-exts.texi:12556 msgid "" "@R{} has its own C-level interface to the encoding conversion capabilities " "provided by @code{iconv} because there are incompatibilities between the " "declarations in different implementations of @code{iconv}." msgstr "" # #. type: Plain text #: R-exts.texi:12558 msgid "These are declared in header file @file{R_ext/Riconv.h}." msgstr "" # #. type: deftypefun #: R-exts.texi:12559 #, no-wrap msgid "{void *} Riconv_open (const char *@var{to}, const char *@var{from})" msgstr "" # #. type: Plain text #: R-exts.texi:12563 msgid "" "Set up a pointer to an encoding object to be used to convert between two " "encodings: @code{\"\"} indicates the current locale." msgstr "" # #. type: deftypefun #: R-exts.texi:12564 #, no-wrap msgid "size_t Riconv (void *@var{cd}, const char **@var{inbuf}, size_t *@var{inbytesleft}, char **@var{outbuf}, size_t *@var{outbytesleft})" msgstr "" # #. type: Plain text #: R-exts.texi:12576 msgid "" "Convert as much as possible of @code{inbuf} to @code{outbuf}. Initially the " "@code{int} variables indicate the number of bytes available in the buffers, " "and they are updated (and the @code{char} pointers are updated to point to " "the next free byte in the buffer). The return value is the number of " "characters converted, or @code{(size_t)-1} (beware: @code{size_t} is usually " "an unsigned type). It should be safe to assume that an error condition sets " "@code{errno} to one of @code{E2BIG} (the output buffer is full), " "@code{EILSEQ} (the input cannot be converted, and might be invalid in the " "encoding specified) or @code{EINVAL} (the input does not end with a complete " "multi-byte character)." msgstr "" # #. type: deftypefun #: R-exts.texi:12577 #, no-wrap msgid "int Riconv_close (void * @var{cd})" msgstr "" # #. type: Plain text #: R-exts.texi:12580 msgid "Free the resources of an encoding object." msgstr "" # #. type: cindex #: R-exts.texi:12584 #, no-wrap msgid "Interrupts" msgstr "" # #. type: Plain text #: R-exts.texi:12589 msgid "" "No port of @R{} can be interrupted whilst running long computations in " "compiled code, so programmers should make provision for the code to be " "interrupted at suitable points by calling from C" msgstr "" # #. type: example #: R-exts.texi:12592 #, no-wrap msgid "" "#include <R_ext/Utils.h>\n" "\n" msgstr "" # #. type: example #: R-exts.texi:12594 #, no-wrap msgid "void R_CheckUserInterrupt(void);\n" msgstr "" # #. type: Plain text #: R-exts.texi:12598 msgid "and from FORTRAN" msgstr "" # #. type: example #: R-exts.texi:12601 #, no-wrap msgid "subroutine rchkusr()\n" msgstr "" # #. type: Plain text #: R-exts.texi:12605 msgid "" "These check if the user has requested an interrupt, and if so branch to " "@R{}'s error handling functions." msgstr "" # #. type: Plain text #: R-exts.texi:12609 msgid "" "Note that it is possible that the code behind one of the entry points " "defined here if called from your C or FORTRAN code could be interruptible or " "generate an error and so not return to your code." msgstr "" # #. type: cindex #: R-exts.texi:12613 #, no-wrap msgid "Version information from C" msgstr "" # #. type: findex #: R-exts.texi:12615 #, no-wrap msgid "R_Version" msgstr "" # #. type: Plain text #: R-exts.texi:12619 msgid "" "The header files define @code{USING_R}, which can be used to test if the " "code is indeed being used with @R{}." msgstr "" #. type: Plain text #: R-exts.texi:12631 msgid "" "Header file @file{Rconfig.h} (included by @file{R.h}) is used to define " "platform-specific macros that are mainly for use in other header files. The " "macro @code{WORDS_BIGENDIAN} is defined on big-endian@footnote{@uref{https://" "en.wikipedia.org/@/wiki/@/Endianness}.} systems (e.g.@: most OSes on Sparc " "and PowerPC hardware) and not on little-endian systems (such as @code{i686} " "and @code{x86_64} on all OSes, and Linux on Alpha and Itanium). It can be " "useful when manipulating binary files. The macro @code{SUPPORT_OPENMP} is " "defined on suitable systems and can be used in conjunction with the " "@code{SUPPORT_OPENMP_*} macros in packages that want to make use of OpenMP." msgstr "" # #. type: Plain text #: R-exts.texi:12638 msgid "" "Header file @file{Rversion.h} (@strong{not} included by @file{R.h}) defines " "a macro @code{R_VERSION} giving the version number encoded as an integer, " "plus a macro @code{R_Version} to do the encoding. This can be used to test " "if the version of @R{} is late enough, or to include back-compatibility " "features. For protection against very old versions of @R{} which did not " "have this macro, use a construction such as" msgstr "" #. type: group #: R-exts.texi:12644 #, no-wrap msgid "" "#if defined(R_VERSION) && R_VERSION >= R_Version(3, 1, 0)\n" " ...\n" "#endif\n" msgstr "" #. type: Plain text #: R-exts.texi:12651 msgid "" "More detailed information is available in the macros @code{R_MAJOR}, " "@code{R_MINOR}, @code{R_YEAR}, @code{R_MONTH} and @code{R_DAY}: see the " "header file @file{Rversion.h} for their format. Note that the minor version " "includes the patchlevel (as in @samp{2.2})." msgstr "" #. type: Plain text #: R-exts.texi:12655 msgid "" "Packages which use @code{alloca} need to ensure it is defined: as it is " "neither C99 nor POSIX there is no standard way to do so. As from @R{} 3.2.2 " "one can use" msgstr "" #. type: example #: R-exts.texi:12666 #, no-wrap msgid "" "#include <Rconfig.h> // for HAVE_ALLOCA_H\n" "#ifdef __GNUC__\n" "// this covers gcc, clang, icc\n" "# undef alloca\n" "# define alloca(x) __builtin_alloca((x))\n" "#elif defined(HAVE_ALLOCA_H)\n" "// needed for native compilers on Solaris and AIX\n" "# include <alloca.h>\n" "#endif\n" msgstr "" #. type: Plain text #: R-exts.texi:12673 msgid "" "(and this should be included before standard C headers such as @file{stdlib." "h}, since on some platforms these include @file{malloc.h} which may have a " "conflicting definition), which suffices for known @R{} platforms." msgstr "" # #. type: findex #: R-exts.texi:12676 #, no-wrap msgid "R_INLINE" msgstr "" # #. type: Plain text #: R-exts.texi:12683 msgid "" "The C99 keyword @code{inline} should be recognized by all compilers now used " "to build @R{}. Portable code which might be used with earlier versions of " "@R{} can be written using the macro @code{R_INLINE} (defined in file " "@file{Rconfig.h} included by @file{R.h}), as for example from package " "@CRANpkg{cluster}" msgstr "" # #. type: example #: R-exts.texi:12691 #, no-wrap msgid "" "static R_INLINE int ind_2(int l, int j)\n" "@{\n" "...\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:12701 msgid "" "Be aware that using inlining with functions in more than one compilation " "unit is almost impossible to do portably, see @uref{http://www.greenend.org." "uk/@/rjk/@/2003/@/03/@/inline.html}, so this usage is for @code{static} " "functions as in the example. All the @R{} configure code has checked is " "that @code{R_INLINE} can be used in a single C file with the compiler used " "to build @R{}. We recommend that packages making extensive use of inlining " "include their own configure code." msgstr "" # #. type: cindex #: R-exts.texi:12704 #, no-wrap msgid "Visibility" msgstr "" # #. type: Plain text #: R-exts.texi:12715 msgid "" "Header @file{R_ext/Visibility} has some definitions for controlling the " "visibility of entry points. These are only effective when " "@samp{HAVE_VISIBILITY_ATTRIBUTE} is defined -- this is checked when @R{} is " "configured and recorded in header @file{Rconfig.h} (included by @file{R_ext/" "Visibility.h}). It is generally defined on modern Unix-alikes with a recent " "compiler, but not supported on OS X nor Windows. Minimizing the visibility " "of symbols in a shared library will both speed up its loading (unlikely to " "be significant) and reduce the possibility of linking to other entry points " "of the same name." msgstr "" # #. type: Plain text #: R-exts.texi:12726 msgid "" "C/C++ entry points prefixed by @code{attribute_hidden} will not be visible " "in the shared object. There is no comparable mechanism for FORTRAN entry " "points, but there is a more comprehensive scheme used by, for example " "package @pkg{stats}. Most compilers which allow control of visibility will " "allow control of visibility for all symbols @emph{via} a flag, and where " "known the flag is encapsulated in the macros @samp{C_VISIBILITY} and " "@code{F77_VISIBILITY} for C and FORTRAN compilers. These are defined in " "@file{etc/Makeconf} and so available for normal compilation of package " "code. For example, @file{src/Makevars} could include" msgstr "" # #. type: example #: R-exts.texi:12730 #, no-wrap msgid "" "PKG_CFLAGS=$(C_VISIBILITY)\n" "PKG_FFLAGS=$(F77_VISIBILITY)\n" msgstr "" # #. type: Plain text #: R-exts.texi:12737 msgid "" "This would end up with @strong{no} visible entry points, which would be " "pointless. However, the effect of the flags can be overridden by using the " "@code{attribute_visible} prefix. A shared object which registers its entry " "points needs only for have one visible entry point, its initializer, so for " "example package @pkg{stats} has" msgstr "" # #. type: example #: R-exts.texi:12745 #, no-wrap msgid "" "void attribute_visible R_init_stats(DllInfo *dll)\n" "@{\n" " R_registerRoutines(dll, CEntries, CallEntries, FortEntries, NULL);\n" " R_useDynamicSymbols(dll, FALSE);\n" "...\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:12753 msgid "" "The visibility mechanism is not available on Windows, but there is an " "equally effective way to control which entry points are visible, by " "supplying a definitions file @file{@var{pkgnme}/src/@var{pkgname}-win.def}: " "only entry points listed in that file will be visible. Again using " "@pkg{stats} as an example, it has" msgstr "" # #. type: example #: R-exts.texi:12758 #, no-wrap msgid "" "LIBRARY stats.dll\n" "EXPORTS\n" " R_init_stats\n" msgstr "" # #. type: section #: R-exts.texi:12761 #, no-wrap msgid "Using these functions in your own C code" msgstr "" # #. type: Plain text #: R-exts.texi:12768 msgid "" "It is possible to build @code{Mathlib}, the @R{} set of mathematical " "functions documented in @file{Rmath.h}, as a standalone library " "@file{libRmath} under both Unix-alikes and Windows. (This includes the " "functions documented in @ref{Numerical analysis subroutines} as from that " "header file.)" msgstr "" # #. type: Plain text #: R-exts.texi:12773 msgid "" "The library is not built automatically when @R{} is installed, but can be " "built in the directory @file{src/nmath/standalone} in the @R{} sources: see " "the file @file{README} there. To use the code in your own C program include" msgstr "" # #. type: group #: R-exts.texi:12778 #, no-wrap msgid "" "#define MATHLIB_STANDALONE\n" "#include <Rmath.h>\n" msgstr "" # #. type: Plain text #: R-exts.texi:12784 msgid "" "and link against @samp{-lRmath} (and perhaps @samp{-lm}). There is an " "example file @file{test.c}." msgstr "" # #. type: Plain text #: R-exts.texi:12787 msgid "" "A little care is needed to use the random-number routines. You will need to " "supply the uniform random number generator" msgstr "" # #. type: example #: R-exts.texi:12790 #, no-wrap msgid "double unif_rand(void)\n" msgstr "" # #. type: Plain text #: R-exts.texi:12796 msgid "" "or use the one supplied (and with a dynamic library or DLL you will have to " "use the one supplied, which is the Marsaglia-multicarry with an entry points" msgstr "" # #. type: example #: R-exts.texi:12799 #, no-wrap msgid "set_seed(unsigned int, unsigned int)\n" msgstr "" # #. type: Plain text #: R-exts.texi:12803 msgid "to set its seeds and" msgstr "" # #. type: example #: R-exts.texi:12806 #, no-wrap msgid "get_seed(unsigned int *, unsigned int *)\n" msgstr "" # #. type: Plain text #: R-exts.texi:12810 msgid "to read the seeds)." msgstr "" # #. type: Plain text #: R-exts.texi:12817 msgid "" "The header files which @R{} installs are in directory " "@file{@var{R_INCLUDE_DIR}} (default @file{@var{R_HOME}/include}). This " "currently includes" msgstr "" # #. type: item #: R-exts.texi:12820 #, no-wrap msgid "@file{R.h} @tab includes many other files" msgstr "" # #. type: item #: R-exts.texi:12821 #, no-wrap msgid "@file{S.h} @tab different version for code ported from @Sl{}" msgstr "" # #. type: item #: R-exts.texi:12822 #, no-wrap msgid "@file{Rinternals.h} @tab definitions for using @R{}'s internal" msgstr "" # #. type: multitable #: R-exts.texi:12824 msgid "structures" msgstr "" # #. type: item #: R-exts.texi:12824 #, no-wrap msgid "@file{Rdefines.h} @tab macros for an @Sl{}-like interface to the" msgstr "" # #. type: multitable #: R-exts.texi:12826 msgid "above (no longer maintained)" msgstr "" # #. type: item #: R-exts.texi:12826 #, no-wrap msgid "@file{Rmath.h} @tab standalone math library" msgstr "" # #. type: item #: R-exts.texi:12827 #, no-wrap msgid "@file{Rversion.h} @tab @R{} version information" msgstr "" # #. type: item #: R-exts.texi:12828 #, no-wrap msgid "@file{Rinterface.h} @tab for add-on front-ends (Unix-alikes only)" msgstr "" # #. type: item #: R-exts.texi:12829 #, no-wrap msgid "@file{Rembedded.h} @tab for add-on front-ends" msgstr "" # #. type: item #: R-exts.texi:12830 #, no-wrap msgid "@file{R_ext/Applic.h} @tab optimization and integration" msgstr "" # #. type: item #: R-exts.texi:12831 #, no-wrap msgid "@file{R_ext/BLAS.h} @tab C definitions for BLAS routines" msgstr "" # #. type: item #: R-exts.texi:12832 #, no-wrap msgid "@file{R_ext/Callbacks.h} @tab C (and R function) top-level task" msgstr "" # #. type: multitable #: R-exts.texi:12834 msgid "handlers" msgstr "" # #. type: item #: R-exts.texi:12834 #, no-wrap msgid "@file{R_ext/GetX11Image.h} @tab X11Image interface used by package" msgstr "" # #. type: multitable #: R-exts.texi:12836 msgid "@pkg{trkplot}" msgstr "" # #. type: item #: R-exts.texi:12836 #, no-wrap msgid "@file{R_ext/Lapack.h} @tab C definitions for some LAPACK routines" msgstr "" # #. type: item #: R-exts.texi:12837 #, no-wrap msgid "@file{R_ext/Linpack.h} @tab C definitions for some LINPACK" msgstr "" # #. type: multitable #: R-exts.texi:12839 msgid "routines, not all of which are included in @R{}" msgstr "" # #. type: item #: R-exts.texi:12839 #, no-wrap msgid "@file{R_ext/Parse.h} @tab a small part of @R{}'s parse interface:" msgstr "" # #. type: multitable #: R-exts.texi:12841 msgid "not part of the stable API." msgstr "" # #. type: item #: R-exts.texi:12841 #, no-wrap msgid "@file{R_ext/RStartup.h} @tab for add-on front-ends" msgstr "" # #. type: item #: R-exts.texi:12842 #, no-wrap msgid "@file{R_ext/Rdynload.h} @tab needed to register compiled code in" msgstr "" # #. type: multitable #: R-exts.texi:12844 msgid "packages" msgstr "" # #. type: item #: R-exts.texi:12844 #, no-wrap msgid "@file{R_ext/R-ftp-http.h} @tab interface to internal method of" msgstr "" # #. type: code{#1} #: R-exts.texi:12846 msgid "download.file" msgstr "" # #. type: item #: R-exts.texi:12846 #, no-wrap msgid "@file{R_ext/Riconv.h} @tab interface to @code{iconv}" msgstr "" # #. type: item #: R-exts.texi:12847 #, no-wrap msgid "@file{R_ext/Visibility.h} @tab definitions controlling visibility" msgstr "" # #. type: item #: R-exts.texi:12848 #, no-wrap msgid "@file{R_ext/eventloop.h} @tab for add-on front-ends and for" msgstr "" # #. type: multitable #: R-exts.texi:12850 msgid "packages that need to share in the @R{} event loops (on all platforms)" msgstr "" # #. type: Plain text #: R-exts.texi:12854 msgid "The following headers are included by @file{R.h}:" msgstr "" # #. type: item #: R-exts.texi:12857 #, no-wrap msgid "@file{Rconfig.h} @tab configuration info that is made available" msgstr "" # #. type: item #: R-exts.texi:12858 #, no-wrap msgid "@file{R_ext/Arith.h} @tab handling for @code{NA}s, @code{NaN}s," msgstr "" # #. type: multitable #: R-exts.texi:12860 msgid "@code{Inf}/@code{-Inf}" msgstr "" # #. type: item #: R-exts.texi:12860 #, no-wrap msgid "@file{R_ext/Boolean.h} @tab @code{TRUE}/@code{FALSE} type" msgstr "" # #. type: item #: R-exts.texi:12861 #, no-wrap msgid "@file{R_ext/Complex.h} @tab C typedefs for @R{}'s @code{complex}" msgstr "" # #. type: item #: R-exts.texi:12862 #, no-wrap msgid "@file{R_ext/Constants.h} @tab constants" msgstr "" # #. type: item #: R-exts.texi:12863 #, no-wrap msgid "@file{R_ext/Error.h} @tab error handling" msgstr "" # #. type: item #: R-exts.texi:12864 #, no-wrap msgid "@file{R_ext/Memory.h} @tab memory allocation" msgstr "" # #. type: item #: R-exts.texi:12865 #, no-wrap msgid "@file{R_ext/Print.h} @tab @code{Rprintf} and variations." msgstr "" # #. type: item #: R-exts.texi:12866 #, no-wrap msgid "@file{R_ext/RS.h} @tab definitions common to @file{R.h} and" msgstr "" # #. type: multitable #: R-exts.texi:12868 msgid "@file{S.h}, including @code{F77_CALL} etc." msgstr "" # #. type: item #: R-exts.texi:12868 #, no-wrap msgid "@file{R_ext/Random.h} @tab random number generation" msgstr "" # #. type: item #: R-exts.texi:12869 #, no-wrap msgid "@file{R_ext/Utils.h} @tab sorting and other utilities" msgstr "" # #. type: item #: R-exts.texi:12870 #, no-wrap msgid "@file{R_ext/libextern.h} @tab definitions for exports from" msgstr "" # #. type: multitable #: R-exts.texi:12872 msgid "@file{R.dll} on Windows." msgstr "" # #. type: Plain text #: R-exts.texi:12881 msgid "" "The graphics systems are exposed in headers @file{R_ext/GraphicsEngine.h}, " "@file{R_ext/GraphicsDevice.h} (which it includes) and @file{R_ext/" "QuartzDevice.h}. Facilities for defining custom connection implementations " "are provided in @file{R_ext/Connections.h}, but make sure you consult the " "file before use." msgstr "" # #. type: Plain text #: R-exts.texi:12887 msgid "" "Let us re-iterate the advice to include system headers before the @R{} " "header files, especially @file{Rinternals.h} (included by @file{Rdefines.h}) " "and @file{Rmath.h}, which redefine names which may be used in system headers " "(fewer if @samp{R_NO_REMAP} is defined, or @samp{R_NO_REMAP_RMATH} for " "@file{Rmath.h}, as from @R{} 3.1.0)." msgstr "" # #. type: cindex #: R-exts.texi:12890 #, no-wrap msgid "Generic functions" msgstr "" # #. type: cindex #: R-exts.texi:12891 #, no-wrap msgid "Method functions" msgstr "" # #. type: Plain text #: R-exts.texi:12897 msgid "" "@R{} programmers will often want to add methods for existing generic " "functions, and may want to add new generic functions or make existing " "functions generic. In this chapter we give guidelines for doing so, with " "examples of the problems caused by not adhering to them." msgstr "" # #. type: Plain text #: R-exts.texi:12900 msgid "" "This chapter only covers the `informal' class system copied from S3, and not " "with the S4 (formal) methods of package @pkg{methods}." msgstr "" #. type: Plain text #: R-exts.texi:12905 msgid "" "First, a @emph{caveat}: a function named @code{@var{gen}.@var{cl}} will be " "invoked by the generic @code{@var{gen}} for class @code{@var{cl}}, so do not " "name functions in this style unless they are intended to be methods." msgstr "" # #. type: Plain text #: R-exts.texi:12910 msgid "" "The key function for methods is @code{NextMethod}, which dispatches the next " "method. It is quite typical for a method function to make a few changes to " "its arguments, dispatch to the next method, receive the results and modify " "them a little. An example is" msgstr "" # #. type: group #: R-exts.texi:12918 #, no-wrap msgid "" "t.data.frame <- function(x)\n" "@{\n" " x <- as.matrix(x)\n" " NextMethod(\"t\")\n" "@}\n" msgstr "" #. type: Plain text #: R-exts.texi:12925 msgid "" "Note that the example above works because there is a @emph{next} method, the " "default method, not that a new method is selected when the class is changed." msgstr "" # #. type: Plain text #: R-exts.texi:12932 msgid "" "@emph{Any} method a programmer writes may be invoked from another method by " "@code{NextMethod}, @emph{with the arguments appropriate to the previous " "method}. Further, the programmer cannot predict which method " "@code{NextMethod} will pick (it might be one not yet dreamt of), and the end " "user calling the generic needs to be able to pass arguments to the next " "method. For this to work" msgstr "" # #. type: emph{#1} #: R-exts.texi:12936 msgid "" "A method must have all the arguments of the generic, including " "@code{@dots{}} if the generic does." msgstr "" # #. type: Plain text #: R-exts.texi:12948 msgid "" "It is a grave misunderstanding to think that a method needs only to accept " "the arguments it needs. The original S version of @code{predict.lm} did not " "have a @code{@dots{}} argument, although @code{predict} did. It soon became " "clear that @code{predict.glm} needed an argument @code{dispersion} to handle " "over-dispersion. As @code{predict.lm} had neither a @code{dispersion} nor a " "@code{@dots{}} argument, @code{NextMethod} could no longer be used. (The " "legacy, two direct calls to @code{predict.lm}, lives on in @code{predict." "glm} in @R{}, which is based on the workaround for S3 written by Venables & " "Ripley.)" msgstr "" # #. type: Plain text #: R-exts.texi:12952 msgid "" "Further, the user is entitled to use positional matching when calling the " "generic, and the arguments to a method called by @code{UseMethod} are those " "of the call to the generic. Thus" msgstr "" # #. type: emph{#1} #: R-exts.texi:12956 msgid "A method must have arguments in exactly the same order as the generic." msgstr "" # #. type: Plain text #: R-exts.texi:12961 msgid "" "To see the scale of this problem, consider the generic function " "@code{scale}, defined as" msgstr "" # #. type: group #: R-exts.texi:12966 #, no-wrap msgid "" "scale <- function (x, center = TRUE, scale = TRUE)\n" " UseMethod(\"scale\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:12971 msgid "Suppose an unthinking package writer created methods such as" msgstr "" # #. type: example #: R-exts.texi:12974 #, no-wrap msgid "scale.foo <- function(x, scale = FALSE, ...) @{ @}\n" msgstr "" # #. type: Plain text #: R-exts.texi:12978 msgid "Then for @code{x} of class @code{\"foo\"} the calls" msgstr "" # #. type: group #: R-exts.texi:12983 #, no-wrap msgid "" "scale(x, , TRUE)\n" "scale(x, scale = TRUE)\n" msgstr "" # #. type: Plain text #: R-exts.texi:12989 msgid "" "would do most likely do different things, to the justifiable consternation " "of the end user." msgstr "" # #. type: Plain text #: R-exts.texi:12992 msgid "" "To add a further twist, which default is used when a user calls " "@code{scale(x)} in our example? What if" msgstr "" # #. type: example #: R-exts.texi:12995 #, no-wrap msgid "scale.bar <- function(x, center, scale = TRUE) NextMethod(\"scale\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:13002 msgid "" "and @code{x} has class @code{c(\"bar\", \"foo\")}? It is the default " "specified in the method that is used, but the default specified in the " "generic may be the one the user sees. This leads to the recommendation:" msgstr "" # #. type: emph{#1} #: R-exts.texi:13005 msgid "" "If the generic specifies defaults, all methods should use the same defaults." msgstr "" # #. type: Plain text #: R-exts.texi:13010 msgid "" "An easy way to follow these recommendations is to always keep generics " "simple, e.g." msgstr "" # #. type: example #: R-exts.texi:13013 #, no-wrap msgid "scale <- function(x, ...) UseMethod(\"scale\")\n" msgstr "" # #. type: Plain text #: R-exts.texi:13017 msgid "" "Only add parameters and defaults to the generic if they make sense in all " "possible methods implementing it." msgstr "" # #. type: section #: R-exts.texi:13020 #: R-exts.texi:13022 #: R-exts.texi:13023 #, no-wrap msgid "Adding new generics" msgstr "" # #. type: Plain text #: R-exts.texi:13030 msgid "" "When creating a new generic function, bear in mind that its argument list " "will be the maximal set of arguments for methods, including those written " "elsewhere years later. So choosing a good set of arguments may well be an " "important design issue, and there need to be good arguments @emph{not} to " "include a @code{@dots{}} argument." msgstr "" # #. type: Plain text #: R-exts.texi:13039 msgid "" "If a @code{@dots{}} argument is supplied, some thought should be given to " "its position in the argument sequence. Arguments which follow " "@code{@dots{}} must be named in calls to the function, and they must be " "named in full (partial matching is suppressed after @code{@dots{}}). Formal " "arguments before @code{@dots{}} can be partially matched, and so may " "`swallow' actual arguments intended for @code{@dots{}}. Although it is " "commonplace to make the @code{@dots{}} argument the last one, that is not " "always the right choice." msgstr "" # #. type: Plain text #: R-exts.texi:13046 msgid "" "Sometimes package writers want to make generic a function in the base " "package, and request a change in @R{}. This may be justifiable, but making " "a function generic with the old definition as the default method does have a " "small performance cost. It is never necessary, as a package can take over a " "function in the base package and make it generic by something like" msgstr "" # #. type: group #: R-exts.texi:13051 #, no-wrap msgid "" "foo <- function(object, ...) UseMethod(\"foo\")\n" "foo.default <- function(object, ...) base::foo(object)\n" msgstr "" # #. type: Plain text #: R-exts.texi:13059 msgid "" "Earlier versions of this manual suggested assigning @code{foo.default <- " "base::foo}. This is @strong{not} a good idea, as it captures the base " "function at the time of installation and it might be changed as @R{} is " "patched or updated." msgstr "" # #. type: Plain text #: R-exts.texi:13061 msgid "" "The same idea can be applied for functions in other packages with namespaces." msgstr "" #. type: Plain text #: R-exts.texi:13073 msgid "" "There are a number of ways to build front-ends to @R{}: we take this to mean " "a GUI or other application that has the ability to submit commands to @R{} " "and perhaps to receive results back (not necessarily in a text format). " "There are other routes besides those described here, for example the package " "@CRANpkg{Rserve} (from @acronym{CRAN}, see also @uref{https://www.rforge.net/" "@/Rserve/}) and connections to Java in @samp{JRI} (part of the " "@CRANpkg{rJava} package on @acronym{CRAN}) and the Omegahat/Bioconductor " "package @samp{SJava}." msgstr "" # #. type: Plain text #: R-exts.texi:13080 msgid "" "Note that the APIs described in this chapter are only intended to be used in " "an alternative front-end: they are not part of the API made available for " "@R{} packages and can be dangerous to use in a conventional package " "(although packages may contain alternative front-ends). Conversely some of " "the functions from the API (such as @code{R_alloc}) should not be used in " "front-ends." msgstr "" # #. type: node #: R-exts.texi:13084 #: R-exts.texi:13086 #: R-exts.texi:13087 #: R-exts.texi:13238 #: R-exts.texi:13307 #: R-exts.texi:13520 #: R-exts.texi:13541 #: R-exts.texi:13629 #: R-exts.texi:13669 #, no-wrap msgid "Embedding R under Unix-alikes" msgstr "" # #. type: node #: R-exts.texi:13084 #: R-exts.texi:13086 #: R-exts.texi:13669 #: R-exts.texi:13670 #: R-exts.texi:13682 #: R-exts.texi:13713 #: R-exts.texi:13918 #, no-wrap msgid "Embedding R under Windows" msgstr "" #. type: Plain text #: R-exts.texi:13098 msgid "" "@R{} can be built as a shared library@footnote{In the parlance of OS X this " "is a @emph{dynamic} library, and is the normal way to build @R{} on that " "platform.} if configured with @option{--enable-R-shlib}. This shared " "library can be used to run @R{} from alternative front-end programs. We " "will assume this has been done for the rest of this section. Also, it can " "be built as a static library if configured with @option{--enable-R-static-" "lib}, and that can be used in a very similar way (at least on Linux: on " "other platforms one needs to ensure that all the symbols exported by " "@file{libR.a} are linked into the front-end)." msgstr "" # #. type: Plain text #: R-exts.texi:13104 msgid "" "The command-line @R{} front-end, @file{@var{R_HOME}/bin/exec/R}, is one such " "example, and the former @acronym{GNOME} (see package @pkg{gnomeGUI} on " "@acronym{CRAN}'s @samp{Archive} area) and OS X consoles are others. The " "source for @file{@var{R_HOME}/bin/exec/R} is in file @file{src/main/Rmain.c} " "and is very simple" msgstr "" # #. type: example #: R-exts.texi:13108 #, no-wrap msgid "" "int Rf_initialize_R(int ac, char **av); /* in ../unix/system.c */\n" "void Rf_mainloop(); /* in main.c */\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13110 #, no-wrap msgid "" "extern int R_running_as_main_program; /* in ../unix/system.c */\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13118 #, no-wrap msgid "" "int main(int ac, char **av)\n" "@{\n" " R_running_as_main_program = 1;\n" " Rf_initialize_R(ac, av);\n" " Rf_mainloop(); /* does not return */\n" " return 0;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:13125 msgid "" "indeed, misleadingly simple. Remember that @file{@var{R_HOME}/bin/exec/R} " "is run from a shell script @file{@var{R_HOME}/bin/R} which sets up the " "environment for the executable, and this is used for" msgstr "" # #. type: itemize #: R-exts.texi:13131 msgid "" "Setting @env{R_HOME} and checking it is valid, as well as the path " "@env{R_SHARE_DIR} and @env{R_DOC_DIR} to the installed @file{share} and " "@file{doc} directory trees. Also setting @env{R_ARCH} if needed." msgstr "" # #. type: itemize #: R-exts.texi:13137 msgid "" "Setting @env{LD_LIBRARY_PATH} to include the directories used in linking " "@R{}. This is recorded as the default setting of @env{R_LD_LIBRARY_PATH} in " "the shell script @file{@var{R_HOME}/etc@var{R_ARCH}/ldpaths}." msgstr "" # #. type: itemize #: R-exts.texi:13141 msgid "" "Processing some of the arguments, for example to run @R{} under a debugger " "and to launch alternative front-ends to provide GUIs." msgstr "" # #. type: Plain text #: R-exts.texi:13146 msgid "" "The first two of these can be achieved for your front-end by running it " "@emph{via} @command{R CMD}. So, for example" msgstr "" # #. type: example #: R-exts.texi:13150 #, no-wrap msgid "" "R CMD /usr/local/lib/R/bin/exec/R\n" "R CMD exec/R\n" msgstr "" # #. type: Plain text #: R-exts.texi:13161 msgid "" "will both work in a standard @R{} installation. (@command{R CMD} looks first " "for executables in @file{@var{R_HOME}/bin}. These command-lines need " "modification if a sub-architecture is in use.) If you do not want to run " "your front-end in this way, you need to ensure that @env{R_HOME} is set and " "@env{LD_LIBRARY_PATH} is suitable. (The latter might well be, but modern " "Unix/Linux systems do not normally include @file{/usr/local/lib} (@file{/usr/" "local/lib64} on some architectures), and @R{} does look there for system " "components.)" msgstr "" # #. type: Plain text #: R-exts.texi:13169 msgid "" "The other senses in which this example is too simple are that all the " "internal defaults are used and that control is handed over to the @R{} main " "loop. There are a number of small examples@footnote{but these are not part " "of the automated test procedures and so little tested.} in the @file{tests/" "Embedding} directory. These make use of @code{Rf_initEmbeddedR} in " "@file{src/main/Rembedded.c}, and essentially use" msgstr "" # #. type: example #: R-exts.texi:13171 #, no-wrap msgid "" "#include <Rembedded.h>\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13177 #, no-wrap msgid "" "int main(int ac, char **av)\n" "@{\n" " /* do some setup */\n" " Rf_initEmbeddedR(argc, argv);\n" " /* do some more setup */\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13180 #, no-wrap msgid "" " /* submit some code to R, which is done interactively via\n" "\trun_Rmainloop();\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13182 #, no-wrap msgid "" "\tA possible substitute for a pseudo-console is\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13187 #, no-wrap msgid "" "\tR_ReplDLLinit();\n" "\twhile(R_ReplDLLdo1() > 0) @{\n" "\t/* add user actions here if desired */\n" " @}\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13193 #, no-wrap msgid "" " */\n" " Rf_endEmbeddedR(0);\n" " /* final tidying up after R is shutdown */\n" " return 0;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:13198 msgid "" "If you do not want to pass @R{} arguments, you can fake an @code{argv} " "array, for example by" msgstr "" # #. type: example #: R-exts.texi:13202 #, no-wrap msgid "" " char *argv[]= @{\"REmbeddedPostgres\", \"--silent\"@};\n" " Rf_initEmbeddedR(sizeof(argv)/sizeof(argv[0]), argv);\n" msgstr "" # #. type: Plain text #: R-exts.texi:13207 msgid "" "However, to make a GUI we usually do want to run @code{run_Rmainloop} after " "setting up various parts of @R{} to talk to our GUI, and arranging for our " "GUI callbacks to be called during the @R{} mainloop." msgstr "" # #. type: Plain text #: R-exts.texi:13211 msgid "" "One issue to watch is that on some platforms @code{Rf_initEmbeddedR} and " "@code{Rf_endEmbeddedR} change the settings of the FPU (e.g.@: to allow " "errors to be trapped and to make use of extended precision registers)." msgstr "" # #. type: Plain text #: R-exts.texi:13217 msgid "" "The standard code sets up a session temporary directory in the usual way, " "@emph{unless} @code{R_TempDir} is set to a non-NULL value before " "@code{Rf_initEmbeddedR} is called. In that case the value is assumed to " "contain an existing writable directory (no check is done), and it is not " "cleaned up when @R{} is shut down." msgstr "" # #. type: Plain text #: R-exts.texi:13221 msgid "" "@code{Rf_initEmbeddedR} sets @R{} to be in interactive mode: you can set " "@code{R_Interactive} (defined in @file{Rinterface.h}) subsequently to change " "this." msgstr "" # #. type: Plain text #: R-exts.texi:13225 msgid "" "Note that @R{} expects to be run with the locale category @samp{LC_NUMERIC} " "set to its default value of @code{C}, and so should not be embedded into an " "application which changes that." msgstr "" # #. type: Plain text #: R-exts.texi:13229 msgid "" "It is the user's responsibility to attempt to initialize only once. To " "protect the @R{} interpreter, @code{Rf_initialize_R} will exit the process " "if re-initialization is attempted." msgstr "" # #. type: node #: R-exts.texi:13236 #: R-exts.texi:13238 #: R-exts.texi:13239 #: R-exts.texi:13307 #, no-wrap msgid "Compiling against the R library" msgstr "" # #. type: node #: R-exts.texi:13236 #: R-exts.texi:13238 #: R-exts.texi:13307 #: R-exts.texi:13308 #: R-exts.texi:13520 #, no-wrap msgid "Setting R callbacks" msgstr "" # #. type: node #: R-exts.texi:13236 #: R-exts.texi:13307 #: R-exts.texi:13520 #: R-exts.texi:13521 #: R-exts.texi:13541 #, no-wrap msgid "Registering symbols" msgstr "" # #. type: node #: R-exts.texi:13236 #: R-exts.texi:13520 #: R-exts.texi:13541 #: R-exts.texi:13542 #: R-exts.texi:13629 #, no-wrap msgid "Meshing event loops" msgstr "" # #. type: subsection #: R-exts.texi:13236 #: R-exts.texi:13541 #: R-exts.texi:13629 #: R-exts.texi:13630 #, no-wrap msgid "Threading issues" msgstr "" # #. type: Plain text #: R-exts.texi:13243 msgid "" "Suitable flags to compile and link against the @R{} (shared or static) " "library can be found by" msgstr "" # #. type: example #: R-exts.texi:13247 #, no-wrap msgid "" "R CMD config --cppflags\n" "R CMD config --ldflags\n" msgstr "" # #. type: Plain text #: R-exts.texi:13251 msgid "(These apply only to an uninstalled copy or a standard install.)" msgstr "" # #. type: Plain text #: R-exts.texi:13255 msgid "" "If @R{} is installed, @code{pkg-config} is available and neither sub-" "architectures nor an OS X framework have been used, alternatives for a " "shared @R{} library are" msgstr "" # #. type: example #: R-exts.texi:13259 #, no-wrap msgid "" "pkg-config --cflags libR\n" "pkg-config --libs libR\n" msgstr "" # #. type: Plain text #: R-exts.texi:13263 msgid "and for a static @R{} library" msgstr "" # #. type: example #: R-exts.texi:13267 #, no-wrap msgid "" "pkg-config --cflags libR\n" "pkg-config --libs --static libR\n" msgstr "" # #. type: Plain text #: R-exts.texi:13273 msgid "" "(This may work for an installed OS framework if @code{pkg-config} is taught " "where to look for @file{libR.pc}: it is installed inside the framework.)" msgstr "" # #. type: Plain text #: R-exts.texi:13277 msgid "" "However, a more comprehensive way is to set up a @file{Makefile} to compile " "the front-end. Suppose file @file{myfe.c} is to be compiled to @file{myfe}. " "A suitable @file{Makefile} might be" msgstr "" # #. type: example #: R-exts.texi:13281 #, no-wrap msgid "" "include $@{R_HOME@}/etc$@{R_ARCH@}/Makeconf\n" "all: myfe\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13285 #, no-wrap msgid "" "## The following is not needed, but avoids PIC flags.\n" "myfe.o: myfe.c\n" " $(CC) $(ALL_CPPFLAGS) $(CFLAGS) -c myfe.c -o $@@\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13289 #, no-wrap msgid "" "## replace $(LIBR) $(LIBS) by $(STATIC_LIBR) if R was build with a static libR\n" "myfe: myfe.o\n" " $(MAIN_LINK) -o $@@ myfe.o $(LIBR) $(LIBS)\n" msgstr "" # #. type: Plain text #: R-exts.texi:13293 msgid "invoked as" msgstr "" # #. type: example #: R-exts.texi:13297 #, no-wrap msgid "" "R CMD make\n" "R CMD myfe\n" msgstr "" # #. type: Plain text #: R-exts.texi:13306 msgid "" "Additional flags which @code{$(MAIN_LINK)} includes are, amongst others, " "those to select OpenMP and @option{--export-dynamic} for the GNU linker on " "some platforms. In principle @code{$(LIBS)} is not needed when using a " "shared @R{} library as @file{libR} is linked against those libraries, but " "some platforms need the executable also linked against them." msgstr "" # #. type: Plain text #: R-exts.texi:13314 msgid "" "For Unix-alikes there is a public header file @file{Rinterface.h} that makes " "it possible to change the standard callbacks used by @R{} in a documented " "way. This defines pointers (if @code{R_INTERFACE_PTRS} is defined)" msgstr "" # #. type: example #: R-exts.texi:13339 #, no-wrap msgid "" "extern void (*ptr_R_Suicide)(const char *);\n" "extern void (*ptr_R_ShowMessage)(const char *);\n" "extern int (*ptr_R_ReadConsole)(const char *, unsigned char *, int, int);\n" "extern void (*ptr_R_WriteConsole)(const char *, int);\n" "extern void (*ptr_R_WriteConsoleEx)(const char *, int, int);\n" "extern void (*ptr_R_ResetConsole)();\n" "extern void (*ptr_R_FlushConsole)();\n" "extern void (*ptr_R_ClearerrConsole)();\n" "extern void (*ptr_R_Busy)(int);\n" "extern void (*ptr_R_CleanUp)(SA_TYPE, int, int);\n" "extern int (*ptr_R_ShowFiles)(int, const char **, const char **,\n" " const char *, Rboolean, const char *);\n" "extern int (*ptr_R_ChooseFile)(int, char *, int);\n" "extern int (*ptr_R_EditFile)(const char *);\n" "extern void (*ptr_R_loadhistory)(SEXP, SEXP, SEXP, SEXP);\n" "extern void (*ptr_R_savehistory)(SEXP, SEXP, SEXP, SEXP);\n" "extern void (*ptr_R_addhistory)(SEXP, SEXP, SEXP, SEXP);\n" "// added in R 3.0.0\n" "extern int (*ptr_R_EditFiles)(int, const char **, const char **, const char *);\n" "extern SEXP (*ptr_do_selectlist)(SEXP, SEXP, SEXP, SEXP);\n" "extern SEXP (*ptr_do_dataentry)(SEXP, SEXP, SEXP, SEXP);\n" "extern SEXP (*ptr_do_dataviewer)(SEXP, SEXP, SEXP, SEXP);\n" "extern void (*ptr_R_ProcessEvents)();\n" msgstr "" # #. type: Plain text #: R-exts.texi:13344 msgid "" "which allow standard @R{} callbacks to be redirected to your GUI. What " "these do is generally documented in the file @file{src/unix/system.txt}." msgstr "" # #. type: deftypefun #: R-exts.texi:13345 #, no-wrap msgid "void R_ShowMessage (char *@var{message})" msgstr "" # #. type: deftypefun #: R-exts.texi:13348 msgid "" "This should display the message, which may have multiple lines: it should be " "brought to the user's attention immediately." msgstr "" # #. type: deftypefun #: R-exts.texi:13350 #, no-wrap msgid "void R_Busy (int @var{which})" msgstr "" # #. type: deftypefun #: R-exts.texi:13354 msgid "" "This function invokes actions (such as change of cursor) when @R{} embarks " "on an extended computation (@code{@var{which}=1}) and when such a state " "terminates (@code{@var{which}=0})." msgstr "" # #. type: deftypefun #: R-exts.texi:13356 #, no-wrap msgid "int R_ReadConsole (const char *@var{prompt}, unsigned char *@var{buf}, @" msgstr "" # #. type: deftypefun #: R-exts.texi:13358 msgid "int @var{buflen}, int @var{hist})" msgstr "" # #. type: deftypefunx #: R-exts.texi:13358 #, no-wrap msgid "void R_WriteConsole (const char *@var{buf}, int @var{buflen})" msgstr "" # #. type: deftypefunx #: R-exts.texi:13359 #, no-wrap msgid "void R_WriteConsoleEx (const char *@var{buf}, int @var{buflen}, int @var{otype})" msgstr "" # #. type: deftypefunx #: R-exts.texi:13360 #, no-wrap msgid "void R_ResetConsole ()" msgstr "" # #. type: deftypefunx #: R-exts.texi:13361 #, no-wrap msgid "void R_FlushConsole ()" msgstr "" # #. type: deftypefunx #: R-exts.texi:13362 #, no-wrap msgid "void R_ClearErrConsole ()" msgstr "" # #. type: deftypefun #: R-exts.texi:13365 msgid "These functions interact with a console." msgstr "" # #. type: deftypefun #: R-exts.texi:13373 msgid "" "@code{R_ReadConsole} prints the given prompt at the console and then does a " "@code{fgets(3)}--like operation, transferring up to @var{buflen} characters " "into the buffer @var{buf}. The last two bytes should be set to @samp{\"\\n" "\\0\"} to preserve sanity. If @var{hist} is non-zero, then the line should " "be added to any command history which is being maintained. The return value " "is 0 is no input is available and >0 otherwise." msgstr "" # #. type: deftypefun #: R-exts.texi:13382 msgid "" "@code{R_WriteConsoleEx} writes the given buffer to the console, @var{otype} " "specifies the output type (regular output or warning/error). Call to " "@code{R_WriteConsole(buf, buflen)} is equivalent to " "@code{R_WriteConsoleEx(buf, buflen, 0)}. To ensure backward compatibility of " "the callbacks, @code{ptr_R_WriteConsoleEx} is used only if " "@code{ptr_R_WriteConsole} is set to @code{NULL}. To ensure that " "@code{stdout()} and @code{stderr()} connections point to the console, set " "the corresponding files to @code{NULL} @emph{via}" msgstr "" # #. type: example #: R-exts.texi:13385 #, no-wrap msgid "" " R_Outputfile = NULL;\n" " R_Consolefile = NULL;\n" msgstr "" # #. type: deftypefun #: R-exts.texi:13391 msgid "" "@code{R_ResetConsole} is called when the system is reset after an error. " "@code{R_FlushConsole} is called to flush any pending output to the system " "console. @code{R_ClearerrConsole} clears any errors associated with reading " "from the console." msgstr "" # #. type: deftypefun #: R-exts.texi:13393 #, no-wrap msgid "int R_ShowFiles (int @var{nfile}, const char **@var{file}, @" msgstr "" # #. type: deftypefun #: R-exts.texi:13396 msgid "" "const char **@var{headers}, const char *@var{wtitle}, Rboolean @var{del}, @ " "const char *@var{pager})" msgstr "" # #. type: deftypefun #: R-exts.texi:13398 msgid "This function is used to display the contents of files." msgstr "" # #. type: deftypefun #: R-exts.texi:13400 #, no-wrap msgid "int R_ChooseFile (int @var{new}, char *@var{buf}, @" msgstr "" # #. type: deftypefun #: R-exts.texi:13402 msgid "int @var{len})" msgstr "" # #. type: deftypefun #: R-exts.texi:13405 msgid "" "Choose a file and return its name in @var{buf} of length @var{len}. Return " "value is 0 for success, > 0 otherwise." msgstr "" # #. type: deftypefun #: R-exts.texi:13407 #, no-wrap msgid "int R_EditFile (const char *@var{buf})" msgstr "" # #. type: deftypefun #: R-exts.texi:13409 msgid "Send a file to an editor window." msgstr "" # #. type: deftypefun #: R-exts.texi:13411 #, no-wrap msgid "int R_EditFiles (int @var{nfile}, const char **@var{file}, const char **@var{title}, const char *@var{editor})" msgstr "" # #. type: deftypefun #: R-exts.texi:13414 msgid "" "Send @var{nfile} files to an editor, with titles possibly to be used for the " "editor window(s)." msgstr "" # #. type: deftypefun #: R-exts.texi:13416 #, no-wrap msgid "SEXP R_loadhistory (SEXP, SEXP, SEXP, SEXP);" msgstr "" # #. type: deftypefunx #: R-exts.texi:13417 #, no-wrap msgid "SEXP R_savehistory (SEXP, SEXP, SEXP, SEXP);" msgstr "" # #. type: deftypefunx #: R-exts.texi:13418 #, no-wrap msgid "SEXP R_addhistory (SEXP, SEXP, SEXP, SEXP);" msgstr "" # #. type: deftypefun #: R-exts.texi:13422 msgid "" "@code{.Internal} functions for @code{loadhistory}, @code{savehistory} and " "@code{timestamp}." msgstr "" # #. type: deftypefun #: R-exts.texi:13425 msgid "If the console has no history mechanism these can be as simple as" msgstr "" # #. type: example #: R-exts.texi:13441 #, no-wrap msgid "" "SEXP R_loadhistory (SEXP call, SEXP op, SEXP args, SEXP env)\n" "@{\n" " errorcall(call, \"loadhistory is not implemented\");\n" " return R_NilValue;\n" "@}\n" "SEXP R_savehistory (SEXP call, SEXP op , SEXP args, SEXP env)\n" "@{\n" " errorcall(call, \"savehistory is not implemented\");\n" " return R_NilValue;\n" "@}\n" "SEXP R_addhistory (SEXP call, SEXP op , SEXP args, SEXP env)\n" "@{\n" " return R_NilValue;\n" "@}\n" msgstr "" # #. type: deftypefun #: R-exts.texi:13446 msgid "" "The @code{R_addhistory} function should return silently if no history " "mechanism is present, as a user may be calling @code{timestamp} purely to " "write the time stamp to the console." msgstr "" # #. type: deftypefun #: R-exts.texi:13448 #, no-wrap msgid "void R_Suicide (const char *@var{message})" msgstr "" # #. type: deftypefun #: R-exts.texi:13451 msgid "" "This should abort @R{} as rapidly as possible, displaying the message. A " "possible implementation is" msgstr "" # #. type: example #: R-exts.texi:13460 #, no-wrap msgid "" "void R_Suicide (const char *message)\n" "@{\n" " char pp[1024];\n" " snprintf(pp, 1024, \"Fatal error: %s\\n\", s);\n" " R_ShowMessage(pp);\n" " R_CleanUp(SA_SUICIDE, 2, 0);\n" "@}\n" msgstr "" # #. type: deftypefun #: R-exts.texi:13463 #, no-wrap msgid "void R_CleanUp (SA_TYPE @var{saveact}, int @var{status}, @" msgstr "" # #. type: deftypefun #: R-exts.texi:13465 msgid "int @var{RunLast})" msgstr "" # #. type: deftypefun #: R-exts.texi:13468 msgid "" "This function invokes any actions which occur at system termination. It " "needs to be quite complex:" msgstr "" # #. type: example #: R-exts.texi:13472 #, no-wrap msgid "" "#include <Rinterface.h>\n" "#include <Rembedded.h> /* for Rf_KillAllDevices */\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13492 #, no-wrap msgid "" "void R_CleanUp (SA_TYPE saveact, int status, int RunLast)\n" "@{\n" " if(saveact == SA_DEFAULT) saveact = SaveAction;\n" " if(saveact == SA_SAVEASK) @{\n" " /* ask what to do and set saveact */\n" " @}\n" " switch (saveact) @{\n" " case SA_SAVE:\n" " if(runLast) R_dot_Last();\n" " if(R_DirtyImage) R_SaveGlobalEnv();\n" " /* save the console history in R_HistoryFile */\n" " break;\n" " case SA_NOSAVE:\n" " if(runLast) R_dot_Last();\n" " break;\n" " case SA_SUICIDE:\n" " default:\n" " break;\n" " @}\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13495 #, no-wrap msgid "" " R_RunExitFinalizers();\n" " /* clean up after the editor e.g. CleanEd() */\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13497 #, no-wrap msgid "" " R_CleanTempDir();\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13501 #, no-wrap msgid "" " /* close all the graphics devices */\n" " if(saveact != SA_SUICIDE) Rf_KillAllDevices();\n" " fpu_setup(FALSE);\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13504 #, no-wrap msgid "" " exit(status);\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:13509 msgid "" "These callbacks should never be changed in a running @R{} session (and hence " "cannot be called from an extension package)." msgstr "" # #. type: deftypefun #: R-exts.texi:13510 #, no-wrap msgid "SEXP R_dataentry (SEXP, SEXP, SEXP, SEXP);" msgstr "" # #. type: deftypefunx #: R-exts.texi:13511 #, no-wrap msgid "SEXP R_dataviewer (SEXP, SEXP, SEXP, SEXP);" msgstr "" # #. type: deftypefunx #: R-exts.texi:13512 #, no-wrap msgid "SEXP R_selectlist (SEXP, SEXP, SEXP, SEXP);" msgstr "" # #. type: deftypefun #: R-exts.texi:13517 msgid "" "@code{.External} functions for @code{dataentry} (and @code{edit} on matrices " "and data frames), @code{View} and @code{select.list}. These can be changed " "if they are not currently in use." msgstr "" # #. type: Plain text #: R-exts.texi:13530 msgid "" "An application embedding @R{} needs a different way of registering symbols " "because it is not a dynamic library loaded by @R{} as would be the case with " "a package. Therefore @R{} reserves a special @code{DllInfo} entry for the " "embedding application such that it can register symbols to be used with " "@code{.C}, @code{.Call} etc. This entry can be obtained by calling " "@code{getEmbeddingDllInfo}, so a typical use is" msgstr "" # #. type: example #: R-exts.texi:13534 #, no-wrap msgid "" "DllInfo *info = R_getEmbeddingDllInfo();\n" "R_registerRoutines(info, cMethods, callMethods, NULL, NULL);\n" msgstr "" # #. type: Plain text #: R-exts.texi:13539 msgid "" "The native routines defined by @code{cMethods} and @code{callMethods} should " "be present in the embedding application. See @ref{Registering native " "routines} for details on registering symbols in general." msgstr "" # #. type: Plain text #: R-exts.texi:13547 msgid "" "One of the most difficult issues in interfacing @R{} to a front-end is the " "handling of event loops, at least if a single thread is used. @R{} uses " "events and timers for" msgstr "" # #. type: itemize #: R-exts.texi:13552 msgid "" "Running X11 windows such as the graphics device and data editor, and " "interacting with them (e.g., using @code{locator()})." msgstr "" # #. type: itemize #: R-exts.texi:13556 msgid "" "Supporting Tcl/Tk events for the @pkg{tcltk} package (for at least the X11 " "version of Tk)." msgstr "" # #. type: itemize #: R-exts.texi:13559 msgid "Preparing input." msgstr "" # #. type: itemize #: R-exts.texi:13563 msgid "" "Timing operations, for example for profiling @R{} code and @code{Sys." "sleep()}." msgstr "" # #. type: itemize #: R-exts.texi:13566 msgid "Interrupts, where permitted." msgstr "" # #. type: Plain text #: R-exts.texi:13571 msgid "" "Specifically, the Unix-alike command-line version of @R{} runs separate " "event loops for" msgstr "" # #. type: itemize #: R-exts.texi:13576 msgid "" "Preparing input at the console command-line, in file @file{src/unix/sys-unix." "c}." msgstr "" # #. type: itemize #: R-exts.texi:13584 msgid "" "Waiting for a response from a socket in the internal functions underlying " "FTP and HTTP transfers in @code{download.file()} and for direct socket " "access, in files @file{src/@/modules/@/internet/@/nanoftp.c}, @file{src/@/" "modules/@/internet/@/nanohttp.c} and @file{src/@/modules/@/internet/@/Rsock." "c}" msgstr "" # #. type: itemize #: R-exts.texi:13589 msgid "" "Mouse and window events when displaying the X11-based dataentry window, in " "file @file{src/modules/X11/dataentry.c}. This is regarded as @emph{modal}, " "and no other events are serviced whilst it is active." msgstr "" # #. type: Plain text #: R-exts.texi:13599 msgid "" "There is a protocol for adding event handlers to the first two types of " "event loops, using types and functions declared in the header @file{R_ext/" "eventloop.h} and described in comments in file @file{src/unix/sys-std.c}. " "It is possible to add (or remove) an input handler for events on a " "particular file descriptor, or to set a polling interval (@emph{via} " "@code{R_wait_usec}) and a function to be called periodically @emph{via} " "@code{R_PolledEvents}: the polling mechanism is used by the @pkg{tcltk} " "package." msgstr "" # #. type: Plain text #: R-exts.texi:13603 msgid "" "It is not intended that these facilities are used by packages, but if they " "are needed exceptionally, the package should ensure that it cleans up and " "removes its handlers when its namespace is unloaded." msgstr "" # #. type: Plain text #: R-exts.texi:13609 msgid "" "An alternative front-end needs both to make provision for other @R{} events " "whilst waiting for input, and to ensure that it is not frozen out during " "events of the second type. This is not handled very well in the existing " "examples. The GNOME front-end ran a private handler for polled events by " "setting" msgstr "" # #. type: example #: R-exts.texi:13613 #, no-wrap msgid "" "extern int (*R_timeout_handler)();\n" "extern long R_timeout_val;\n" "\n" msgstr "" # #. type: example #: R-exts.texi:13617 #, no-wrap msgid "" " if (R_timeout_handler && R_timeout_val)\n" " gtk_timeout_add(R_timeout_val, R_timeout_handler, NULL);\n" " gtk_main ();\n" msgstr "" # #. type: Plain text #: R-exts.texi:13627 msgid "" "whilst it is waiting for console input. This obviously handles events for " "Gtk windows (such as the graphics device in the @pkg{gtkDevice} package), " "but not X11 events (such as the @code{X11()} device) or for other event " "handlers that might have been registered with @R{}. It does not attempt to " "keep itself alive whilst @R{} is waiting on sockets. The ability to add a " "polled handler as @code{R_timeout_handler} is used by the @pkg{tcltk} " "package." msgstr "" # #. type: Plain text #: R-exts.texi:13637 msgid "" "Embedded @R{} is designed to be run in the main thread, and all the testing " "is done in that context. There is a potential issue with the stack-checking " "mechanism where threads are involved. This uses two variables declared in " "@file{Rinterface.h} (if @code{CSTACK_DEFNS} is defined) as" msgstr "" # #. type: example #: R-exts.texi:13641 #, no-wrap msgid "" "extern uintptr_t R_CStackLimit; /* C stack limit */\n" "extern uintptr_t R_CStackStart; /* Initial stack address */\n" msgstr "" # #. type: Plain text #: R-exts.texi:13647 msgid "" "Note that @code{uintptr_t} is a C99 type for which a substitute is defined " "in @R{}, so your code needs to define @code{HAVE_UINTPTR_T} appropriately." msgstr "" #. type: Plain text #: R-exts.texi:13658 msgid "" "These will be set@footnote{at least on platforms where the values are " "available, that is having @code{getrlimit} and on Linux or having " "@code{sysctl} supporting @code{KERN_USRSTACK}, including FreeBSD and OS X.} " "when @code{Rf_initialize_R} is called, to values appropriate to the main " "thread. Stack-checking can be disabled by setting @code{R_CStackLimit = " "(uintptr_t)-1} immediately after @code{Rf_initialize_R} is called, but it is " "better to if possible set appropriate values. (What these are and how to " "determine them are OS-specific, and the stack size limit may differ for " "secondary threads. If you have a choice of stack size, at least 10Mb is " "recommended.)" msgstr "" # #. type: Plain text #: R-exts.texi:13664 msgid "" "You may also want to consider how signals are handled: @R{} sets signal " "handlers for several signals, including @code{SIGINT}, @code{SIGSEGV}, " "@code{SIGPIPE}, @code{SIGUSR1} and @code{SIGUSR2}, but these can all be " "suppressed by setting the variable @code{R_SignalHandlers} (declared in " "@file{Rinterface.h}) to @code{0}." msgstr "" # #. type: Plain text #: R-exts.texi:13668 msgid "" "Note that these variables must not be changed by an @R{} @strong{package}: a " "package should not calling @R{} internals which makes use of the stack-" "checking mechanism on a secondary thread." msgstr "" # #. type: Plain text #: R-exts.texi:13675 msgid "" "All Windows interfaces to @R{} call entry points in the DLL @file{R.dll}, " "directly or indirectly. Simpler applications may find it easier to use the " "indirect route @emph{via} @acronym{(D)COM}." msgstr "" # #. type: node #: R-exts.texi:13680 #: R-exts.texi:13682 #: R-exts.texi:13683 #: R-exts.texi:13713 #, no-wrap msgid "Using (D)COM" msgstr "" # #. type: node #: R-exts.texi:13680 #: R-exts.texi:13682 #: R-exts.texi:13713 #: R-exts.texi:13714 #: R-exts.texi:13918 #, no-wrap msgid "Calling R.dll directly" msgstr "" # #. type: subsection #: R-exts.texi:13680 #: R-exts.texi:13713 #: R-exts.texi:13918 #: R-exts.texi:13919 #, no-wrap msgid "Finding R_HOME" msgstr "" # #. type: Plain text #: R-exts.texi:13693 msgid "" "@acronym{(D)COM} is a standard Windows mechanism used for communication " "between Windows applications. One application (here @R{}) is run as COM " "server which offers services to clients, here the front-end calling " "application. The services are described in a `Type Library' and are (more " "or less) language-independent, so the calling application can be written in " "C or C++ or Visual Basic or Perl or Python and so on. The `D' in (D)COM " "refers to `distributed', as the client and server can be running on " "different machines." msgstr "" # #. type: Plain text #: R-exts.texi:13697 msgid "" "The basic @R{} distribution is not a (D)COM server, but two addons are " "currently available that interface directly with @R{} and provide a (D)COM " "server:" msgstr "" # #. type: itemize #: R-exts.texi:13704 msgid "" "There is a (D)COM server called @code{StatConnector} written by Thomas Baier " "available @emph{via} @uref{http://sunsite.univie.ac.at/rcom/}, which works " "with @R{} packages to support transfer of data to and from @R{} and remote " "execution of @R{} commands, as well as embedding of an @R{} graphics window." msgstr "" # #. type: itemize #: R-exts.texi:13706 msgid "Recent versions have usage restrictions." msgstr "" # #. type: itemize #: R-exts.texi:13712 msgid "" "Another (D)COM server, @code{RDCOMServer}, is available from @uref{http://" "www.omegahat.org/}. Its philosophy is discussed in @uref{http://www." "omegahat.org/@/RDCOMServer/@/Docs/@/Paradigm.html} and is very different " "from the purpose of this section." msgstr "" # #. type: Plain text #: R-exts.texi:13719 msgid "" "The @code{R} DLL is mainly written in C and has @code{_cdecl} entry points. " "Calling it directly will be tricky except from C code (or C++ with a little " "care)." msgstr "" # #. type: Plain text #: R-exts.texi:13721 msgid "There is a version of the Unix-alike interface calling" msgstr "" # #. type: example #: R-exts.texi:13725 #, no-wrap msgid "" "int Rf_initEmbeddedR(int ac, char **av);\n" "void Rf_endEmbeddedR(int fatal);\n" msgstr "" # #. type: Plain text #: R-exts.texi:13732 msgid "" "which is an entry point in @file{R.dll}. Examples of its use (and a " "suitable @file{Makefile.win}) can be found in the @file{tests/Embedding} " "directory of the sources. You may need to ensure that @file{@var{R_HOME}/" "bin} is in your @env{PATH} so the @R{} DLLs are found." msgstr "" # #. type: Plain text #: R-exts.texi:13736 msgid "" "Examples of calling @file{R.dll} directly are provided in the directory " "@file{src/@/gnuwin32/@/front-ends}, including a simple command-line front " "end @file{rtest.c} whose code is" msgstr "" # #. type: smallexample #: R-exts.texi:13747 #, no-wrap msgid "" "#define Win32\n" "#include <windows.h>\n" "#include <stdio.h>\n" "#include <Rversion.h>\n" "#define LibExtern __declspec(dllimport) extern\n" "#include <Rembedded.h>\n" "#include <R_ext/RStartup.h>\n" "/* for askok and askyesnocancel */\n" "#include <graphapp.h>\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13750 #, no-wrap msgid "" "/* for signal-handling code */\n" "#include <psignal.h>\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13752 #, no-wrap msgid "" "/* simple input, simple output */\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13763 #, no-wrap msgid "" "/* This version blocks all events: a real one needs to call ProcessEvents\n" " frequently. See rterm.c and ../system.c for one approach using\n" " a separate thread for input.\n" "*/\n" "int myReadConsole(const char *prompt, char *buf, int len, int addtohistory)\n" "@{\n" " fputs(prompt, stdout);\n" " fflush(stdout);\n" " if(fgets(buf, len, stdin)) return 1; else return 0;\n" "@}\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13768 #, no-wrap msgid "" "void myWriteConsole(const char *buf, int len)\n" "@{\n" " printf(\"%s\", buf);\n" "@}\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13773 #, no-wrap msgid "" "void myCallBack(void)\n" "@{\n" " /* called during i/o, eval, graphics in ProcessEvents */\n" "@}\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13778 #, no-wrap msgid "" "void myBusy(int which)\n" "@{\n" " /* set a busy cursor ... if which = 1, unset if which = 0 */\n" "@}\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13780 #, no-wrap msgid "" "static void my_onintr(int sig) @{ UserBreak = 1; @}\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13786 #, no-wrap msgid "" "int main (int argc, char **argv)\n" "@{\n" " structRstart rp;\n" " Rstart Rp = &rp;\n" " char Rversion[25], *RHome;\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13792 #, no-wrap msgid "" " sprintf(Rversion, \"%s.%s\", R_MAJOR, R_MINOR);\n" " if(strcmp(getDLLVersion(), Rversion) != 0) @{\n" " fprintf(stderr, \"Error: R.DLL version does not match\\n\");\n" " exit(1);\n" " @}\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13808 #, no-wrap msgid "" " R_setStartTime();\n" " R_DefParams(Rp);\n" " if((RHome = get_R_HOME()) == NULL) @{\n" " fprintf(stderr, \"R_HOME must be set in the environment or Registry\\n\");\n" " exit(1);\n" " @}\n" " Rp->rhome = RHome;\n" " Rp->home = getRUser();\n" " Rp->CharacterMode = LinkDLL;\n" " Rp->ReadConsole = myReadConsole;\n" " Rp->WriteConsole = myWriteConsole;\n" " Rp->CallBack = myCallBack;\n" " Rp->ShowMessage = askok;\n" " Rp->YesNoCancel = askyesnocancel;\n" " Rp->Busy = myBusy;\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13815 #, no-wrap msgid "" " Rp->R_Quiet = TRUE; /* Default is FALSE */\n" " Rp->R_Interactive = FALSE; /* Default is TRUE */\n" " Rp->RestoreAction = SA_RESTORE;\n" " Rp->SaveAction = SA_NOSAVE;\n" " R_SetParams(Rp);\n" " R_set_command_line_arguments(argc, argv);\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13817 #, no-wrap msgid "" " FlushConsoleInputBuffer(GetStdHandle(STD_INPUT_HANDLE));\n" "\n" msgstr "" # #. type: smallexample #: R-exts.texi:13834 #, no-wrap msgid "" " signal(SIGBREAK, my_onintr);\n" " GA_initapp(0, 0);\n" " readconsolecfg();\n" " setup_Rmainloop();\n" "#ifdef SIMPLE_CASE\n" " run_Rmainloop();\n" "#else\n" " R_ReplDLLinit();\n" " while(R_ReplDLLdo1() > 0) @{\n" "/* add user actions here if desired */\n" " @}\n" "/* only get here on EOF (not q()) */\n" "#endif\n" " Rf_endEmbeddedR(0);\n" " return 0;\n" "@}\n" msgstr "" # #. type: Plain text #: R-exts.texi:13837 msgid "The ideas are" msgstr "" # #. type: itemize #: R-exts.texi:13842 msgid "" "Check that the front-end and the linked @file{R.dll} match -- other front-" "ends may allow a looser match." msgstr "" # #. type: itemize #: R-exts.texi:13850 msgid "" "Find and set the @R{} home directory and the user's home directory. The " "former may be available from the Windows Registry: it will be in " "@code{HKEY_LOCAL_MACHINE\\Software\\R-core\\R\\InstallPath} from an " "administrative install and @code{HKEY_CURRENT_USER\\Software\\R-core\\R" "\\InstallPath} otherwise, if selected during installation (as it is by " "default)." msgstr "" # #. type: itemize #: R-exts.texi:13855 msgid "" "Define startup conditions and callbacks @emph{via} the @code{Rstart} " "structure. @code{R_DefParams} sets the defaults, and @code{R_SetParams} " "sets updated values." msgstr "" # #. type: itemize #: R-exts.texi:13860 msgid "" "Record the command-line arguments used by " "@code{R_set_command_line_arguments} for use by the @R{} function " "@code{commandArgs()}." msgstr "" # #. type: itemize #: R-exts.texi:13863 msgid "Set up the signal handler and the basic user interface." msgstr "" # #. type: itemize #: R-exts.texi:13866 msgid "Run the main @R{} loop, possibly with our actions intermeshed." msgstr "" # #. type: itemize #: R-exts.texi:13869 msgid "Arrange to clean up." msgstr "" # #. type: Plain text #: R-exts.texi:13877 msgid "" "An underlying theme is the need to keep the GUI `alive', and this has not " "been done in this example. The @R{} callback @code{R_ProcessEvents} needs " "to be called frequently to ensure that Windows events in @R{} windows are " "handled expeditiously. Conversely, @R{} needs to allow the GUI code (which " "is running in the same process) to update itself as needed -- two ways are " "provided to allow this:" msgstr "" # #. type: itemize #: R-exts.texi:13883 msgid "" "@code{R_ProcessEvents} calls the callback registered by @code{Rp-" ">callback}. A version of this is used to run package Tcl/Tk for @pkg{tcltk} " "under Windows, for the code is" msgstr "" # #. type: example #: R-exts.texi:13892 #, no-wrap msgid "" "void R_ProcessEvents(void)\n" "@{\n" " while (peekevent()) doevent(); /* Windows events for GraphApp */\n" " if (UserBreak) @{ UserBreak = FALSE; onintr(); @}\n" " R_CallBackHook();\n" " if(R_tcldo) R_tcldo();\n" "@}\n" msgstr "" # #. type: itemize #: R-exts.texi:13898 msgid "" "The mainloop can be split up to allow the calling application to take some " "action after each line of input has been dealt with: see the alternative " "code below @code{#ifdef SIMPLE_CASE}." msgstr "" # #. type: Plain text #: R-exts.texi:13905 msgid "" "It may be that no @R{} GraphApp windows need to be considered, although " "these include pagers, the @code{windows()} graphics device, the @R{} data " "and script editors and various popups such as @code{choose.file()} and " "@code{select.list()}. It would be possible to replace all of these, but it " "seems easier to allow GraphApp to handle most of them." msgstr "" # #. type: Plain text #: R-exts.texi:13911 msgid "" "It is possible to run @R{} in a GUI in a single thread (as @file{RGui.exe} " "shows) but it will normally be easier@footnote{An attempt to use only " "threads in the late 1990s failed to work correctly under Windows 95, the " "predominant version of Windows at that time.} to use multiple threads." msgstr "" # #. type: Plain text #: R-exts.texi:13916 msgid "" "Note that @R{}'s own front ends use a stack size of 10Mb, whereas MinGW " "executables default to 2Mb, and Visual C++ ones to 1Mb. The latter stack " "sizes are too small for a number of @R{} applications, so general-purpose " "front-ends should use a larger stack size." msgstr "" # #. type: Plain text #: R-exts.texi:13927 msgid "" "Both applications which embed @R{} and those which use a @code{system} call " "to invoke @R{} (as @command{Rscript.exe}, @command{Rterm.exe} or @command{R." "exe}) need to be able to find the @R{} @file{bin} directory. The simplest " "way to do so is the ask the user to set an environment variable @env{R_HOME} " "and use that, but naive users may be flummoxed as to how to do so or what " "value to use." msgstr "" # #. type: Plain text #: R-exts.texi:13934 msgid "" "The @R{} for Windows installers have for a long time allowed the value of " "@code{R_HOME} to be recorded in the Windows Registry: this is optional but " "selected by default. @emph{Where} it is recorded has changed over the years " "to allow for multiple versions of @R{} to be installed at once, and to allow " "32- and 64-bit versions of @R{} to be installed on the same machine." msgstr "" # #. type: Plain text #: R-exts.texi:13946 msgid "" "The basic Registry location is @code{Software\\R-core\\R}. For an " "administrative install this is under @code{HKEY_LOCAL_MACHINE} and on a 64-" "bit OS @code{HKEY_LOCAL_MACHINE\\Software\\R-core\\R} is by default " "redirected for a 32-bit application, so a 32-bit application will see the " "information for the last 32-bit install, and a 64-bit application that for " "the last 64-bit install. For a personal install, the information is under " "@code{HKEY_CURRENT_USER\\Software\\R-core\\R} which is seen by both 32-bit " "and 64-bit applications and so records the last install of either " "architecture. To circumvent this, there are locations @code{Software\\R-core" "\\R32} and @code{Software\\R-core\\R64} which always refer to one " "architecture." msgstr "" # #. type: Plain text #: R-exts.texi:13954 msgid "" "When @R{} is installed and recording is not disabled then two string values " "are written at that location for keys @code{InstallPath} and @code{Current " "Version}, and these keys are removed when @R{} is uninstalled. To allow " "information about other installed versions to be retained, there is also a " "key named something like @code{3.0.0} or @code{3.0.0 patched} or @code{3.1.0 " "Pre-release} with a value for @code{InstallPath}." msgstr "" # #. type: Plain text #: R-exts.texi:13957 msgid "" "So a comprehensive algorithm to search for @code{R_HOME} is something like" msgstr "" # #. type: itemize #: R-exts.texi:13965 msgid "" "Decide which of personal or administrative installs should have precedence. " "There are arguments both ways: we find that with roaming profiles that " "@code{HKEY_CURRENT_USER\\Software} often gets reverted to an earlier " "version. Do the following for one or both of @code{HKEY_CURRENT_USER} and " "@code{HKEY_LOCAL_MACHINE}." msgstr "" # #. type: itemize #: R-exts.texi:13970 msgid "" "If the desired architecture is known, look in @code{Software\\R-core\\R32} " "or @code{Software\\R-core\\R64}, and if that does not exist or the " "architecture is immaterial, in @code{Software\\R-core\\R}." msgstr "" # #. type: itemize #: R-exts.texi:13977 msgid "" "If key @code{InstallPath} exists then this is @code{R_HOME} (recorded using " "backslashes). If it does not, look for version-specific keys like " "@code{2.11.0 alpha}, pick the latest (which is of itself a complicated " "algorithm as @code{2.11.0 patched > 2.11.0 > 2.11.0 alpha > 2.8.1}) and use " "its value for @code{InstallPath}." msgstr "" # #. type: Plain text #: R-exts.texi:13983 msgid "" "Prior to @R{} 2.12.0 @file{R.dll} and the various front-end executables were " "in @file{R_HOME\\bin}, but they are now in @file{R_HOME\\bin\\i386} or " "@file{R_HOME\\bin\\x64}. So you may need to arrange to look first in the " "architecture-specific subdirectory and then in @file{R_HOME\\bin}." msgstr ""
| R-Forge@R-project.org | ViewVC Help |
| Powered by ViewVC 1.0.0 |
