# 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;@}@}@{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 ""