Next:Configure and cleanup, Up:Creating R packages   [Contents][Index]

1.1.1 TheDESCRIPTION file ¶

TheDESCRIPTION file contains basic information about the packagein the following format:

Package: pkgnameVersion: 0.5-1Date: 2015-01-01Title: My First Collection of FunctionsAuthors@R: c(person("Joe", "Developer", role = c("aut", "cre"), email = "Joe.Developer@some.domain.net", comment = c(ORCID = "nnnn-nnnn-nnnn-nnnn")), person("Pat", "Developer", role = "aut"), person("A.", "User", role = "ctb", email = "A.User@whereever.net"))Author: Joe Developer [aut, cre], Pat Developer [aut], A. User [ctb]Maintainer: Joe Developer <Joe.Developer@some.domain.net>Depends: R (>= 3.1.0), nlmeSuggests: MASSDescription: A (one paragraph) description of what the package does and why it may be useful.License: GPL (>= 2)URL: https://www.r-project.org, http://www.another.urlBugReports: https://pkgname.bugtracker.url

The format is that of a version of a ‘Debian Control File’ (see the helpfor ‘read.dcf’ andhttps://www.debian.org/doc/debian-policy/ch-controlfields.html:R does not require encoding in UTF-8 and does not support commentsstarting with ‘#’). Fields start with anASCII nameimmediately followed by a colon: the value starts after the colon and aspace. Continuation lines (for example, for descriptions longer thanone line) start with a space or tab. Field names are case-sensitive:all those used by R are capitalized.

For maximal portability, theDESCRIPTION file should be writtenentirely inASCII — if this is not possible it must containan ‘Encoding’ field (see below).

Several optional fields takelogical values: these can bespecified as ‘yes’, ‘true’, ‘no’ or ‘false’:capitalized values are also accepted.

The ‘Package’, ‘Version’, ‘License’, ‘Description’,‘Title’, ‘Author’, and ‘Maintainer’ fields are mandatory,all other fields are optional. Fields ‘Author’ and‘Maintainer’ can be auto-generated from ‘Authors@R’, and maybe omitted if the latter is provided: however if they are notASCII we recommend that they are provided.

The mandatory ‘Package’ field gives the name of the package. Thisshould contain only (ASCII) letters, numbers and dot, have atleast two characters and start with a letter and not end in a dot. Ifit needs explaining, this should be done in the ‘Description’ field(and not the ‘Title’ field).

The mandatory ‘Version’ field gives the version of the package.This is a sequence of at leasttwo (and usually three)non-negative integers separated by single ‘.’ or ‘-’characters. The canonical form is as shown in the example, and aversion such as ‘0.01’ or ‘0.01.0’ will be handled as if itwere ‘0.1-0’. It isnot a decimal number, so for example0.9 < 0.75 since9 < 75.

The mandatory ‘License’ field is discussed in the next subsection.

The mandatory ‘Title’ field should give ashort descriptionof the package. Some package listings may truncate the title to 65characters. It should usetitle case (that is, use capitals forthe principal words:tools::toTitleCase can help you with this),not use any markup, not have any continuation lines, and not end in aperiod (unless part of …). Do not repeat the package name: it isoften used prefixed by the name. Refer to other packages and externalsoftware in single quotes, and to book titles (and similar) in doublequotes.

The mandatory ‘Description’ field should give acomprehensive description of what the package does. One can useseveral (complete) sentences, but only one paragraph. It should beintelligible to all the intended readership (e.g. for aCRANpackage to allCRAN users). It is good practice not to startwith the package name, ‘This package’ or similar. As with the‘Title’ field, double quotes should be used for quotations(including titles of books and articles), and single quotes fornon-English usage, including names of other packages and externalsoftware. This field should also be used for explaining the packagename if necessary. URLs should be enclosed in angle brackets, e.g.‘<https://www.r-project.org>’: see alsoSpecifying URLs.

The mandatory ‘Author’ field describes who wrotethepackage. It is a plain text field intended for human readers, but notfor automatic processing (such as extracting the email addresses of alllisted contributors: for that use ‘Authors@R’). Note that allsignificant contributors must be included: if you wrote an R wrapperfor the work of others included in thesrc directory, you are notthe sole (and maybe not even the main) author.

The mandatory ‘Maintainer’ field should give asingle namefollowed by avalid (RFC 2822) email address in angle brackets. Itshould not end in a period or comma. This field is what is reported bythemaintainer function and used bybug.report. For aCRAN package it should be aperson, not a mailing listand not a corporate entity: do ensure that it is valid and will remainvalid for the lifetime of the package.

Note that thedisplay name (the part before the address in anglebrackets) should be enclosed in double quotes if it containsnon-alphanumeric characters such as comma or period. (The currentstandard, RFC 5322, allows periods but RFC 2822 did not.)

Both ‘Author’ and ‘Maintainer’ fields can be omitted if asuitable ‘Authors@R’ field is given. This field can be used toprovide a refined and machine-readable description of the package“authors” (in particular specifying their preciseroles),via suitable R code. It should create an object of class"person", by either a call toperson or a series of calls(one per “author”) concatenated byc(): see the exampleDESCRIPTION file above. The roles can include ‘"aut"’(author) for full authors, ‘"cre"’ (creator) for the packagemaintainer, and ‘"ctb"’ (contributor) for other contributors,‘"cph"’ (copyright holder, which should be the legal name for aninstitution or corporate body), among others. See?person formore information. Note that no role is assumed by default.Auto-generated package citation information takes advantage of thisspecification. The ‘Author’ and ‘Maintainer’ fields areauto-generated from it if needed when building⁵ or installing.Note that for CRAN submissions, providing ‘Authors@R’ is required,and providingORCID orROR identifiers (seehttps://orcid.org/ andhttps://ror.org/) where possible isstrongly encouraged.

An optional ‘Copyright’ field can be used where the copyrightholder(s) are not the authors. If necessary, this can refer to aninstalled file: the convention is to use fileinst/COPYRIGHTS.

The optional ‘Date’ field gives therelease date of thecurrent version of the package. Using the ‘yyyy-mm-dd’ format ofthe ISO 8601 standard is strongly recommended⁶.

The ‘Depends’, ‘Imports’, ‘Suggests’, ‘Enhances’,‘LinkingTo’ and ‘Additional_repositories’ fields are discussedin a later subsection.

Dependencies external to the R system should be listed in the‘SystemRequirements’ field, possibly amplified in a separateREADME file. This includes specifying a non-default C++ standardand the need for GNUmake.

The ‘URL’ field may give a list ofURLsseparated by commas or whitespace, for example the homepage of theauthor or a page where additional material describing the software canbe found. TheseURLs are converted to active hyperlinks inCRAN package listings. SeeSpecifying URLs.

The ‘BugReports’ field may contain a singleURL to whichbug reports about the package should be submitted. ThisURLwill be used bybug.report instead of sending an email to themaintainer. A browser is opened for a ‘http://’ or ‘https://’URL. To specify another email address for bug reports, use‘Contact’ instead: howeverbug.report will try to extract anemail address (preferably from a ‘mailto:’ URL or enclosed in anglebrackets) from ‘BugReports’.

Base and recommended packages (i.e., packages contained in the Rsource distribution or available fromCRAN and recommended tobe included in every binary distribution of R) have a ‘Priority’field with value ‘base’ or ‘recommended’, respectively. Thesepriorities must not be used by other packages.

A ‘Collate’ field can be used for controlling the collation orderfor the R code files in a package when these are processed forpackage installation. The default is to collate according to the‘C’ locale. If present, the collate specification must listall R code files in the package (taking possible OS-specificsubdirectories into account, seePackage subdirectories) as awhitespace separated list of file paths relative to theRsubdirectory.Paths containing white space or quotes need to be quoted. AnOS-specific collation field (‘Collate.unix’ or‘Collate.windows’) will be used in preference to ‘Collate’.

The ‘LazyData’ logical field controls whether the R datasets uselazy-loading. A ‘LazyLoad’ field was used in versions prior to2.14.0, but now is ignored.

The ‘KeepSource’ logical field controls if the package code is sourcedusingkeep.source = TRUE orFALSE: it might be neededexceptionally for a package designed to always be used withkeep.source = TRUE.

The ‘ByteCompile’ logical field controls if the package R code is tobe byte-compiled on installation: the default is to byte-compile. Thiscan be overridden by installing with flag--no-byte-compile.

The ‘UseLTO’ logical field is used to indicate if source code inthe package⁷ is to becompiled with Link-Time Optimization (seeUsing Link-time Optimization) if R was installed with--enable-lto (defaulttrue) or--enable-lto=R (default false) (or onWindows⁸ ifLTO_OPT is set inMkRules). This can be overridden by theflags--use-LTO and--no-use-LTO.LTO is said to givemost size and performance improvements for large and complex (heavilytemplated) C++ projects.

The ‘StagedInstall’ logical field controls if package installationis ‘staged’, that is done to a temporary location and moved to the finallocation when successfully completed. This field was introduced in R3.6.0 and is true by default: it is considered to be a temporary measurewhich may be withdrawn in future.

The ‘ZipData’ logical field has been ignored since R 2.13.0.

The ‘Biarch’ logical field is used on Windows to select theINSTALL option--force-biarch for this package. Notcurrently relevant.

The ‘BuildVignettes’ logical field can be set to a false value tostopR CMD build from attempting to build the vignettes, aswell as preventing⁹R CMD check from testingthis. This should only be used exceptionally, for example if the PDFsinclude large figures which are not part of the package sources (andhence only in packages which do not have an Open Source license).

The ‘VignetteBuilder’ field names (in a comma-separated list)packages that provide an engine for building vignettes. These mayinclude the current package, or ones listed in ‘Depends’,‘Suggests’ or ‘Imports’. Theutils package is alwaysimplicitly appended. SeeNon-Sweave vignettes for details. Notethat if, for example, a vignette has engine ‘knitr::rmarkdown’,thenknitr provides the engine but bothknitr andrmarkdown are needed for using it, soboth thesepackages need to be in the ‘VignetteBuilder’ field and at leastsuggested (asrmarkdown is only suggested byknitr, andhence not available automatically along with it). Many packages usingknitr also need the packageformatR which itsuggests and so the user package needs to do so too and include this in‘VignetteBuilder’.

If theDESCRIPTION file is not entirely inASCII itshould contain an ‘Encoding’ field specifying an encoding. This isused as the encoding of theDESCRIPTION file itself and of theR andNAMESPACE files, and as the default encoding of.Rd files. The examples are assumed to be in this encoding whenrunningR CMD check, and it is used for the encoding of theCITATION file. Only encoding nameslatin1 andandUTF-8 are known to be portable. (Do not specify an encodingunless one is actually needed: doing so makes the packagelessportable. If a package has a specified encoding, you should runR CMD build etc in a locale using that encoding.)

The ‘NeedsCompilation’ field should be set to"yes" if thepackage contains native code which needs to be compiled, otherwise"no" (whenthe package could be installed from source on any platform withoutadditional tools). This is used byinstall.packages(type ="both") in R >= 2.15.2 on platforms where binary packages are thenorm: it is normally set byR CMD build or the repositoryassuming compilation is required if and only if the package has asrc directory.

The ‘OS_type’ field specifies the OS(es) for which thepackage is intended. If present, it should be one ofunix orwindows, and indicates that the package can only be installedon a platform with ‘.Platform$OS.type’ having that value.

The ‘Type’ field specifies the type of the package:seePackage types.

One can add subject classifications for the content of the package usingthe fields ‘Classification/ACM’ or ‘Classification/ACM-2012’(using the Computing Classification System of the Association forComputing Machinery,https://www.acm.org/publications/class-2012; the former refersto the 1998 version), ‘Classification/JEL’ (the Journal of EconomicLiterature Classification System,https://www.aeaweb.org/econlit/jelCodes.php, or‘Classification/MSC’ or ‘Classification/MSC-2010’ (theMathematics Subject Classification of the American Mathematical Society,https://mathscinet.ams.org/msc/msc2010.html; the former refers to the 2000 version).The subject classifications should be comma-separated lists of therespective classification codes, e.g., ‘Classification/ACM: G.4,H.2.8, I.5.1’.

A ‘Language’ field can be used to indicate if the packagedocumentation is not in English: this should be a comma-separated listof standard (not private use or grandfathered)IETF language tags ascurrently defined by RFC 5646(https://www.rfc-editor.org/rfc/rfc5646, see alsohttps://en.wikipedia.org/wiki/IETF_language_tag), i.e., uselanguage subtags which in essence are 2-letter ISO 639-1(https://en.wikipedia.org/wiki/ISO_639-1) or 3-letter ISO639-3 (https://en.wikipedia.org/wiki/ISO_639-3) languagecodes.

An ‘RdMacros’ field can be used to hold a comma-separated list ofpackages from which the current package will importRd macrodefinitions. These package should also be listed in ‘Imports’(or ‘Depends’). The macros in these packages will beimported after the system macros, in theorder listed in the ‘RdMacros’ field, before any macro definitionsin the current package are loaded. Macro definitions in individual.Rd files in theman directory are loaded last, and arelocal to later parts of that file. In case of duplicates, the lastloaded definition will be used.¹⁰ BothR CMDRd2pdf andR CMD Rdconv have an optional flag--RdMacros=pkglist. The option is also a comma-separated listof package names, and has priority over the value given inDESCRIPTION. Packages usingRd macros should depend onR 3.2.0 or later.

Note: There should be no ‘Built’ or ‘Packaged’ fields, as these areadded by the package management tools.

There is no restriction on the use of other fields not mentioned here(but using other capitalizations of these field names would causeconfusion). FieldsNote,Contact (for contacting theauthors/developers¹¹) andMailingList are in commonuse. Some repositories (includingCRAN and R-forge) add theirown fields.

1.1.2 Licensing ¶

Licensing for a package which might be distributed is an important butpotentially complex subject.

It is very important that you include license information! Otherwise,it may not even be legally correct for others to distribute copies ofthe package, let alone use it.

The package management tools use the concept of‘free or open source software’(FOSS, e.g.,https://en.wikipedia.org/wiki/FOSS)licenses: the idea being that some users of R and its packages wantto restrict themselves to such software. Others need to ensure thatthere are no restrictions stopping them using a package, e.g.forbidding commercial or military use. It is a central tenet ofFOSSsoftware that there are no restrictions on users nor usage.

Do not use the ‘License’ field for information on copyrightholders: if needed, use a ‘Copyright’ field.

The mandatory ‘License’ field in theDESCRIPTION file shouldspecify the license of the package in a standardized form. Alternativesare indicatedvia vertical bars. Individual specifications mustbe one of

• One of the “standard” short specifications

  GPL-2 GPL-3 LGPL-2 LGPL-2.1 LGPL-3 AGPL-3 Artistic-2.0BSD_2_clause BSD_3_clause MIT

  as made availableviahttps://www.R-project.org/Licenses/ andcontained in subdirectoryshare/licenses of the R source or homedirectory.

• The names or abbreviations of other licenses contained in the licensedata base in fileshare/licenses/license.db in the R source orhome directory, possibly (for versioned licenses) followed by a versionrestriction of the form ‘(opv)’ with ‘op’ one ofthe comparison operators ‘<’, ‘<=’, ‘>’, ‘>=’,‘==’, or ‘!=’ and ‘v’ a numeric version specification(strings of non-negative integers separated by ‘.’), possiblycombinedvia ‘,’ (see below for an example). For versionedlicenses, one can also specify the name followed by the version, orcombine an existing abbreviation and the version with a ‘-’.

  AbbreviationsGPL andLGPL are ambiguous andusually¹² taken to mean any version of the license: but it is betternot to use them.

• One of the strings ‘file LICENSE’ or ‘file LICENCE’ referringto a file namedLICENSE orLICENCE in the package (sourceand installation) top-level directory.
• The string ‘Unlimited’, meaning that there are no restrictions ondistribution or use other than those imposed by relevant laws (includingcopyright laws).

Multiple licences can be specified separated by ‘|’ (surrounded byspaces) in which case the user can choose any of the alternatives.

If a package licenserestricts a base license (where permitted,e.g., using GPL-3 or AGPL-3 with an attribution clause), the additionalterms should be placed in fileLICENSE (orLICENCE), andthe string ‘+ file LICENSE’ (or ‘+ file LICENCE’,respectively) should be appended to the corresponding individual licensespecification (preferably with the ‘+’ surrounded by spaces). Notethat several commonly used licenses do not permit restrictions: thisincludes GPL-2 and hence any specification which includes it.

Examples of standardized specifications include

License: GPL-2License: LGPL (>= 2.0, < 3) | Mozilla Public LicenseLicense: GPL-2 | file LICENCELicense: GPL (>= 2) | BSD_3_clause + file LICENSELicense: Artistic-2.0 | AGPL-3 + file LICENSE

Please note in particular that “Public domain” is not a valid license,since it is not recognized in some jurisdictions.

Please ensure that the license you choose also covers any dependencies(including system dependencies) of your package: it is particularlyimportant that any restrictions on the use of such dependencies areevident to people reading yourDESCRIPTION file.

Fields ‘License_is_FOSS’ and ‘License_restricts_use’ may beadded by repositories where information cannot be computed from the nameof the license. ‘License_is_FOSS: yes’ is used for licenses whichare known to beFOSS, and ‘License_restricts_use’ can have values‘yes’ or ‘no’ if theLICENSE file is known to restrictusers or usage, or known not to. These are used by, e.g., theavailable.packages filters.

The optional fileLICENSE/LICENCE contains a copy of thelicense of the package. To avoid any confusion only include such a fileif it is referred to in the ‘License’ field of theDESCRIPTION file.

Whereas you should feel free to include a license file in yoursource distribution, please do not arrange toinstall yetanother copy of theGNUCOPYING orCOPYING.LIBfiles but refer to the copies onhttps://www.R-project.org/Licenses/ and included in the Rdistribution (in directoryshare/licenses). Since files namedLICENSE orLICENCEwill be installed, do not usethese names for standard license files. To include comments about thelicensing rather than the body of a license, use a file named somethinglikeLICENSE.note.

A few “standard” licenses are rather license templates which needadditional information to be completedvia ‘+ file LICENSE’(with the ‘+’ surrounded by spaces). Where the additionalinformation is ‘COPYRIGHT HOLDER’, this must give the actual legalentities (not something vague like ‘Name-of-package authors’): if morethan one they should be listed in decreasing order of contribution.

1.1.3 Package Dependencies ¶

The ‘Depends’ field gives a comma-separated list of package nameswhich this package depends on. Those packages will be attached beforethe current package whenlibrary orrequire is called.Each package name may be optionally followed by a comment in parenthesesspecifying a version requirement. The comment should contain acomparison operator, whitespace and a valid version number,e.g. ‘MASS (>= 3.1-20)’.

The ‘Depends’ field can also specify a dependence on a certainversion of R — e.g., if the package works only with R version4.0.0 or later, include ‘R (>= 4.0)’ in the ‘Depends’field. (As here, trailing zeroes can be dropped and it is recommendedthat they are.) You can also require a certain SVN revision for R-develor R-patched, e.g. ‘R (>= 2.14.0), R (>= r56550)’ requires aversion later than R-devel of late July 2011 (including releasedversions of 2.14.0).

It makes no sense to declare a dependence onR without a versionspecification, nor on the packagebase: this is an R packageand packagebase is always available.

A package or ‘R’ can appear more than once in the ‘Depends’field, for example to give upper and lower bounds on acceptableversions.

It is inadvisable to use a dependence on R with patch level (the thirddigit) other than zero. Doing so with packages which others depend onwill cause the other packages to become unusable under earlier versionsin the series, and e.g. versions 4.x.1 are widely used throughout theNorthern Hemisphere academic year.

Bothlibrary and the R package checking facilities use thisfield: hence it is an error to use improper syntax or misuse the‘Depends’ field for comments on other software that might beneeded. The RINSTALL facilities check if the version ofR used is recent enough for the package being installed, and the listof packages which is specified will be attached (after checking versionrequirements) before the current package.

The ‘Imports’ field lists packages whose namespaces are importedfrom (as specified in theNAMESPACE file) but which do not needto be attached. Namespaces accessed by the ‘::’ and ‘:::’operators must be listed here, or in ‘Suggests’ or ‘Enhances’(see below). Ideally this field will include all the standard packagesthat are used, and it is important to include S4-using packages (astheir class definitions can change and theDESCRIPTION file isused to decide which packages to re-install when this happens).Packages declared in the ‘Depends’ field should not also be in the‘Imports’ field. Version requirements can be specified and arechecked when the namespace is loaded.

The ‘Suggests’ field uses the same syntax as ‘Depends’ andlists packages that are not necessarily needed. This includes packagesused only in examples, demos, tests or vignettes (seeWriting package vignettes), and packages loaded in the body of functions. E.g.,suppose an example¹³ frompackagefoo uses a dataset from packagebar. Then it is notnecessary to havebar to usefoo unless one wants to executeall the examples: it is useful to havebar, butnot necessary. Version requirements can be specified but should bechecked by the code which uses the package.

Finally, the ‘Enhances’ field lists packages “enhanced” by thepackage at hand, e.g., by providing methods for classes from thesepackages, or ways to handle objects from these packages (so severalpackages have ‘Enhances: chron’ because they can handle datetimeobjects fromchron even though they prefer R’s nativedatetime functions). Version requirements can be specified, but arecurrently not used. Such packages cannot be required to check thepackage: any tests which use them must be conditional on the presenceof the package. (If your tests use e.g. a dataset from anotherpackage it should be in ‘Suggests’ and not ‘Enhances’.)

The general rules are

• A package should be listed in only one of these fields.
• Packages whose namespace only is needed to load the package usinglibrary(pkgname) should be listed in the ‘Imports’ fieldand not in the ‘Depends’ field. Packages listed inimportorimportFrom directives in theNAMESPACE file shouldalmost always be in ‘Imports’ and not ‘Depends’.
• Packages that need to be attached to successfully load the package usinglibrary(pkgname) must be listed in the ‘Depends’field.
• All packages that are needed¹⁴ to successfully runR CMD check on thepackage must be listed in one of ‘Depends’ or ‘Suggests’ or‘Imports’. Packages used to run examples or tests conditionally(e.g.viaif(require(pkgname))) should be listedin ‘Suggests’ or ‘Enhances’. (This allows checkers to ensurethat all the packages needed for a complete check are installed.)
• Packages needed to use datasets from the package should be in‘Imports’: this includes those needed to define S4 classes used.

In particular, packages providing “only” data for examples, demos orvignettes should be listed in ‘Suggests’ rather than ‘Depends’in order to make lean installations possible.

Version dependencies in the ‘Depends’ and ‘Imports’ fields areused bylibrary when it loads the package, andinstall.packages checks versions for the ‘Depends’,‘Imports’ and (fordependencies = TRUE) ‘Suggests’fields.

It is important that the information in these fields is complete andaccurate: it is for example used to compute which packages depend on anupdated package and which packages can safely be installed in parallel.

This scheme was developed before all packages had namespaces (R2.14.0 in October 2011), and good practice changed once that was inplace.

Field ‘Depends’ should nowadays be used rarely, only for packageswhich are intended to be put on the search path to make their facilitiesavailable to the end user (and not to the package itself): for exampleit makes sense that a user of packagelatticeExtra would wantthe functions of packagelattice made available.

Almost always packages mentioned in ‘Depends’ should also beimported from in theNAMESPACE file: this ensures that any neededparts of those packages are available when some other package importsthe current package.

The ‘Imports’ field should not contain packages which are notimported from (via theNAMESPACE file or:: or::: operators), as all the packages listed in that field need tobe installed for the current package to be installed. (This is checkedbyR CMD check.)

R code in the package should calllibrary orrequireonly exceptionally. Such calls are never needed for packages listed in‘Depends’ as they will already be on the search path. It used tobe common practice to userequire calls for packages listed in‘Suggests’ in functions which used their functionality, butnowadays it is better to access such functionalityvia::calls.

A package that wishes to make use of header files in other packages tocompile its C/C++ code needs to declare them as a comma-separated listin the field ‘LinkingTo’ in theDESCRIPTION file. Forexample

LinkingTo: link1, link2

The ‘LinkingTo’ field can have a version requirement which ischecked at installation.

Specifying a package in ‘LinkingTo’ suffices if these are C/C++headers containing source code or static linking is done atinstallation: the packages do not need to be (and usually should not be)listed in the ‘Depends’ or ‘Imports’ fields. This includesCRAN packageBH and almost all users ofRcppArmadillo andRcppEigen. Note that‘LinkingTo’ applies only to installation: if a packages wishes touse headers to compile code in tests or vignettes the package providingthem needs to be listed in ‘Suggests’ or perhaps ‘Depends’.

For another use of ‘LinkingTo’ seeLinking to native routines in other packages.

The ‘Additional_repositories’ field is a comma-separated list ofrepository URLs where the packages named in the other fields may befound. It is currently used byR CMD check to check that thepackages can be found, at least as source packages (which can beinstalled on any platform).

• Suggested packages

   if (requireNamespace("rgl", quietly = TRUE)) {      rgl::plot3d(...)   } else {      ## do something else not involving rgl.   }

1.1.4 TheINDEX file ¶

The optional fileINDEX contains a line for each sufficientlyinteresting object in the package, giving its name and a description(functions such as print methods not usually called explicitly might notbe included). Normally this file is missing and the correspondinginformation is automatically generated from the documentation sources(usingtools::Rdindex()) when installing from source.

The file is part of the information given bylibrary(help =pkgname).

Rather than editing this file, it is preferable to put customizedinformation about the package into an overview help page(seeDocumenting packages) and/or a vignette (seeWriting package vignettes).

1.1.5 Package subdirectories ¶

TheR subdirectory contains R code files, only. The codefiles to be installed must start with anASCII (lower or uppercase) letter or digit and have one of the extensions¹⁵.R,.S,.q,.r, or.s. We recommend using.R, as this extension seems to be not used by any other software.It should be possible to read in the files usingsource(), soR objects must be created by assignments. Note that there need be noconnection between the name of the file and the R objects created byit. Ideally, the R code files should only directly assign Robjects and definitely should not call functions with side effects suchasrequire andoptions. If computations are required tocreate objects these can use code ‘earlier’ in the package (see the‘Collate’ field) plus functions in the ‘Depends’ packagesprovided that the objects created do not depend on those packages exceptvia namespace imports.

Extreme care is needed if top-level computations are made to depend onavailability or not of other packages. In particular this applies tosetMethods andsetClass calls. Nor should they depend onthe availability of external resources such as downloads.

Two exceptions are allowed: if theR subdirectory contains a filesysdata.rda (a saved image of one or more R objects: pleaseuse suitable compression as suggested bytools::resaveRdaFiles,and see also the ‘SysDataCompression’DESCRIPTION field.)this will be lazy-loaded into the namespace environment – this isintended for system datasets that are not intended to be user-accessibleviadata. Also, files ending in ‘.in’ will beallowed in theR directory to allow aconfigure script togenerate suitable files.

OnlyASCII characters (and the control characters tab,form feed,LF andCR) should be used in code files. Other characters areaccepted in comments¹⁶, but then the comments may notbe readable in e.g. a UTF-8 locale. Non-ASCII characters inobject names will normally¹⁷ fail when the package is installed. Any byte willbe allowed in a quoted character string but ‘\uxxxx’ escapes shouldbe used for non-ASCII characters. However,non-ASCII character strings may not be usable in some localesand may display incorrectly in others.

Various R functions in a package can be used to initialize andclean up. SeeLoad hooks.

Theman subdirectory should contain (only) documentation filesfor the objects in the package inR documentation (Rd) format.The documentation filenames must start with anASCII (lower orupper case) letter or digit and have the extension.Rd (thedefault) or.rd. Further, the names must be valid in‘file://’ URLs, which means¹⁸they must be entirelyASCII and not contain ‘%’.SeeWriting R documentation files, for more information. Note thatall user-level objects in a package should be documented; if a packagepkg contains user-level objects which are for “internal” useonly, it should provide a filepkg-internal.Rd whichdocuments all such objects, and clearly states that these are not meantto be called by the user. See e.g. the sources for packagegridin the R distribution. Note that packages which use internal objectsextensively should not export those objects from their namespace, whenthey do not need to be documented (seePackage namespaces).

Having aman directory containing no documentation files may givean installation error.

Theman subdirectory may contain a subdirectory namedmacros;this will contain source for user-defined Rd macros.(SeeUser-defined macros.) These use the Rd format, but maynot contain anything but macro definitions, comments and whitespace.

TheR andman subdirectories may contain OS-specificsubdirectories namedunix orwindows.

The sources and headers for the compiled code are insrc, plusoptionally a fileMakevars orMakefile (or for use onWindows, with extension.win or.ucrt). When a package isinstalled usingR CMD INSTALL,make is used to controlcompilation and linking into a shared object for loading into R.There are defaultmake variables and rules for this(determined when R is configured and recorded inR_HOME/etcR_ARCH/Makeconf), providing support for C,C++, fixed- or free-form Fortran, Objective C and ObjectiveC++¹⁹ with associated extensions.c,.cc or.cpp,.f,.f90 or.f95,²⁰.m, and.mm, respectively. We recommend using.hfor headers, also for C++²¹ or Fortran include files. (Use of extension.C for C++ is no longer supported.) Files in thesrcdirectory should not be hidden (start with a dot), and hidden files willunder some versions of R be ignored.

It is not portable (and may not be possible at all) to mix all theselanguages in a single package. Because R itself uses it, we know thatC and fixed-form Fortran can be used together, and mixing C, C++ andFortran usually work for the platform’s native compilers.

If your code needs to depend on the platform there are certain defineswhich can be used in C or C++. On all Windows builds (even 64-bit ones)‘_WIN32’ will be defined: on 64-bit Windows builds also‘_WIN64’. For Windows on ARM, test for ‘_M_ARM64’ or both‘_WIN32’ and ‘__aarch64__’. On macOS ‘__APPLE__’ isdefined²²; for an ‘Apple Silicon’ platform, testfor both ‘__APPLE__’ and ‘__arm64__’.

The default rules can be tweaked by setting macros²³ in a filesrc/Makevars (seeUsingMakevars). Note that this mechanismshould be general enough to eliminate the need for a package-specificsrc/Makefile. If such a file is to be distributed, considerablecare 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 targetnamed ‘all’ and a (possibly empty) target ‘clean’ whichremoves all files generated by runningmake (to be used by‘R CMD INSTALL --clean’ and ‘R CMD INSTALL --preclean’).There are platform-specific file names on Windows:src/Makevars.win takes precedence oversrc/Makevars andsrc/Makefile.win must be used. Since R 4.2.0,src/Makevars.ucrt takes precedence oversrc/Makevars.win andsrc/Makefile.ucrt takes precedenceoversrc/Makefile.win.src/Makevars.ucrt andsrc/Makefile.ucrt will be ignored by earlier versions of R, andhence can be used to provide content specific toUCRT or Rtools42 and newer,but the support for.ucrt files may be removed in the future whenbuilding packages from source on the older versions of R will no longerbe needed, and hence the files may be renamed back to.win.Somemake programsrequire makefiles to have a complete final line, including a newline.

A few packages use thesrc directory for purposes other thanmaking a shared object (e.g. to create executables). Such packagesshould have filessrc/Makefile andsrc/Makefile.win orsrc/Makefile.ucrt (unless intended for only Unix-alikes or onlyWindows). Note that on Unix such makefiles are included afterR_HOME/etc/R_ARCH/Makeconf so all the usual Rmacros and make rules are available – for example C compilation will bydefault use the C compiler and flags with which R wasconfigured. This also applies on Windows as from R 4.3.0: packagesintended to be used with earlier versions should include that filethemselves.

The order of inclusion of makefiles for a package which doesnot have asrc/Makefile file is

For those which do, it is

Items in capitals are environment variables: those separated by commasare alternatives looked for in the order shown.

In very special cases packages may create binary files other than theshared objects/DLLs in thesrc directory. Such files will not beinstalled in a multi-architecture setting sinceR CMD INSTALL--libs-only is used to merge multiple sub-architectures and it onlycopies shared objects/DLLs. If a package wants to install otherbinaries (for example executable programs), it should provide an Rscriptsrc/install.libs.R which will be run as part of theinstallation in thesrc build directoryinstead of copyingthe shared objects/DLLs. The script is run in a separate Renvironment containing the following variables:R_PACKAGE_NAME(the name of the package),R_PACKAGE_SOURCE (the path to thesource directory of the package),R_PACKAGE_DIR (the path of thetarget installation directory of the package),R_ARCH (thearch-dependent part of the path, often empty),SHLIB_EXT (theextension of shared objects) andWINDOWS (TRUE on Windows,FALSE elsewhere). Something close to the default behavior couldbe replicated with the followingsrc/install.libs.R file:

files <- Sys.glob(paste0("*", SHLIB_EXT))dest <- file.path(R_PACKAGE_DIR, paste0('libs', R_ARCH))dir.create(dest, recursive = TRUE, showWarnings = FALSE)file.copy(files, dest, overwrite = TRUE)if(file.exists("symbols.rds"))    file.copy("symbols.rds", dest, overwrite = TRUE)

On the other hand, executable programs could be installed along thelines of

execs <- c("one", "two", "three")if(WINDOWS) execs <- paste0(execs, ".exe")if ( any(file.exists(execs)) ) {  dest <- file.path(R_PACKAGE_DIR,  paste0('bin', R_ARCH))  dir.create(dest, recursive = TRUE, showWarnings = FALSE)  file.copy(execs, dest, overwrite = TRUE)}

Note the use of architecture-specific subdirectories ofbin whereneeded. (Executables should installed under abin directory andnot underlibs. It is good practice to check that they can beexecuted as part of the installation script, so a broken package is notinstalled.)

Thedata subdirectory is for data files: SeeData in packages.

Thedemo subdirectory is for R scripts (for runningviademo()) that demonstrate some of the functionality of thepackage. Demos may be interactive and are not checkedautomatically²⁴, soif testing is desired use code in thetests directory to achievethis. The script files must start with a (lower or upper case) letterand have one of the extensions.R or.r. If present, thedemo subdirectory should also have a00Index file with oneline for each demo, giving its name and a description separated by a tabor at least three spaces. (This index file is not generatedautomatically.) Note that a demo does not have a specified encoding andso should be anASCII file (seeEncoding issues). Functiondemo() will use the package encoding if there is one, but this ismainly useful for non-ASCII comments.

The contents of theinst subdirectory will be copied recursivelyto the installation directory. Subdirectories ofinst should notinterfere with those used by R (currently,R,data,demo,exec,libs,man,help,html andMeta, and earlier versions usedlatex,R-ex). The copying of theinst happens aftersrcis built so itsMakefile can create files to be installed. Toexclude files from being installed, one can specify a list of excludepatterns in file.Rinstignore in the top-level source directory.These patterns should be Perl-like regular expressions (see the help forregexp in R for the precise details), one per line, to bematched case-insensitively against the file and directory paths, e.g.doc/.*[.]png$ will exclude all PNG files ininst/doc basedon the extension.

Note that with the exceptions ofINDEX,LICENSE/LICENCE andNEWS, information files at thetop level of the package willnot be installed and so not beknown to users of Windows and macOS compiled packages (and not seenby those who useR CMD INSTALL orinstall.packages()on the tarball). So any information files you wish an end user to seeshould be included ininst. Note that if the named exceptionsalso occur ininst, the version ininst will be that seenin the installed package.

Things you might like to add toinst are aCITATION filefor use by thecitation function, and aNEWS.Rd file foruse by thenews function. See its help page for the specificformat restrictions of theNEWS.Rd file.

Another file sometimes needed ininst isAUTHORS orCOPYRIGHTS to specify the authors or copyright holders when thisis too complex to put in theDESCRIPTION file.

Subdirectorytests 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.R (or.ras from R 3.4.0) file, orvia a.Rin file containingcode which in turn creates the corresponding.R file (e.g., bycollecting all function objects in the package and then calling themwith the strangest arguments). The results of running a.R fileare written to a.Rout file. If there is acorresponding²⁵.Rout.save file, these two arecompared, with differences being reported but not causing an error. Thedirectorytests is copied to the check area, and the tests arerun with the copy as the working directory and withR_LIBS set toensure that the copy of the package installed during testing will befound bylibrary(pkg_name). Note that the package-specifictests are run in a vanilla R session without setting therandom-number seed, so tests which use random numbers will need to setthe seed to obtain reproducible results (and it can be helpful to do soin all cases, to avoid occasional failures when tests are run).

If directorytests has a subdirectoryExamples containinga filepkg-Ex.Rout.save, this is compared to the outputfile for running the examples when the latter are checked. Referenceoutput should be produced without having the--timings optionset (and note that--as-cran sets it).

If reference output is included for examples, demos, tests or vignettes do makesure that it is fully reproducible, as it will be compared verbatim tothat produced in a check run, unless the ‘IGNORE_RDIFF’ markup isused. Things which trip up maintainers include displayed versionnumbers from loading other packages, printing numerical results to anunreproducibly high precision and printing timings. Another trap issmall values which are in fact rounding error from zero: consider usingzapsmall.

Subdirectoryexec could contain additional executable scripts thepackage needs, typically scripts for interpreters such as the shell,Perl, or Tcl. NB: only files (and not directories) underexecare installed (and those with names starting with a dot are ignored),and they are all marked as executable (mode755, moderated by‘umask’) on POSIX platforms. Note too that this is not suitablefor executableprograms since some platforms support multiplearchitectures using the same installed package directory.

Subdirectorypo is used for files related tolocalization:seeInternationalization.

Subdirectorytools is the preferred place for auxiliary filesneeded during configuration, and also for sources need to re-createscripts (e.g. M4 files forautoconf: some prefer to putthose in a subdirectorym4 oftools).

1.1.6 Data in packages ¶

Thedata subdirectory is for data files, either to be madeavailablevia lazy-loading or for loading usingdata().(The choice is made by the ‘LazyData’ field in theDESCRIPTION file: the default is not to do so.) It should not beused for other data files needed by the package, and the convention hasgrown up to use directoryinst/extdata for such files.

Data files can have one of three types as indicated by their extension:plain R code (.R or.r), tables (.tab,.txt, or.csv, see?data for the file formats, andnote that.csv isnot the standard²⁶ CSV format), orsave() images (.RData or.rda). The files shouldnot be hidden (have names starting with a dot). Note that R codeshould be if possible “self-sufficient” and not make use of extrafunctionality provided by the package, so that the data file can also beused without having to load the package or its namespace: it should runas silently as possible and not change thesearch() path byattaching packages or other environments.

Images (extensions.RData²⁷ or.rda) can containreferences to the namespaces of packages that were used to create them.Preferably there should be no such references in data files, and in anycase they should only be to packages listed in theDepends andImports fields, as otherwise it may be impossible to install thepackage. To check for such references, load all the images into avanilla R session, runstr() on all the datasets, and look atthe output ofloadedNamespaces().

Particular care is needed where a dataset or one of its components is ofan S4 class, especially if the class is defined in a different package.First, the package containing the class definition has to be availableto do useful things with the dataset, so that package must be listed inImports orDepends (even if this gives a check warningabout unused imports). Second, the definition of an S4 class canchange, and often is unnoticed when in a package with a differentauthor. So it may be wiser to use the.R form and use that tocreate the dataset object when needed (loading package namespaces butnot attaching them by usingrequireNamespace(pkg, quietly =TRUE) and usingpkg:: to refer to objects in thenamespace).

If you are not using ‘LazyData’ and either your data files are largeor e.g., you usedata/foo.R scripts to produce your data, loadingyour namespace, youcan speed up installation by providing a filedatalist in thedata subdirectory. This should have one line per topic thatdata() will find, in the format ‘foo’ ifdata(foo)provides ‘foo’, or ‘foo: bar bah’ ifdata(foo) provides‘bar’ and ‘bah’.R CMD build will automatically addadatalist file todata directories of over 1Mb, using thefunctiontools::add_datalist.

Tables (.tab,.txt, or.csv files) can becompressed bygzip,bzip2 orxz,optionally with additional extension.gz,.bz2 or.xz.

If your package is to be distributed, do consider the resourceimplications of large datasets for your users: they can make packagesvery slow to download and use up unwelcome amounts of storage space, aswell as taking many seconds to load. It is normally best to distributelarge datasets as.rda images prepared bysave(, compress =TRUE) (the default). Usingbzip2 orxz compressionwill usually reduce the size of both the package tarball and theinstalled package, in some cases by a factor of two or more.

Packagetools has a couple of functions to help with data images:checkRdaFiles reports on the way the image was saved, andresaveRdaFiles will re-save with a different type of compression,including choosing the best type for that particular image.

Many packages using ‘LazyData’ will benefit from using a form ofcompression other thangzip in the installed lazy-loadingdatabase. This can be selected by the--data-compress optiontoR CMD INSTALL or by using the ‘LazyDataCompression’field in theDESCRIPTION file. Useful values arebzip2,xz and the default,gzip: valuenone is alsoaccepted. The only way to discover which is best is to try them all andlook at the size of thepkgname/data/Rdata.rdb file. Afunction to do that (quoting sizes in KB) is

CheckLazyDataCompression <- function(pkg){    pkg_name <- sub("_.*", "", pkg)    lib <- tempfile(); dir.create(lib)    zs <- c("gzip", "bzip2", "xz")    res <- integer(3); names(res) <- zs    for (z in zs) {        opts <- c(paste0("--data-compress=", z),                  "--no-libs", "--no-help", "--no-demo", "--no-exec", "--no-test-load")        install.packages(pkg, lib, INSTALL_opts = opts, repos = NULL, quiet = TRUE)        res[z] <- file.size(file.path(lib, pkg_name, "data", "Rdata.rdb"))    }    ceiling(res/1024)}

(applied to a source package without any ‘LazyDataCompression’field).R CMD check will warn if it finds apkgname/data/Rdata.rdb file of more than 5MB without‘LazyDataCompression’ being set. If you see that, runCheckLazyDataCompression() and set the field – togzip inthe unlikely event²⁸ that is the best choice.

The analogue forsysdata.rda is field ‘SysDataCompression’:the default isxz for files bigger than 1MB otherwisegzip.

Lazy-loading is not supported for very large datasets (those which whenserialized exceed 2GB, the limit for the format on 32-bit platforms).

1.1.7 Non-R scripts in packages ¶

Code which needs to be compiled (C, C++, Fortran …)is included in thesrc subdirectory and discussed elsewhere inthis document.

Subdirectoryexec could be used for scripts for interpreters suchas the shell, BUGS, JavaScript, Matlab, Perl, PHP (amap),Python or Tcl (Simile), or even R. However, it seems morecommon to use theinst directory, for exampleWriteXLS/inst/Perl,NMF/inst/m-files,RnavGraph/inst/tcl,RProtoBuf/inst/python andemdbook/inst/BUGS andgridSVG/inst/js.

Java code is a special case: except for very small programs,.java files should be byte-compiled (to a.class file) anddistributed as part of a.jar file: the conventional location forthe.jar file(s) isinst/java. It is desirable (andrequired under an Open Source license) to make the Java source filesavailable: this is best done in a top-leveljava directory in thepackage—the source files should not be installed.

If your package requires one of these interpreters or an extension thenthis should be declared in the ‘SystemRequirements’ field of itsDESCRIPTION file. (Users of Java most often do soviarJava, when depending on/importing that suffices unless thereis a version requirement on Java code in the package.)

Windows and Mac users should be aware that the Tcl extensions‘BWidget’ and ‘Tktable’ (which have sometimes been included inthe Windows²⁹ and macOS R installers)are extensions and do need to be declared (and that‘Tktable’ is less widely available than it used to be, includingnot in the main repositories for major Linux distributions).‘BWidget’ needs to be installed by the user on other OSes. This isfairly easy to do: first find the Tcl search path:

library(tcltk)strsplit(tclvalue('auto_path'), " ")[[1]]

then download the sources fromhttps://sourceforge.net/projects/tcllib/files/BWidget/and in a terminal run something like

tar xf bwidget-1.9.14.tar.gzsudo mv bwidget-1.9.14 /usr/local/lib

substituting a location on the Tcl search path for/usr/local/lib ifneeded. (If no location on that search path is writeable, you will needto add one each time ‘BWidget’ is to be used withtcltk::addTclPath().)

To (silently) test for the presence of ‘Tktable’ one can use

library(tcltk)have_tktable <- !isFALSE(suppressWarnings(tclRequire('Tktable')))

Installing ‘Tktable’ needs a C compiler and the Tk headers (notnecessarily installed with Tcl/Tk). At the time of writing the latestsources (from 2008) were available fromhttps://sourceforge.net/projects/tktable/files/tktable/2.10/Tktable2.10.tar.gz/download,but needed patching for current Tk (8.6.11, but not 8.6.10) – a patchcan be found athttps://www.stats.ox.ac.uk/pub/bdr/Tktable/. Fora system installation of Tk you may need to install ‘Tktable’ as‘root’ as on e.g. Fedora all the locations onauto_pathare owned by ‘root’.

1.1.8 Specifying URLs ¶

URLs in many places in the package documentation will be converted toclickable hyperlinks in at least some of their renderings. So care isneeded that their forms are correct and portable.

The full URL should be given, including the scheme (often ‘http://’or ‘https://’) and a final ‘/’ for references to directories.

Spaces in URLs are not portable and how they are handled does vary byHTTP server and by client. There should be no space in the host part ofan ‘http://’ URL, and spaces in the remainder should be encoded,with each space replaced by ‘%20’.

Reserved characters should be encoded unless used in their reservedsense: see the help onURLencode().

The canonical URL for aCRAN package is

https://cran.r-project.org/package=pkgname

and not a version starting‘https://cran.r-project.org/web/packages/pkgname’.

Next:Checking and building packages, Previous:Package structure, Up:Creating R packages   [Contents][Index]

LDFLAGS=`"${R_HOME}/bin/R" CMD config LDFLAGS`

CXX=`"${R_HOME}/bin/R" CMD config CXX`if test -z "$CXX"; then  AC_MSG_ERROR([No C++ compiler is available])fiCXXFLAGS=`"${R_HOME}/bin/R" CMD config CXXFLAGS`CPPFLAGS=`"${R_HOME}/bin/R" CMD config CPPFLAGS`AC_LANG(C++)

CC CFLAGS CXX CXXFLAGS CPPFLAGS LDFLAGS FC FCFLAGS

#!/bin/shrm -f config.* src/Makevars src/config.h

$ pkg-config --exists 'libtiff-4 >= 4.1.0' --print-errors # check the status$ pkg-config --modversion libtiff-44.3.0$ pkg-config --cflags libtiff-4-I/usr/local/include$ pkg-config --libs libtiff-4-L/usr/local/lib -ltiff$ pkg-config --static --libs libtiff-4-L/usr/local/lib -ltiff -lwebp -llzma -ljpeg -lz

pkg-config --list-all | sort

curl-config   freetype-config  gdal-config    geos-configgsl-config    iodbc-config     libpng-config  nc-configpcre-config   pcre2-config     xml2-config    xslt-config

m4_include([tools/ax_pthread.m4])

AC_CONFIG_MACRO_DIR([tools/m4])

1.2.1 UsingMakevars ¶

Sometimes writing your ownconfigure script can be avoided bysupplying a fileMakevars: also one of the most common uses of aconfigure script is to makeMakevars fromMakevars.in.

AMakevars file is a makefile and is used as one of severalmakefiles byR CMD SHLIB (which is called byR CMDINSTALL to compile code in thesrc directory). It should bewritten if at all possible in a portable style, in particular (exceptforMakevars.win andMakevars.ucrt) without the use of GNUextensions.

The most common use of aMakevars file is to set additionalpreprocessor options (for example include paths and definitions) forC/C++ filesviaPKG_CPPFLAGS, and additional compilerflags by settingPKG_CFLAGS,PKG_CXXFLAGS orPKG_FFLAGS, for C, C++ or Fortran respectively (seeCreating shared objects).

N.B.: Include paths are preprocessor options, not compileroptions, andmust be set inPKG_CPPFLAGS as otherwiseplatform-specific paths (e.g. ‘-I/usr/local/include’) will takeprecedence.PKG_CPPFLAGS should contain ‘-I’, ‘-D’,‘-U’ and (where supported) ‘-include’ and ‘-pthread’options: everything else should be a compiler flag. The order of flagsmatters, and using ‘-I’ inPKG_CFLAGS orPKG_CXXFLAGShas led to hard-to-debug platform-specific errors.

Makevars can also be used to set flags for the linker, forexample ‘-L’ and ‘-l’ options,viaPKG_LIBS.

When writing aMakevars file for a package you intend todistribute, take care to ensure that it is not specific to yourcompiler: flags such as-O2 -Wall -pedantic (and all other-W flags: for the Oracle compilers these were used to passarguments to compiler phases) are all specific to GCC (and compilers suchasclang which aim to be options-compatible with it).

Also, do not set variables such asCPPFLAGS,CFLAGS etc.:these should be settable by users (sites) through appropriate personal(site-wide)Makevars files.SeeCustomizing package compilation inR Installation and Administrationfor more information.

There are some macros³⁷ which are set whilst configuring thebuilding of R itself and are stored inR_HOME/etcR_ARCH/Makeconf. That makefile is includedas aMakefileafterMakevars[.win], and the macrosit defines can be used in macro assignments and make command lines inthe latter. These include

FLIBS ¶

A macro containing the set of libraries need to link Fortran code. Thismay need to be included inPKG_LIBS: it will normally be includedautomatically if the package contains Fortran source files in thesrc directory.

BLAS_LIBS ¶

A macro containing the BLAS libraries used when building R. This mayneed to be included inPKG_LIBS. Beware that if it is empty thenthe R executable will contain all the double-precision anddouble-complex BLAS routines, but no single-precision nor complexroutines. IfBLAS_LIBS is included, thenFLIBS also needsto be³⁸ included following it, as most BLASlibraries are written at least partially in Fortran. However, it canbe omitted if the package contains Fortran source code as that will addFLIBS to the link line.

LAPACK_LIBS ¶

A macro containing the LAPACK libraries (and paths where appropriate)used when building R. This may need to be included inPKG_LIBS. It may point to a dynamic librarylibRlapackwhich contains the main double-precision LAPACK routines as well asthose double-complex LAPACK routines needed to build R, or it maypoint to an external LAPACK library, or may be empty if an external BLASlibrary also contains LAPACK.

[libRlapack includes all the double-precision LAPACK routineswhich were current in 2003 and a few more recent ones: a list of whichroutines are included is in filesrc/modules/lapack/README. Notethat an external LAPACK/BLAS library need not do so, as some were‘deprecated’ (and not compiled by default) in LAPACK 3.6.0 in late2015.]

For portability, the macrosBLAS_LIBS andFLIBS shouldalways be includedafterLAPACK_LIBS (and in that order).

SAFE_FFLAGS ¶

A macro containing flags which are needed to circumventover-optimization of FORTRAN code: it is might be ‘-g -O2-ffloat-store’ or ‘-g -O2 -msse2 -mfpmath=sse’ on ‘ix86’platforms usinggfortran. Note that this isnot anadditional flag to be used as part ofPKG_FFLAGS, but areplacement forFFLAGS. See the example later in this section.

Setting certain macros inMakevars will preventR CMDSHLIB setting them: in particular ifMakevars sets‘OBJECTS’ it will not be set on themake command line.This can be useful in conjunction with implicit rules to allow othertypes 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 insrc or including some files insubdirectories. For example

OBJECTS = 4dfp/endianio.o 4dfp/Getifh.o R4dfp-object.o

Note thatMakevars should not normally contain targets, as it isincluded before the default makefile andmake will call thefirst target, intended to beall in the default makefile. If youreally need to circumvent that, use a suitable (phony) targetallbefore any actual targets inMakevars.[win]: for example packagefastICA used to have

PKG_LIBS = @BLAS_LIBS@SLAMC_FFLAGS=$(R_XTRA_FFLAGS) $(FPICFLAGS) $(SHLIB_FFLAGS) $(SAFE_FFLAGS)all: $(SHLIB)slamc.o: slamc.f        $(FC) $(SLAMC_FFLAGS) -c -o slamc.o slamc.f

needed to ensure that the LAPACK routines find some constants withoutinfinite looping. The Windows equivalent was

all: $(SHLIB)slamc.o: slamc.f        $(FC) $(SAFE_FFLAGS) -c -o slamc.o slamc.f

(since the other macros are all empty on that platform, and R’sinternal BLAS was not used). Note that the first target inMakevars will be called, but for back-compatibility it is bestnamedall.

If you want to create and then link to a library, say using code in asubdirectory, use something like

.PHONY: all mylibsall: $(SHLIB)$(SHLIB): mylibsmylibs:        (cd subdir; $(MAKE))

Be careful to create all the necessary dependencies, as there is noguarantee that the dependencies ofall will be run in aparticular order (and some of theCRAN build machines usemultiple CPUs and parallel makes). In particular,

all: mylibs

doesnot suffice. GNU make does allow the construct

.NOTPARALLEL: allall: mylibs $(SHLIB)

but that is not portable.dmake andpmake allow thesimilar.NO_PARALLEL, also not portable: some variants ofpmake accept.NOTPARALLEL as an alias for.NO_PARALLEL.

Note that on Windows it is required thatMakevars[.win, .ucrt] doescreate a DLL: this is needed as it is the only reliable way to ensurethat building a DLL succeeded. If you want to use thesrcdirectory for some purpose other than building a DLL, use aMakefile.win orMakefile.ucrt file.

It is sometimes useful to have a target ‘clean’ inMakevars,Makevars.win orMakevars.ucrt:this will be used byR CMD build toclean up (a copy of) the package sources. When it is run bybuild it will have fewer macros set, in particular not$(SHLIB), nor$(OBJECTS) unless set in the file itself.It would also be possible to add tasks to the target ‘shlib-clean’which is run byR CMD INSTALL andR CMD SHLIB withoptions--clean and--preclean.

Avoid the use of default (also known as ‘implicit’ rules) in makefiles,as these aremake-specific. Even when mandated by POSIX –GNUmake does not comply and this has broken packageinstallation.

An unfortunately common error is to have

all: $(SHLIB) clean

which asksmake to clean in parallel with compiling the code.Not only does this lead to hard-to-debug installation errors, it wipesout all the evidence of any error (from a parallel make or not). It ismuch better to leave cleaning to the end user using the facilities inthe previous paragraph.

If you want to run R code inMakevars, e.g. to findconfiguration information, please do ensure that you use the correctcopy ofR orRscript: there might not be one in the pathat all, or it might be the wrong version or architecture. The correctway to do this isvia

"$(R_HOME)/bin$(R_ARCH_BIN)/Rscript"filename"$(R_HOME)/bin$(R_ARCH_BIN)/Rscript" -e 'R expression'

where$(R_ARCH_BIN) is only needed currently on Windows.

Environment or make variables can be used to select different macros forIntel 64-bit code or code for other architectures, for example(GNUmake syntax, allowed on Windows)

ifeq "$(WIN)" "64"PKG_LIBS =value for 64-bit Intel WindowselsePKG_LIBS =value for unknown Windows architecturesendif

On Windows there is normally a choice between linking to an importlibrary or directly to a DLL. Where possible, the latter is much morereliable: import libraries are tied to a specific toolchain, and inparticular on 64-bit Windows two different conventions have beencommonly used. So for example instead of

PKG_LIBS = -L$(XML_DIR)/lib -lxml2

one can use

PKG_LIBS = -L$(XML_DIR)/bin -lxml2

since on Windows-lxxx will look in turn for

libxxx.dll.axxx.dll.alibxxx.axxx.liblibxxx.dllxxx.dll

where the first and second are conventionally import libraries, thethird and fourth often static libraries (with.lib intended forVisual C++), but might be import libraries. See for examplehttps://sourceware.org/binutils/docs-2.20/ld/WIN32.html#WIN32.

The fly in the ointment is that the DLL might not be namedlibxxx.dll, and in fact on 32-bit Windows there was alibxml2.dll whereas on one build for 64-bit Windows the DLL iscalledlibxml2-2.dll. Using import libraries can cover overthese differences but can cause equal difficulties.

If static libraries are available they can save a lot of problems withrun-time finding of DLLs, especially when binary packages are to bedistributed and even more when these support both architectures. Whereusing DLLs is unavoidable we normally arrange (viaconfigure.win orconfigure.ucrt) to ship them in the same directory as the packageDLL.

• OpenMP support
• Using pthreads
• Compiling in sub-directories

SHLIB_OPENMP_CFLAGSSHLIB_OPENMP_CXXFLAGSSHLIB_OPENMP_FFLAGS

PKG_CFLAGS = $(SHLIB_OPENMP_CFLAGS)PKG_LIBS = $(SHLIB_OPENMP_CFLAGS)

PKG_FFLAGS = $(SHLIB_OPENMP_FFLAGS)PKG_LIBS = $(SHLIB_OPENMP_CFLAGS)

USE_FC_TO_LINK =PKG_FFLAGS = $(SHLIB_OPENMP_FFLAGS)PKG_LIBS = $(SHLIB_OPENMP_FFLAGS)

use omp_lib

  undefined symbol: __atomic_compare_exchange  undefined symbol: __atomic_load

#pragma omp parallel for num_threads(nthreads) ...

PKG_CPPFLAGS = -pthreadPKG_LIBS = -pthread

PKG_CPPFLAGS = -D_REENTRANTPKG_LIBS = -lpthread

SOURCES = $(wildcard data/*.cpp network/*.cpp utils/*.cpp model/*.cpp model/*/*.cpp model/*/*/*.cpp)OBJECTS = siena07utilities.o siena07internals.o siena07setup.o siena07models.o $(SOURCES:.cpp=.o)

OBJECTS.samplers = samplers/ExpandableArray.o samplers/Knots.o \  samplers/RJumpSpline.o samplers/RJumpSplineFactory.o \  samplers/RealSlicerOV.o samplers/SliceFactoryOV.o samplers/MNorm.oOBJECTS.distributions = distributions/DSpline.o \  distributions/DChisqrOV.o distributions/DTOV.o \  distributions/DNormOV.o distributions/DUnifOV.o distributions/RScalarDist.oOBJECTS.root = RJump.oOBJECTS = $(OBJECTS.samplers) $(OBJECTS.distributions) $(OBJECTS.root)

PKG_LIBS = -LCsdp/lib -lsdp $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)$(SHLIB): Csdp/lib/libsdp.aCsdp/lib/libsdp.a:        @(cd Csdp/lib && $(MAKE) libsdp.a \          CC="$(CC)" CFLAGS="$(CFLAGS) $(CPICFLAGS)" AR="$(AR)" RANLIB="$(RANLIB)")

1.2.2 Configure example ¶

It may be helpful to give an extended example of using aconfigure script to create asrc/Makevars file: this isbased on that in theRODBC package.

Theconfigure.ac file follows:configure is created fromthis by runningautoconf in the top-level package directory(containingconfigure.ac).

AC_INIT([RODBC], 1.1.8) dnl package name, versiondnl A user-specifiable optionodbc_mgr=""AC_ARG_WITH([odbc-manager],            AC_HELP_STRING([--with-odbc-manager=MGR],                           [specify the ODBC manager, e.g. odbc or iodbc]),            [odbc_mgr=$withval])if test "$odbc_mgr" = "odbc" ; then  AC_PATH_PROGS(ODBC_CONFIG, odbc_config)fidnl Select an optional include path, from a configure optiondnl or from an environment variable.AC_ARG_WITH([odbc-include],            AC_HELP_STRING([--with-odbc-include=INCLUDE_PATH],                           [the location of ODBC header files]),            [odbc_include_path=$withval])RODBC_CPPFLAGS="-I."if test [ -n "$odbc_include_path" ] ; then   RODBC_CPPFLAGS="-I. -I${odbc_include_path}"else  if test [ -n "${ODBC_INCLUDE}" ] ; then     RODBC_CPPFLAGS="-I. -I${ODBC_INCLUDE}"  fifidnl ditto for a library pathAC_ARG_WITH([odbc-lib],            AC_HELP_STRING([--with-odbc-lib=LIB_PATH],                           [the location of ODBC libraries]),            [odbc_lib_path=$withval])if test [ -n "$odbc_lib_path" ] ; then   LIBS="-L$odbc_lib_path ${LIBS}"else  if test [ -n "${ODBC_LIBS}" ] ; then     LIBS="-L${ODBC_LIBS} ${LIBS}"  else    if test -n "${ODBC_CONFIG}"; then      odbc_lib_path=`odbc_config --libs | sed s/-lodbc//`      LIBS="${odbc_lib_path} ${LIBS}"    fi  fifidnl Now find the compiler and compiler flags to use: ${R_HOME=`R RHOME`}if test -z "${R_HOME}"; then  echo "could not determine R_HOME"  exit 1fiCC=`"${R_HOME}/bin/R" CMD config CC`CFLAGS=`"${R_HOME}/bin/R" CMD config CFLAGS`CPPFLAGS=`"${R_HOME}/bin/R" CMD config CPPFLAGS`if test -n "${ODBC_CONFIG}"; then  RODBC_CPPFLAGS=`odbc_config --cflags`fiCPPFLAGS="${CPPFLAGS} ${RODBC_CPPFLAGS}"dnl Check the headers can be foundAC_CHECK_HEADERS(sql.h sqlext.h)if test "${ac_cv_header_sql_h}" = no ||   test "${ac_cv_header_sqlext_h}" = no; then   AC_MSG_ERROR("ODBC headers sql.h and sqlext.h not found")fidnl search for a library containing an ODBC functionif test [ -n "${odbc_mgr}" ] ; then  AC_SEARCH_LIBS(SQLTables, ${odbc_mgr}, ,      AC_MSG_ERROR("ODBC driver manager ${odbc_mgr} not found"))else  AC_SEARCH_LIBS(SQLTables, odbc odbc32 iodbc, ,      AC_MSG_ERROR("no ODBC driver manager found"))fidnl for 64-bit ODBC need SQL[U]LEN, and it is unclear where they are defined.AC_CHECK_TYPES([SQLLEN, SQLULEN], , , [# include <sql.h>])dnl for unixODBC headerAC_CHECK_SIZEOF(long, 4)dnl substitute RODBC_CPPFLAGS and LIBSAC_SUBST(RODBC_CPPFLAGS)AC_SUBST(LIBS)AC_CONFIG_HEADERS([src/config.h])dnl and do substitution in the src/Makevars.in and src/config.hAC_CONFIG_FILES([src/Makevars])AC_OUTPUT

wheresrc/Makevars.in would be simply

PKG_CPPFLAGS = @RODBC_CPPFLAGS@PKG_LIBS = @LIBS@

A user can then be advised to specify the location of theODBCdriver manager files by options like (lines broken for easier reading)

R CMD INSTALL \  --configure-args='--with-odbc-include=/opt/local/include \  --with-odbc-lib=/opt/local/lib --with-odbc-manager=iodbc' \  RODBC

or by setting the environment variablesODBC_INCLUDE andODBC_LIBS.

1.2.3 Using modern Fortran code ¶

R assumes that source files with extension.f are fixed-formFortran 90 (which includes Fortran 77), and passes them to the compilerspecified by macro ‘FC’. The Fortran compiler will also acceptfree-form Fortran 90/95 code with extension.f90 or(most⁴⁷).f95.

The same compiler is used for both fixed-form and free-form Fortran code(with different file extensions and possibly different flags). MacroPKG_FFLAGS can be used for package-specific flags: for theun-encountered case that both are included in a single package and thatdifferent flags are needed for the two forms, macroPKG_FCFLAGSis also available for free-form Fortran.

The code used to build R allows a ‘Fortran 90’ compiler to beselected as ‘FC’, so platforms might be encountered which onlysupport Fortran 90. However, Fortran 95 is supported on all knownplatforms.

Most compilers specified by ‘FC’ will accept most Fortran 2003,2008 or 2018 code: such code should still use file extension.f90. Most current platforms usegfortran where youmight need to include-std=f2003,-std=f2008 or (fromversion 8)-std=f2018 inPKG_FFLAGS orPKG_FCFLAGS: the default is ‘GNU Fortran’, currently Fortran 2018(but Fortran 95 prior togfortran 8) with non-standardextensions. The other compilers in current use (LLVM’sflang (calledflang-new before version 20) and Intel’sifx) default to Fortran 2018⁴⁸.

It is good practice to describe a Fortran version requirement inDESCRIPTION’s ‘SystemRequirements’ field. Note that this ispurely for information: the package also needs aconfigurescript to determine the compiler and set appropriate option(s) and testthat the features needed from the standard are actually supported.

The Fortran 2023 released in Nov 2023: as usual compiler vendors areintroducing support incrementally.For Intel’sifx seehttps://www.intel.com/content/www/us/en/developer/articles/technical/fortran-language-and-openmp-features-in-ifx.html#Fortran%20Standards.For LLVM’sflang seehttps://flang.llvm.org/docs/F202X.html.gfortran does not have complete support even for the 2008 and2018 standards, but the option-std=f2023 is supported fromversion 14.1.

Modern versions of Fortran support modules, whereby compiling one sourcefile creates a module file which is then included in others. (Modulefiles typically have a.mod extension: they do depend on thecompiler used and so should never be included in a package.) Thiscreates a dependence whichmake will not know about and oftencauses installation with a parallel make to fail. Thus it is necessaryto add explicit dependencies tosrc/Makevars to tellmake the constraints on the order of compilation. Forexample, if fileiface.f90 creates a module ‘iface’ used byfilescmi.f90 anddmi.f90 thensrc/Makevars needsto contain something like

cmi.o dmi.o: iface.o

Some maintainers have found it difficult to findall the moduledependencies which leads to hard-to-reproduce installation failures.There are tools available to find these, including the Intel compiler’sflag-gen-dep andmakedepf90.

Note that it is not portable (although some platforms do accept it) todefine a module of the same name in multiple source files.

1.2.4 Using C++ code ¶

R can be built without a C++ compiler although one is available (butnot necessarily installed) on all known R platforms. As from R4.0.0 a C++ compiler will be selected only if it conforms to the 2011standard (‘C++11’). A minor update⁴⁹ (‘C++14’) was published inDecember 2014 and was used by default as from R 4.1.0 if supported.Further revisions ‘C++17’ (in December 2017), ‘C++20’ (with many newfeatures in December 2020) and ‘C++23’ (in October 2024) have beenpublished since. The next revision, ‘C++26’, is expected in 2026/7 andseveral compilers already have considerable support for the currentdraft.

The support in R for these standards has varied over the years: thisversion of the manual only describes R 4.3.0 and later. For detailsof earlier versions, see the corresponding section in their manuals.

The default standard for compiling R packages was changed to C++17 inR 4.3.0 if supported, and from R 4.4.0 only a C++17 compiler willbe selected as the default C++ compiler.

What standard a C++ compiler aims to support can be hard to determine:the value⁵⁰ of__cplusplus may help butsome compilers use it to denote a standard which is partially supportedand some the latest standard which is (almost) fully supported. On aUnix-alikeconfigure will try to identify a compiler and flagsfor each of the standards: this relies heavily on the reported values of__cplusplus.

The webpagehttps://en.cppreference.com/w/cpp/compiler_supportgives some information on which compiler versions are known to supportrecent C++ features.

C++ standards have deprecated and later removed features. Be aware thatsome current compilers still accept removed features in C++17 mode,such asstd::unary_function (deprecated in C++11, removed in C++17).

For maximal portability a package should specify the standard itrequires for code in itssrc directory by including somethinglike ‘C++14’ in the ‘SystemRequirements’ field of theDESCRIPTION file, e.g.

SystemRequirements: C++14

If it has aMakevars file (orMakevars.win orMakevars.ucrt on Windows) this should include the line

CXX_STD = CXX14

On the other hand, specifying C++11⁵¹ when the code is valid under C++14 or C++17reduces future portability.

Code needing C++14 or later features can check for their presencevia‘SD-6 feature tests’⁵². Such a check could be

#include <memory> // header where this is defined#if defined(__cpp_lib_make_unique) && (__cpp_lib_make_unique >= 201304)using std::make_unique;#else// your emulation#endif

C++17, C++20, C++23 and C++26 (from R 4.5.0) can be specified in ananalogous way.

Note that C++17 or later ‘support’ does not mean complete support: usefeature tests as well as resources such ashttps://en.cppreference.com/w/cpp/compiler_support,https://gcc.gnu.org/projects/cxx-status.html andhttps://clang.llvm.org/cxx_status.html to see if the features youwant to use are widely implemented.

Attempts to specify an unknown C++ standard are silently ignored: recentversions of R throw an error for C++98 and for known standards forwhich no compiler+flags has been detected.

If a package using C++ has aconfigure script it is essentialthat the script selects the correct C++ compiler and standard,via something like

CXX17=`"${R_HOME}/bin/R" CMD config CXX17`if test -z "$CXX17"; then  AC_MSG_ERROR([No C++17 compiler is available])fiCXX17STD=`"${R_HOME}/bin/R" CMD config CXX17STD`CXX="${CXX17} ${CXX17STD}"CXXFLAGS=`"${R_HOME}/bin/R" CMD config CXX17FLAGS`## for an configure.ac fileAC_LANG(C++)

if C++17 was specified, but using

CXX=`"${R_HOME}/bin/R" CMD config CXX`CXXFLAGS=`"${R_HOME}/bin/R" CMD config CXXFLAGS`## for an configure.ac fileAC_LANG(C++)

if no standard was specified.

If you want to compile C++ code in a subdirectory, make sure you passdown the macros to specify the appropriate compiler, e.g. insrc/Makevars

sublibs:         @(cd libs && $(MAKE) \            CXX="$(CXX17) $(CXX17STD)" CXXFLAGS="$(CXX17FLAGS) $(CXX17PICFLAGS)")

The discussion above is about the standard R ways of compiling C++:it will not apply to packages usingsrc/Makefile or building in asubdirectory that do not set the C++ standard. Do not rely on thecompilers’ default C++ standard, which varies widely and gets changedfrequently by vendors – for example Apple clang up to at least 16defaults to C++98, LLVM clang 14–15 to C++14, LLVM clang 16–20andg++ 11–15 to C++17.

For a package with asrc/Makefile (or a Windows analogue),a non-default C++ compiler can be selected by including something like

CXX14 = `"${R_HOME}/bin/R" CMD config CXX14`CXX14STD = `"${R_HOME}/bin/R" CMD config CXX14STD`CXX = ${CXX14} ${CXX14STD}CXXFLAGS = `"${R_HOME}/bin/R" CMD config CXX14FLAGS`CXXPICFLAGS = `"${R_HOME}/bin/R" CMD config CXX14PICFLAGS`SHLIB_LD = "${R_HOME}/bin/R" CMD config SHLIB_CXX14LD`SHLIB_LDFLAGS = "${R_HOME}/bin/R" CMD config SHLIB_CXX14LDFLAGS`

and ensuring these values are used in relevant compilations, afterchecking they are non-empty. A common use ofsrc/Makefile is tocompile an executable, when likely something like (for example forC++14)

if test -z "$CXX14"; then  AC_MSG_ERROR([No C++14 compiler is available])fiCXX = ${CXX14} ${CXX14STD}CXXFLAGS = ${CXX14FLAGS}

suffices.

The.so/.dll in a package may need to be linked by theC++ compiler if it or any library it links to contains compiled C++code. Dynamic linking usually brings in the C++ runtime library(commonlylibstdc++ but can be, for example,libc++) butstatic linking (as used for external libraries on Windows and macOS)will not.R CMD INSTALL will link with the C++ compiler ifthere are any top-level C++ files insrc, but not if these areall in subdirectories. The simplest way to force linking by the C++compiler is to include an empty C++ file insrc..

1.2.5 C standards ¶

C has had standards C89/C90, C99, C11, C17 (also known as C18), and C23(published in 2024). C11 was a minor change to C99 which introducedsome new features and made others optional, and C17 is a ‘bug-fix’update to C11. On the other hand, C23 makes extensive changes,including makingbool,true andfalse reservedwords, finally disallowing K&R-style function declarations and changingthe formerly deprecated meaning of function declarations with an emptyparameter list to now mean no parameters.⁵³(There are many other additions: see for examplehttps://en.cppreference.com/w/c/23.)

As from R 4.5.0, R’sconfigure script chooses a compileroption which selects C23 if one is available. Some compilers (includinggcc 15) default to C23 and most others from 2022/3 andlater have such an option.

Theconfigure script in recent previous versions of R aimedto choose a C compiler which supported C11: as the default in recentversions ofgcc (prior to 15), LLVMclang andAppleclang is C17, that is what is likely to be chosen. Onthe other hand, until R 4.3.0 the makefiles for the Windows buildspecified C99 and up to R 4.4.3 used the compiler default which forthe recommended compiler was C17.

Packages may want to either avoid or embrace the changes in C23, and cando sovia specifying ‘USE_Cnn’ for 17, 23, 90 or 99 in the‘SystemRequirements’ field of theirDESCRIPTION file of apackage depending on ‘R (>= 4.3.0)’. Those using aconfigure script should set the corresponding compiler andflags, for example using

CC=`"${R_HOME}/bin/R" CMD config CC23`CFLAGS=`"${R_HOME}/bin/R" CMD config C23FLAGS`CPPFLAGS=`"${R_HOME}/bin/R" CMD config CPPFLAGS`LDFLAGS=`"${R_HOME}/bin/R" CMD config LDFLAGS`

However, not all platforms will have a C23 compiler: the first line herewill give an empty value if no C23 compiler was found.

The (claimed) C standard in use can be checked by the macro__STDC_VERSION__. This is undefined in C89/C90 and should havevalues199901L,201112L and201710L for C99, C11and C17. The definitive value for C23 is202311L but somecompilers⁵⁴ are currently using202000L and requiring the standard tobe specified asc2x.C23 has macros similar to C++ ‘feature tests’ for many of its changes,for example__STDC_VERSION_LIMITS_H__.

However, note the ‘claimed’ as no compiler had 100% conformance, and itis better to useconfigure to test for the feature you want touse than to condition on the value of__STDC_VERSION__. Inparticular, C11 alignment functionality such as_Alignas andaligned_alloc is not implemented on Windows.

End users installing a source package can specify a standard bysomething likeR CMD INSTALL --use-C17. This overrides the‘SystemRequirements’ field, but not anyconfigure file.

1.2.6 Usingcmake ¶

Packages often wish to include the sources of other software and compilethat for inclusion in their.so or.dll, which is normallydone by including (or unpacking) the sources in a subdirectory ofsrc, as considered above.

Further issues arise when the external software uses another buildsystem such ascmake, principally to ensure thatall the settings for compilers, include and load pathsetcare made. This section has already mentioned the need to setat least some of

CC CFLAGS CXX CXXFLAGS CPPFLAGS LDFLAGS

CFLAGS andCXXFLAGS will need to includeCPICFLAGSandCXXPICFLAGS respectively unless (as below)cmake isasked to generate PIC code.

Setting these (and more) as environment variables controls the behaviourofcmake(https://cmake.org/cmake/help/latest/manual/cmake-env-variables.7.html#manual:cmake-env-variables(7)),but it may be desirable to translate these into native settings such as

CMAKE_C_COMPILERCMAKE_C_FLAGSCMAKE_CXX_COMPILERCMAKE_CXX_FLAGSCMAKE_INCLUDE_PATHCMAKE_LIBRARY_PATHCMAKE_SHARED_LINKER_FLAGS_INITCMAKE_OSX_DEPLOYMENT_TARGET

and it is often necessary to ensure a static library of PIC code is built by

-DBUILD_SHARED_LIBS:bool=OFF-DCMAKE_POSITION_INDEPENDENT_CODE:bool=ON

If R is to be detected or used, this must be the build being used forpackage installation –"${R_HOME}"/bin/R.

To fix ideas, consider a package with sources for a librarymyLibundersrc/libs. Two approaches have been used. It is often mostconvenient to build the external software in a directory other than itssources (particularly during development when the build directory can beremoved between builds rather than attempting to clean the sources) –this is illustrated in the first approach.

1. Use the package’sconfigure script to create a static librarysrc/build/libmyLib.a. This can then be treated in the same wayas external software, for example having insrc/Makevars

   PKG_CPPFLAGS = -Ilibs/includePKG_LIBS = build/libmyLib.a

   (-Lbuild -lmyLib could also be used but this explicitspecification avoids any confusion with dynamic libraries of the samename.)

   Theconfigure script will need to contain something like (for Ccode)

   : ${R_HOME=`R RHOME`}if test -z "${R_HOME}"; then  echo "could not determine R_HOME"  exit 1fiCC=`"${R_HOME}/bin/R" CMD config CC`CFLAGS=`"${R_HOME}/bin/R" CMD config CFLAGS`CPPFLAGS=`"${R_HOME}/bin/R" CMD config CPPFLAGS`LDFLAGS=`"${R_HOME}/bin/R" CMD config LDFLAGS`cd srcmkdir build && cd buildcmake -S ../libs \  -DCMAKE_BUILD_TYPE=Release \  -DBUILD_SHARED_LIBS:bool=OFF \  -DCMAKE_POSITION_INDEPENDENT_CODE:bool=ON${MAKE}

2. Usesrc/Makevars (orsrc/Makevars.win orMakevars.ucrt) to build within thesubdirectory. This could be something like (for C code)

   PKG_CPPFLAGS = -Ilibs/includePKG_LIBS = libs/libmyLib.a$(SHLIB): mylibsmylibs:        (cd libs; \          CC="$(CC)" CFLAGS="$(CFLAGS)" \          CPPFLAGS="$(CPPFLAGS)" LDFLAGS="$(LDFLAGS)" \          cmake . \            -DCMAKE_BUILD_TYPE=Release \            -DBUILD_SHARED_LIBS:bool=OFF \            -DCMAKE_POSITION_INDEPENDENT_CODE:bool=ON; \          $(MAKE))

   the compiler and other settings having been set as Make variables by anR makefile included byINSTALL beforesrc/Makevars.

A complication is that on macOScmake (where installed) iscommonly not on the path but at/Applications/CMake.app/Contents/bin/cmake. One way to workaround this is for the package’sconfigure script to include

if test -z "$CMAKE"; then CMAKE="`which cmake`"; fiif test -z "$CMAKE"; then CMAKE=/Applications/CMake.app/Contents/bin/cmake; fiif test -f "$CMAKE"; then echo "no 'cmake' command found"; exit 1; fi

and for the second approach to substituteCMAKE intosrc/Makevars. This also applies to the ancillary commandctest, if used.

Next:Writing package vignettes, Previous:Configure and cleanup, Up:Creating R packages   [Contents][Index]

1.3.1 Checking packages ¶

UsingR CMD check, the R package checker, one can test whethersource R packages work correctly. It can be run on one ormore directories, or compressed packagetar archives withextension.tar.gz,.tgz,.tar.bz2 or.tar.xz.

It is strongly recommended that the final checks are run on atar archive prepared byR CMD build.

This runs a series of checks, including

1. The package is installed. This will warn about missing cross-referencesand duplicate aliases in help files.
2. The file names are checked to be valid across file systems and supportedoperating system platforms.
3. The files and directories are checked for sufficient permissions(Unix-alikes only).
4. The files are checked for binary executables, using a suitable versionoffile if available⁵⁶. (There may berare false positives.)
5. TheDESCRIPTION file is checked for completeness, and some of itsentries for correctness. Unless installation tests are skipped,checking is aborted if the package dependencies cannot be resolved atrun time. (You may need to setR_LIBS in the environment ifdependent packages are in a separate library tree.) One check is thatthe package name is not that of a standard package, nor one of thedefunct standard packages (‘ctest’, ‘eda’, ‘lqs’,‘mle’, ‘modreg’, ‘mva’, ‘nls’, ‘stepfun’ and‘ts’). Another check is that all packages mentioned inlibrary orrequires or from which theNAMESPACEfile imports or are calledvia:: or::: are listed(in ‘Depends’, ‘Imports’, ‘Suggests’): this is not anexhaustive check of the actual imports.
6. Available index information (in particular, for demos and vignettes) ischecked for completeness.
7. The package subdirectories are checked for suitable file names and fornot being empty. The checks on file names are controlled by the option--check-subdirs=value. This defaults to ‘default’,which runs the checks only if checking a tarball: the default can beoverridden by specifying the value as ‘yes’ or ‘no’. Further,the check on thesrc directory is only run if the packagedoes not contain aconfigure script (which corresponds to thevalue ‘yes-maybe’) and there is nosrc/Makefile orsrc/Makefile.in.

   To allow aconfigure script to generate suitable files, filesending in ‘.in’ will be allowed in theR directory.

   A warning is given for directory names that look like R package checkdirectories – many packages have been submitted toCRANcontaining these.

8. The R files are checked for syntax errors. Bytes which arenon-ASCII are reported as warnings, but these should beregarded as errors unless it is known that the package will always beused in the same locale.
9. It is checked that the package can be loaded, first with the usualdefault packages and then only with packagebase alreadyloaded. It is checked that the namespace can be loaded in an emptysession with only thebase namespace loaded. (Namespaces andpackages can be loaded very early in the session, before the defaultpackages are available, so packages should work then.)
10. The R files are checked for correct calls tolibrary.dynam.Package startup functions are checked for correct argument lists and(incorrect) calls to functions which modify the search path orinappropriately generate messages. The R code is checked forpossible problems usingcodetools. In addition, it is checkedwhether S3 methods have all the arguments of the corresponding generic, andwhether the final argument of replacement functions is called‘value’. All foreign function calls (.C,.Fortran,.Call and.External calls) are tested to see if they haveaPACKAGE argument, and if not, whether the appropriate DLL mightbe deduced from the namespace of the package. Any other calls arereported. (The check is generous, and users may want to supplement thisby examining the output oftools::checkFF("mypkg", verbose=TRUE),especially if the intention were to always use aPACKAGEargument)
11. TheRd files are checked for correct syntax and metadata,including the presence of the mandatory fields (\name,\alias,\title and\description). TheRd name andtitle are checked for being non-empty, and there is a check for missingcross-references (links).
12. A check is made for missing documentation entries, such as undocumenteduser-level objects in the package.
13. Documentation for functions, data sets, and S4 classes is checked forconsistency with the corresponding code.
14. It is checked whether all function arguments given in\usagesections ofRd files are documented in the corresponding\arguments section.
15. Thedata directory is checked for non-ASCII charactersand for the use of reasonable levels of compression.
16. C, C++ and Fortran source and header files⁵⁷ aretested for portable (LF-only) line endings. If there is aMakefile orMakefile.in orMakevars orMakevars.in file under thesrc directory, it is checkedfor portable line endings and the correct use of ‘$(BLAS_LIBS)’ and‘$(LAPACK_LIBS)’

    Compiled code is checked for symbols corresponding to functions whichmight terminate R or write tostdout/stderr instead ofthe console. Note that the latter might give false positives in thatthe symbols might be pulled in with external libraries and could neverbe called. Windows⁵⁸ usersshould note that the Fortran and C++ runtime libraries are examples ofsuch external libraries.

17. Some checks are made of the contents of theinst/doc directory.These always include checking for files that look like leftovers, and ifsuitable tools (such asqpdf) are available, checking that thePDF documentation is of minimal size.
18. The examples provided by the package’s documentation are run.(seeWriting R documentation files, for information on using\examples to create executable example code.) If there is a filetests/Examples/pkg-Ex.Rout.save, the output of running theexamples is compared to that file.

    Of course, released packages should be able to run at least their ownexamples. Each example is run in a ‘clean’ environment (so earlierexamples cannot be assumed to have been run), and with the variablesT andF redefined to generate an error unless they are setin the example:SeeLogical vectors inAn Introduction to R.

19. If the package sources contain atests directory then the testsspecified in that directory are run. (Typically they will consist of aset of.R source files and target output files.Rout.save.) Please note that the comparison will be done in theend user’s locale, so the target output files should beASCIIif at all possible. (The command line option--test-dir=foo maybe used to specify tests in a non-standard location. For example,unusually slow tests could be placed ininst/slowTests and thenR CMD check --test-dir=inst/slowTests would be used to run them.Other names that have been suggested are, for example,inst/testWithOracle for tests that require Oracle to be installed,inst/randomTests for tests which use random values and mayoccasionally fail by chance, etc.)
20. The R code in package vignettes (seeWriting package vignettes) isexecuted, and the vignettes re-made from their sources as a check ofcompleteness of the sources (unless there is a ‘BuildVignettes’field in the package’sDESCRIPTION file with a false value). Ifthere is a target output file.Rout.save in the vignette sourcedirectory, the output from running the code in that vignette is comparedwith the target output file and any differences are reported (but notrecorded in the log file). (If the vignette sources are in thedeprecated locationinst/doc, do mark such target output files tonot be installed in.Rinstignore.)

    If there is an error⁵⁹ in executing the R code in vignettefoo.ext, a logfilefoo.ext.log is created in the check directory. Thevignettes are re-made in a copy of the package sources in thevign_test subdirectory of the check directory, so for furtherinformation on errors look in directorypkgname/vign_test/vignettes. (It is only retained if thereare errors or if environment variable_R_CHECK_CLEAN_VIGN_TEST_ isset to a false value.)

21. The PDF version of the package’s manual is created (to check that theRd files can be converted successfully). This needs LaTeX andsuitable fonts and LaTeX packages to be installed.SeeMaking the manuals inR Installation and Administrationfor further details.
22. Optionally (including byR CMD check --as-cran) the HTMLversion of the manual is created and checked for compliance with theHTML5 standard. This requires a recent version⁶⁰ of ‘HTMLTidy’, either on the path or at a location specified by environmentvariableR_TIDYCMD. Up-to-date versions can be installed fromhttp://binaries.html-tidy.org/.

All these tests are run with collation set to theC locale, andfor the examples and tests with environment variableLANGUAGE=en:this is to minimize differences between platforms.

UseR CMD check --help to obtain more information about the usageof the R package checker. A subset of the checking steps can beselected by adding command-line options. It also allows customization bysetting environment variables_R_CHECK_*_ as described inTools inR Internals:a set of these customizations similar to those used byCRANcan be selected by the option--as-cran (which works best ifInternet access is available). Some Windows users mayneed to set environment variableR_WIN_NO_JUNCTIONS to a non-emptyvalue. The test of cyclic declarations⁶¹inDESCRIPTION files needsrepositories (includingCRAN) set: do this in~/.Rprofile, by e.g.

options(repos = c(CRAN="https://cran.r-project.org"))

One check customization which can be revealing is

_R_CHECK_CODETOOLS_PROFILE_="suppressLocalUnused=FALSE"

which reports unused local assignments. Not only does this point outcomputations which are unnecessary because their results are unused, italso can uncover errors. (Two such are to intend to update an object byassigning a value but mistype its name or assign in the wrong scope,for example using<- where<<- was intended.) This cangive false positives, most commonly because of non-standard evaluationfor formulae and because the intention is to return objects in theenvironment of a function for later use.

Complete checking of a package which contains a fileREADME.mdneeds a reasonably current version ofpandoc installed: seehttps://pandoc.org/installing.html.

You do need to ensure that the package is checked in a suitable localeif it contains non-ASCII characters. Such packages are likelyto fail some of the checks in aC locale, andR CMDcheck will warn if it spots the problem. You should be able to checkany package in a UTF-8 locale (if one is available). Beware thatalthough aC locale is rarely used at a console, it may be thedefault if logging in remotely or for batch jobs.

OftenR CMD check will need to consult a CRAN repository tocheck details of uninstalled packages. Normally this defaults to theCRAN main site, but a mirror can be specified by setting environmentvariablesR_CRAN_WEB and (rarely needed)R_CRAN_SRC to theURL of a CRAN mirror.

It is possible to install a package and then check the installedpackage. To do so first install the package and keep a log of theinstallation:

R CMD INSTALL -llibdirpkg >pkg.log 2>&1

and then use

Rdev CMD check -llibdir --install=check:pkg.logpkg

(Specifying the library is required: it ensures that the just-installedpackage is the one checked. If you know for sure only one copy isinstalled you can use--install=skip: this is used for Rinstallation’smake check-recommended.)

1.3.2 Building package tarballs ¶

Packages may be distributed in source form as “tarballs”(.tar.gz files) or in binary form. The source form can beinstalled on all platforms with suitable tools and is the usual form forUnix-like systems; the binary form is platform-specific, and is the morecommon distribution form for the macOS and ‘x86_64’ Windows platforms.

UsingR CMD build, the R package builder, one can buildR package tarballs from their sources (for example, for subsequentrelease). It is recommended that packages are built for release by thecurrent release version of R or ‘r-patched’, to avoidinadvertently picking up new features of a development version of R.

Prior to actually building the package in the standard gzipped tar fileformat, a few diagnostic checks and cleanups are performed. Inparticular, it is tested whether object indices exist and can be assumedto be up-to-date, and C, C++ and Fortran source files and relevantmakefiles in asrc directory are tested and converted toLFline-endings if necessary.

Run-time checks whether the package works correctly should be performedusingR CMD check prior to invoking the final build procedure.

To exclude files from being put into the package, one can specify a listof exclude patterns in file.Rbuildignore in the top-level sourcedirectory. These patterns should be Perl-like regular expressions (seethe help forregexp in R for the precise details), one perline, to be matched case-insensitively against the file and directorynames relative to the top-level package source directory. In addition,directories from source control systems⁶² or fromeclipse⁶³, directories withnamescheck,chm, or ending.Rcheck orOldorold and filesGNUMakefile⁶⁴,Read-and-delete-me or with base namesstarting with ‘.#’, or starting and ending with ‘#’, or endingin ‘~’, ‘.bak’ or ‘.swp’, are excluded bydefault⁶⁵. In addition,same-package tarballs (from previous builds) and their binary forms willbe excluded from the top-level directory, as well asthose files in theR,demo andmandirectories which are flagged byR CMD check as having invalidnames.

UseR CMD build --help to obtain more information about the usageof the R package builder.

UnlessR CMD build is invoked with the--no-build-vignettes option (or the package’sDESCRIPTION contains ‘BuildVignettes: no’ or similar), itwill attempt to (re)build the vignettes (seeWriting package vignettes) in the package. To do so it installs the current packageinto a temporary library tree, but any dependent packages need to beinstalled in an available library tree (see the Note: at the top of thissection).

Similarly, if the.Rd documentation files contain any\Sexpr macros (seeDynamic pages), the package will betemporarily installed to execute them. Post-execution binary copies ofthose pages containing build-time macros will be saved inbuild/partial.rdb. If there are any install-time or render-timemacros, a.pdf version of the package manual will be built andinstalled in thebuild subdirectory. (This allowsCRAN or other repositories to display the manual even if theyare unable to install the package.) This can be suppressed by theoption--no-manual or if package’sDESCRIPTION contains‘BuildManual: no’ or similar.

One of the checks thatR CMD build runs is for empty sourcedirectories. These are in most (but not all) cases unintentional, ifthey are intentional use the option--keep-empty-dirs (or setthe environment variable_R_BUILD_KEEP_EMPTY_DIRS_ to ‘TRUE’,or have a ‘BuildKeepEmpty’ field with a true value in theDESCRIPTION file).

The--resave-data option allows saved images (.rda and.RData files) in thedata directory to be optimized forsize. It will also compress tabular files and convert.R filesto saved images. It can take valuesno,gzip (the defaultif this option is not supplied, which can be changed by setting theenvironment variable_R_BUILD_RESAVE_DATA_) andbest(equivalent to giving it without a value), which chooses the mosteffective compression. Usingbest adds a dependence onR(>= 2.10) to theDESCRIPTION file ifbzip2 orxz compression is selected for any of the files. If this isthought undesirable,--resave-data=gzip (which is the defaultif that option is not supplied) will do what compression it can withgzip. A package can control how its data is resaved bysupplying a ‘BuildResaveData’ field (with one of the values givenearlier in this paragraph) in itsDESCRIPTION file.

The--compact-vignettes option will runtools::compactPDF over the PDF files ininst/doc (and itssubdirectories) to losslessly compress them. This is not enabled bydefault (it can be selected by environment variable_R_BUILD_COMPACT_VIGNETTES_) and needsqpdf(https://qpdf.sourceforge.io/) to be available.

It can be useful to runR CMD check --check-subdirs=yes on thebuilt tarball as a final check on the contents.

Where a non-POSIX file system is in use which does not utilize executepermissions, some care is needed with permissions. This applies onWindows and to e.g. FAT-formatted drives and SMB-mounted file systemson other OSes. The ‘mode’ of the file recorded in the tarball will bewhateverfile.info() returns. On Windows this will record onlydirectories as having execute permission and on other OSes it is likelythat all files have reported ‘mode’0777. A particular issue ispackages being built on Windows which are intended to contain executablescripts such asconfigure andcleanup:R CMDbuild ensures those two are recorded with execute permission.

Directorybuild of the package sources is reserved for use byR CMD build: it contains information which may not easily becreated when the package is installed, including index information onthe vignettes and, rarely, information on the help pages and perhaps acopy of the PDF reference manual (see above).

1.3.3 Building binary packages ¶

Binary packages are compressed copies of installed versions ofpackages. They contain compiled shared libraries rather than C, C++ orFortran source code, and the R functions are included in their installedform. The format and filename are platform-specific; for example, abinary package for Windows is usually supplied as a.zip file,and for the macOS platform the default binary package file extension is.tgz.

The recommended method of building binary packages is to use

R CMD INSTALL --build pkg

wherepkg is either the name of a source tarball (in the usual.tar.gz format) or the location of the directory of the packagesource to be built. This operates by first installing the package andthen packing the installed binaries into the appropriate binary packagefile for the particular platform.

By default,R CMD INSTALL --build will attempt to install thepackage into the default library tree for the local installation ofR. This has two implications:

• If the installation is successful, it will overwrite any existing installationof the same package.
• The default library tree must have write permission; if not, the package willnot install and the binary will not be created.

To prevent changes to the present working installation or to provide aninstall location with write access, create a suitably located directorywith write access and use the-l option to build the packagein the chosen location. The usage is then

R CMD INSTALL -l location --build pkg

wherelocation is the chosen directory with write access. The packagewill be installed as a subdirectory oflocation, and the package binarywill be created in the current directory.

Other options forR CMD INSTALL can be found usingRCMD INSTALL --help, and platform-specific details for special cases arediscussed in the platform-specific FAQs.

Finally, at least one web-based service is available for building binarypackages from (checked) source code: WinBuilder (seehttps://win-builder.R-project.org/) is able to build‘x86_64’ Windows binaries. Note that this is intended fordevelopers on other platforms who do not have access to Windows but wishto provide binaries for the Windows platform.

Next:Package namespaces, Previous:Checking and building packages, Up:Creating R packages   [Contents][Index]

## BAD EXAMPLEall: pdf cleanpdf: ABC-intro.pdf ABC-details.pdf%.pdf:  %.tex        texi2dvi --pdf $*clean:        rm *.tex ABC-details-*.pdf

%\VignetteIndexEntry{Using Animal}

1.4.1 Encodings and vignettes ¶

Vignettes will in general include descriptive text, R input, Routput and figures, LaTeX include files and bibliographic references.As any of these may contain non-ASCII characters, the handlingof encodings can become very complicated.

The vignette source file should be written inASCII or containa declaration of the encoding (see below). This applies even tocomments within the source file, since vignette engines process commentsto look for options and metadata lines. When an engine’s weave andtangle functions are called on the vignette source, it will be convertedto the encoding of the current R session.

Stangle() will produce an R code file in the current locale’sencoding: for a non-ASCII vignette what that is is recorded in acomment at the top of the file.

Sweave() will produce a.tex file in the currentencoding, or in UTF-8 if that is declared. Non-ASCII encodingsneed to be declared to LaTeX via a line like

\usepackage[utf8]{inputenc}

(It is also possible to use the more recent ‘inputenx’ LaTeXpackage.) For files where this line is not needed (e.g. chaptersincluded within the body of a larger document, or non-Sweavevignettes), the encoding may be declared using a comment like

%\VignetteEncoding{UTF-8}

If the encoding is UTF-8, this can also be declared usingthe declaration

%\SweaveUTF8

If no declaration is given in the vignette, it will be assumed to bein the encoding declared for the package. If there is no encodingdeclared in either place, then it is an error to use non-ASCIIcharacters in the vignette.

In any case, be aware that LaTeX may require the ‘usepackage’declaration.

Sweave() will also parse and evaluate the R code in eachchunk. The R output will also be in the current locale (orUTF-8if so declared), and shouldbe covered by the ‘inputenc’ declaration. One thing people oftenforget is that the R output may not beASCII even forASCII R sources, for many possible reasons. One common oneis the use of ‘fancy’ quotes: see the R help onsQuote: notecarefully that it is not portable to declare UTF-8 or CP1252 to coversuch quotes, as their encoding will depend on the locale used to runSweave(): this can be circumvented by settingoptions(useFancyQuotes="UTF-8") in the vignette.

The final issue is the encoding of figures – this applies only to PDFfigures and not PNG etc. The PDF figures will contain declarations fortheir encoding, but the Sweave optionpdf.encoding may need to beset appropriately: see the help for thepdf() graphics device.

As a real example of the complexities, consider thefortunespackage version ‘1.4-0’. That package did not have a declaredencoding, and its vignette was inASCII. However, the data itdisplays are read from a UTF-8 CSV file and will be assumed to be in thecurrent encoding, sofortunes.tex will be in UTF-8 in any locale.Hadread.table been told the data were UTF-8,fortunes.texwould have been in the locale’s encoding.

1.4.2 Non-Sweave vignettes ¶

Vignettes in formats other than Sweave are supportedvia“vignette engines”. For exampleknitr version 1.1 or latercan create.tex files from a variation on Sweave format, and.html files from a variation on “markdown” format. Theseengines replace theSweave() function with other functions toconvert vignette source files into LaTeX files for processing into.pdf, or directly into.pdf or.html files. TheStangle() function is replaced with a function that extracts theR source from a vignette.

R recognizes non-Sweave vignettes using filename extensions specifiedby the engine. For example, theknitr package supportsthe extension.Rmd (standing for“R markdown”). The user indicates the vignette enginewithin the vignette source using a\VignetteEngine line, for example

%\VignetteEngine{knitr::knitr}

This specifies the name of a package and an engine to use in place ofSweave in processing the vignette. AsSweave is the only enginesupplied with the R distribution, the package providing any otherengine must be specified in the ‘VignetteBuilder’ field of thepackageDESCRIPTION file, and also specified in the‘Suggests’, ‘Imports’ or ‘Depends’ field (since itsnamespace must be available to build or check your package). If morethan one package is specified as a builder, they will be searched in theorder given there. Theutils package is always implicitlyappended to the list of builder packages, but may be included earlierto change the search order.

Note that a package with non-Sweave vignettes should always have a‘VignetteBuilder’ field in theDESCRIPTION file, since thisis howR CMD check recognizes that there are vignettes to bechecked: packages listed there are required when the package is checked.

The vignette engine can produce.tex,.pdf, or.htmlfiles as output. If it produces.tex files, R willcalltexi2pdf to convert them to.pdf for displayto the user (unless there is aMakefile in thevignettesdirectory).

Package writers who would like to supply vignette engines needto register those engines in the package.onLoad function.For example, that function could make the call

tools::vignetteEngine("knitr", weave = vweave, tangle = vtangle,                      pattern = "[.]Rmd$", package = "knitr")

(The actual registration inknitr is more complicated, becauseit supports other input formats.) See the?tools::vignetteEnginehelp topic for details on engine registration.

Next:Writing portable packages, Previous:Writing package vignettes, Up:Creating R packages   [Contents][Index]

1.5.1 Specifying imports and exports ¶

Exports are specified using theexport directive in theNAMESPACE file. A directive of the form

export(f, g)

specifies that the variablesf andg are to be exported.(Note that variable names may be quoted, and reserved words andnon-standard names such as[<-.fractions must be.)

For packages with many variables to export it may be more convenient tospecify the names to export with a regular expression usingexportPattern. The directive

exportPattern("^[^.]")

exports all variables that do not start with a period. However, suchbroad patterns are not recommended for production code: it is better tolist all exports or use narrowly-defined groups. (This pattern appliesto S4 classes.) Beware of patterns which include names starting with aperiod: some of these are internal-only variables and should never beexported, e.g. ‘.__S3MethodsTable__.’ (and loading excludes knowncases).

Packages implicitly import the base namespace.Variables exported from other packages with namespaces need to beimported explicitly using the directivesimport andimportFrom. Theimport directive imports all exportedvariables from the specified package(s). Thus the directives

import(foo, bar)

specifies that all exported variables in the packagesfoo andbar are to be imported. If only some of the exported variablesfrom a package are needed, then they can be imported usingimportFrom. The directive

importFrom(foo, f, g)

specifies that the exported variablesf andg of thepackagefoo are to be imported. UsingimportFromselectively rather thanimport is good practice and recommendednotably when importing from packages with more than a dozen exports andespecially from those written by others (so what they export can changein future).

To import every symbol from a package but for a few exceptions,pass theexcept argument toimport. The directive

import(foo, except=c(bar, baz))

imports every symbol fromfoo exceptbar andbaz. The value ofexcept should evaluate to somethingcoercible to a character vector, after substituting each symbol forits corresponding string.

It is possible to export variables from a namespace which it hasimported from other namespaces: this has to be done explicitly and notviaexportPattern.

If a package only needs a few objects from another package it can use afully qualified variable reference in the code instead of a formalimport. A fully-qualified reference to the functionf in packagefoo is of the formfoo::f. This is slightly less efficientthan a formal import and also loses the advantage of recording alldependencies in theNAMESPACE file (but they still need to berecorded in theDESCRIPTION file). Evaluatingfoo::f willcause packagefoo to be loaded, but not attached, if it was notloaded already—this can be an advantage in delaying the loading of ararely used package. However, iffoo is listed only in‘Suggests’ or ‘Enhances’ this also delays the check that it isinstalled: it is good practice to use such imports conditionally (e.g.viarequireNamespace("foo", quietly = TRUE)).

Using thefoo::f form will be necessary when a package needs touse a function of the same name from more than one namespace.

Usingfoo:::f instead offoo::f allows access tounexported objects. This is generally not recommended, as the existenceor semantics of unexported objects may be changed by the package authorin routine maintenance.

1.5.2 Registering S3 methods ¶

The standard method for S3-styleUseMethod dispatching might failto locate methods defined in a package that is imported but not attachedto the search path. To ensure that these methods are available thepackages defining the methods should ensure that the generics areimported and register the methods usingS3method directives. Ifa package defines a functionprint.foo intended to be used as aprint method for classfoo, then the directive

S3method(print, foo)

ensures that the method is registered and available forUseMethoddispatch, and the functionprint.foo does not need to be exported.Since the genericprint is defined inbase it does not needto be imported explicitly.

(Note that function and class names may be quoted, and reserved wordsand non-standard names such as[<- andfunction mustbe.)

It is possible to specify a third argument to S3method, the function tobe used as the method, for example

S3method(print, check_so_symbols, .print.via.format)

whenprint.check_so_symbols is not needed.

As from R 3.6.0 one can also useS3method() directives toperformdelayed registration. With

if(getRversion() >= "3.6.0") {    S3method(pkg::gen, cls)}

functiongen.cls will get registered as an S3 method for classcls and genericgen from packagepkg only when thenamespace ofpkg is loaded. This can be employed to deal withsituations where the method is not “immediately” needed, and having topre-load the namespace ofpkg (and all its strong dependencies)in order to perform immediate registration is considered too onerous.

1.5.3 Load hooks ¶

There are a number of hooks called as packages are loaded, attached,detached, and unloaded. Seehelp(".onLoad") for more details.

Since loading and attaching are distinct operations, separate hooks areprovided for each. These hook functions are called.onLoad and.onAttach. They both take arguments⁷¹libname andpkgname; they should be defined in the namespace but notexported.

Packages can use a.onDetach or.Last.lib function(provided the latter is exported from the namespace) whendetachis called on the package. It is called with a single argument, the fullpath to the installed package. There is also a hook.onUnloadwhich is called when the namespace is unloaded (via a call tounloadNamespace, perhaps called bydetach(unload = TRUE))with argument the full path to the installed package’s directory.Functions.onUnload and.onDetach should be defined in thenamespace and not exported, but.Last.lib does need to beexported.

Packages are not likely to need.onAttach (except perhaps for astart-up banner); code to set options and load shared objects should beplaced in a.onLoad function, or use made of theuseDynLibdirective described next.

User-level hooks are also available: see the help on functionsetHook.

These hooks are often used incorrectly. People forget to export.Last.lib. Compiled code should be loaded in.onLoad (orvia auseDynLb directive: see below) and unloaded in.onUnload. Do remember that a package’s namespace can be loadedwithout the namespace being attached (e.g. bypkgname::fun) andthat a package can be detached and re-attached whilst its namespaceremains loaded.

It is good practice for these functions to be quiet. Any messagesshould usepackageStartupMessage so users (include check scripts)can suppress them if desired.

1.5.4useDynLib ¶

ANAMESPACE file can contain one or moreuseDynLibdirectives which allows shared objects that need to beloaded.⁷² The directive

useDynLib(foo)

registers the shared objectfoo⁷³ for loading withlibrary.dynam.Loading of registered object(s) occurs after the package code has beenloaded and before running the load hook function. Packages that wouldonly need a load hook function to load a shared object can use theuseDynLib directive instead.

TheuseDynLib directive also accepts the names of the nativeroutines that are to be used in Rvia the.C,.Call,.Fortran and.External interface functions. These are given asadditional arguments to the directive, for example,

useDynLib(foo, myRoutine, myOtherRoutine)

By specifying these names in theuseDynLib directive, the nativesymbols are resolved when the package is loaded and R variablesidentifying these symbols are added to the package’s namespace withthese names. These can be used in the.C,.Call,.Fortran and.External calls in place of the name of theroutine and thePACKAGE argument. For instance, we can call theroutinemyRoutine from R with the code

 .Call(myRoutine, x, y)

rather than

 .Call("myRoutine", x, y, PACKAGE = "foo")

There are at least two benefits to this approach. Firstly, the symbollookup is done just once for each symbol rather than each time theroutine is invoked. Secondly, this removes any ambiguity in resolvingsymbols that might be present in more than one DLL. However, thisapproach is nowadays deprecated in favour of supplying registrationinformation (see below).

In some circumstances, there will already be an R variable in thepackage with the same name as a native symbol. For example, we may havean R function in the package namedmyRoutine. In this case,it is necessary to map the native symbol to a different R variablename. This can be done in theuseDynLib directive by using namedarguments. For instance, to map the native symbol namemyRoutineto the R variablemyRoutine_sym, we would use

useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)

We could then call that routine from R using the command

 .Call(myRoutine_sym, x, y)

Symbols without explicit names are assigned to the R variable withthat name.

In some cases, it may be preferable not to create R variables in thepackage’s namespace that identify the native routines. It may be toocostly to compute these for many routines when the package is loadedif 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 theDLL as an R variable, saydll, we can call the routinemyRoutine using the expression

 .Call(dll$myRoutine, x, y)

The$ operator resolves the routine with the given name in theDLL using a call togetNativeSymbol. This is the samecomputation as above where we resolve the symbol when the package isloaded. The only difference is that this is done each time in the caseofdll$myRoutine.

In order to use this dynamic approach (e.g.,dll$myRoutine), oneneeds the reference to the DLL as an R variable in the package. TheDLL can be assigned to a variable by using thevariable =dllName format used above for mapping symbols to R variables. Forexample, if we wanted to assign the DLL reference for the DLLfoo in the example above to the variablemyDLL, we woulduse the following directive in theNAMESPACE file:

myDLL = useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)

Then, the R variablemyDLL is in the package’s namespace andavailable for calls such asmyDLL$dynRoutine to access routinesthat are not explicitly resolved at load time.

If the package has registration information (seeRegistering native routines), then we can use that directly rather than specifying thelist of symbols again in theuseDynLib directive in theNAMESPACE file. Each routine in the registration information isspecified by giving a name by which the routine is to be specified alongwith the address of the routine and any information about the number andtype of the parameters. Using the.registration argument ofuseDynLib, we can instruct the namespace mechanism to createR variables for these symbols. For example, suppose we have thefollowing registration information for a DLL namedmyDLL:

static R_NativePrimitiveArgType foo_t[] = {    REALSXP, INTSXP, STRSXP, LGLSXP};static const R_CMethodDef cMethods[] = {   {"foo", (DL_FUNC) &foo, 4, foo_t},   {"bar_sym", (DL_FUNC) &bar, 0},   {NULL, NULL, 0, NULL}};static const R_CallMethodDef callMethods[] = {   {"R_call_sym", (DL_FUNC) &R_call, 4},   {"R_version_sym", (DL_FUNC) &R_version, 0},   {NULL, NULL, 0}};

Then, the directive in theNAMESPACE file

useDynLib(myDLL, .registration = TRUE)

causes the DLL to be loaded and also for the R variablesfoo,bar_sym,R_call_sym andR_version_sym to bedefined in the package’s namespace.

Note that the names for the R variables are taken from the entry inthe registration information and do not need to be the same as the nameof the native routine. This allows the creator of the registrationinformation to map the native symbols to non-conflicting variable namesin R, e.g.R_version toR_version_sym for use in anR function such as

R_version <- function(){  .Call(R_version_sym)}

Using argument.fixes allows an automatic prefix to be added tothe registered symbols, which can be useful when working with anexisting package. For example, packageKernSmooth has

useDynLib(KernSmooth, .registration = TRUE, .fixes = "F_")

which makes the R variables corresponding to the Fortran symbolsF_bkde and so on, and so avoid clashes with R code in thenamespace.

NB: Using these arguments for a package which does not registernative symbols merely slows down the package loading (although manyCRAN packages have done so). Once symbols are registered,check that the corresponding R variables are not accidentallyexported by a pattern in theNAMESPACE file.

1.5.5 An example ¶

As an example consider two packages namedfoo andbar. TheR code for packagefoo in filefoo.R is

x <- 1f <- function(y) c(x,y)foo <- function(x) .Call("foo", x, PACKAGE="foo")print.foo <- function(x, ...) cat("<a foo>\n")

Some C code defines a C function compiled into DLLfoo (with anappropriate extension). TheNAMESPACE file for this package is

useDynLib(foo)export(f, foo)S3method(print, foo)

The second packagebar has code filebar.R

c <- function(...) sum(...)g <- function(y) f(c(y, 7))h <- function(y) y+9

andNAMESPACE file

import(foo)export(g, h)

Callinglibrary(bar) loadsbar and attaches its exports tothe search path. Packagefoo is also loaded but not attached tothe search path. A call tog produces

> g(6)[1]  1 13

This is consistent with the definitions ofc in the two settings:inbar the functionc is defined to be equivalent tosum, but infoo the variablec refers to thestandard functionc inbase.

1.5.6 Namespaces with S4 classes and methods ¶

Some additional steps are needed for packages which make use of formal(S4-style) classes and methods (unless these are purely usedinternally). The package should haveDepends: methods⁷⁴ in itsDESCRIPTION andimport(methods) orimportFrom(methods, ...) plus any classes and methods which areto be exported need to be declared in theNAMESPACE file. Forexample, thestats4 package has

export(mle) # exporting methods implicitly exports the genericimportFrom("stats", approx, optim, pchisq, predict, qchisq, qnorm, spline)## For these, we define methods or (AIC, BIC, nobs) an implicit generic:importFrom("stats", AIC, BIC, coef, confint, logLik, nobs, profile,           update, vcov)exportClasses(mle, profile.mle, summary.mle)## All methods for imported generics:exportMethods(coef, confint, logLik, plot, profile, summary,              show, update, vcov)## implicit generics which do not have any methods hereexport(AIC, BIC, nobs)

All S4 classes to be used outside the package need to be listed in anexportClasses directive. Alternatively, they can be specifiedusingexportClassPattern⁷⁵ in the same style asforexportPattern. To export methods for generics from otherpackages anexportMethods directive can be used.

Note that exporting methods on a generic in the namespace will alsoexport the generic, and exporting a generic in the namespace will alsoexport its methods. If the generic function is not local to thispackage, either because it was imported as a generic function or becausethe non-generic version has been made generic solely to add S4 methodsto it (as for functions such ascoef in the example above), itcan be declaredvia either or both ofexport orexportMethods, but the latter is clearer (and is used in thestats4 example above). In particular, for primitive functionsthere is no generic function, soexport would export theprimitive, which makes no sense. On the other hand, if the generic islocal to this package, it is more natural to export the function itselfusingexport(), and thismust be done if an implicitgeneric is created without setting any methods for it (as is the caseforAIC instats4).

A non-local generic function is only exported to ensure that calls tothe function will dispatch the methods from this package (and that isnot done or required when the methods are for primitive functions). Forthis reason, you do not need to document such implicitly created genericfunctions, andundoc in packagetools will not report them.

If a package uses S4 classes and methods exported from another package,but does not import the entire namespace of the otherpackage⁷⁶, it needsto import the classes and methods explicitly, with directives

importClassesFrom(package, ...)importMethodsFrom(package, ...)

listing the classes and functions with methods respectively. Suppose wehad two small packagesA andB withB usingA.Then they could haveNAMESPACE files

export(f1, ng1)exportMethods("[")exportClasses(c1)

and

importFrom(A, ng1)importClassesFrom(A, c1)importMethodsFrom(A, f1)export(f4, f5)exportMethods(f6, "[")exportClasses(c1, c2)

respectively.

Note thatimportMethodsFrom will also import any generics definedin the namespace on those methods.

It is important if you export S4 methods that the corresponding genericsare available. You may for example need to importcoef fromstats to make visible a function to be converted into itsimplicit generic. But it is better practice to make use of the genericsexported bystats4 as this enables multiple packages tounambiguously set methods on those generics.

Next:Diagnostic messages, Previous:Package namespaces, Up:Creating R packages   [Contents][Index]

1.6.1 PDF size ¶

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 inquality. Not only do large files take up space: they can stress the PDFviewer and take many minutes to print (if they can be printed at all).

qpdf (https://qpdf.sourceforge.io/) can compresslosslessly. It is fairly readily available (e.g. it is included inrtools, has packages in Debian/Ubuntu/Fedora, and isinstalled as part of theCRAN macOS distribution of R).R CMD build has an option to runqpdf over PDF filesunderinst/doc and replace them if at least 10Kb and 10% issaved. The full path to theqpdf command can be supplied asenvironment variableR_QPDF (and is on theCRAN binaryof R for macOS). It seems MiKTeX does not use PDF objectcompression and soqpdf can reduce considerably the sizes offiles it outputs: MiKTeX’s defaults can be overridden by code in thepreamble of an Sweave or LaTeX file — see how this is done for theR reference manual athttps://svn.r-project.org/R/trunk/doc/manual/refman.top.

Other tools can reduce the size of PDFs containing bitmap images atexcessively high resolution. These are often best re-generated (forexampleSweave defaults to 300 ppi, and 100–150 is moreappropriate for a package manual). These tools include Adobe Acrobat(not Reader), Apple’s Preview⁹⁷ and Ghostscript (whichconverts PDF to PDF by

ps2pdfoptions -dAutoRotatePages=/None -dPrinted=falsein.pdfout.pdf

and suitable options might be

-dPDFSETTINGS=/ebook-dPDFSETTINGS=/screen

Seehttps://ghostscript.readthedocs.io/en/latest/VectorDevices.html formore such and consider all the options for image downsampling). Therehave been examples inCRAN packages for which current versionsof Ghostscript produced much bigger reductions than earlier ones (e.g.at the upgrades from9.50 to9.52, from9.55 to9.56 and then to10.00.0).

We come across occasionally large PDF files containing excessivelycomplicated figures using PDF vector graphics: such figures are oftenbest redesigned or failing that, output as PNG files.

Option--compact-vignettes toR CMD build defaults tovalue ‘qpdf’: use ‘both’ to try harder to reduce the size,provided you have Ghostscript available (see the help fortools::compactPDF).

1.6.2 Check timing ¶

There are several ways to find out where time is being spent in thecheck process. Start by setting the environment variable_R_CHECK_TIMINGS_ to ‘0’. This will report the total CPUtimes (not Windows) and elapsed times for installation and several checks,including for running examples, tests and vignettes, under each sub-architecture ifappropriate. For tests and vignettes, it reports the time for each aswell as the total.

Setting_R_CHECK_TIMINGS_ to a positive value sets a threshold (inseconds elapsed time) for reporting timings.

If you need to look in more detail at the timings for examples, useoption--timings toR CMD check (this is set by--as-cran). This adds a summary to the check output for allthe examples with CPU or elapsed time of more than 5 seconds. Itproduces a filemypkg.Rcheck/mypkg-Ex.timingscontaining timings for each help file: it is a tab-delimited file whichcan be read into R for further analysis.

Timings for the tests and vignette runs are given at the bottom of thecorresponding log file: note that log files for successful vignette runsare only retained if environment variable_R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_ is set to a true value.

1.6.3 Encoding issues ¶

The issues in this subsection have been much alleviated by the change inR 4.2.0 to running the Windows port of R in a UTF-8 locale whereavailable. However, Windows users might be running an earlier versionof R on an earlier version of Windows which does not support UTF-8locales.

Care is needed if your package contains non-ASCII text, and inparticular if it is intended to be used in more than one locale. It ispossible to mark the encoding used in theDESCRIPTION file and in.Rd files, as discussed elsewhere in this manual.

First, consider carefully if you really need non-ASCII text.Some users of R will only be able to view correctly text in theirnative language group (e.g. Western European, Eastern European,Simplified Chinese) andASCII.⁹⁸. Other characters may not be rendered at all,rendered incorrectly, or cause your R code to give an error. For.Rd documentation, marking the encoding and includingASCII transliterations is likely to do a reasonable job. Theset of characters which is commonly supported is wider than it used tobe around 2000, but non-Latin alphabets (Greek, Russian, Georgian,…) are still often problematic and those with double-widthcharacters (Chinese, Japanese, Korean, emoji) often need specialistfonts to render correctly.

SeveralCRAN packages have messages in their R code in French (and afew in German). A better way to tackle this is to use theinternationalization facilities discussed elsewhere in this manual.

FunctionshowNonASCIIfile in packagetools can help infinding non-ASCII bytes in files.

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‘\uxxxx’ escapes (or, rarely needed except for emojis,‘\Uxxxxxxxx’ escapes). If there are any characters not in thecurrent encoding the parser will encode the character string as UTF-8and mark it as such. This applies also to character strings indatasets: they can be prepared using ‘\uxxxx’ escapes or encoded inUTF-8 in a UTF-8 locale, or even converted to UTF-8viaiconv(). If you do this, make sure you have ‘R (>= 2.10)’(or later) in the ‘Depends’ field of theDESCRIPTION file.

R sessions running in non-UTF-8 locales will if possible re-encodesuch strings for display (and this is done byRGui on olderversions of Windows, for example). Suitable fonts will need to beselected or made available⁹⁹ both for the console/terminal and graphics devicessuch as ‘X11()’ and ‘windows()’. Using ‘postscript’ or‘pdf’ will choose a default 8-bit encoding depending on thelanguage of the UTF-8 locale, and your users would need to be told howto select the ‘encoding’ argument.

Note that the previous two paragraphs only apply to character strings inR code. Non-ASCII characters are particularly prevalent in comments(in the R code of the package, in examples, tests, vignettes and evenin theNAMESPACE file) but should be avoided there. Most commonlypeople use the Windows extensions to Latin-1 (often directional singleand double quotes, ellipsis, bullet and en and em dashes) which are notsupported in strict Latin-1 locales nor in CJK locales on Windows. Asurprisingly common misuse is to use a right quote in ‘don't’instead of the correct apostrophe.

Datasets can include marked UTF-8 or Latin-1 character strings. As Ris nowadays unlikely to be run in a Latin-1 or Windows’ CP1252 locale,for performance reasons these should be converted to UTF-8.

If you want to runR CMD check on a Unix-alike over a packagethat sets a package encoding in itsDESCRIPTION fileand donot use a UTF-8 locale you may need to specify a suitable localevia environment variableR_ENCODING_LOCALES. The defaultis equivalent to the value

"latin1=en_US:latin2=pl_PL:UTF-8=en_US.UTF-8:latin9=fr_FR.iso885915@euro"

(which is appropriate for a system based onglibc: macOS requireslatin9=fr_FR.ISO8859-15) except that if the current locale isUTF-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.

1.6.4 Portable C and C++ code ¶

Writing portable C and C++ code is mainly a matter of observing thestandards (C99, C++14 or where declared C++11/17/20) and testing thatextensions (such as POSIX functions) are supported. Do make maximal useof your compiler diagnostics — this typically means using flags-Wall and-pedantic for both C and C++ and additionally-Werror=implicit-function-declaration and-Wstrict-prototypes for C (on some platforms and compilerversions) these are part of-Wall or-pedantic).

C++ standards: From version 4.0.0 R required and defaultedto C++11; from R 4.1.0 in defaulted to C++14 and from R 4.3.0 toC++17 (where available). For maximal portability a package shouldeither specify a standard (seeUsing C++ code) or be tested underall of C++11, C++14 and C++17.

Later C++ standards, notably C++17 remove features deprecated in earlierversions. Unfortunately some compilers, notablyg++ haveretained these features so if possible test under another compiler (suchas that used on macOS).

Note that the ‘TR1’ C++ extensions are not part of any of thesestandards and the<tr1/name> headers are not supplied by some ofthe compilers used for R, including on macOS. (Use the C++11versions instead.)

A common error is to assume recent versions of compilers or OSes. Inproduction environments ‘long term support’ versions of OSes may be inuse for many years,¹⁰⁰ and their compilers may notbe updated during that time. For example, GCC 4.8 was still in use in2022 and could be (in RHEL 7) until 2028: that supports neither C++14nor C++17.

The POSIX standards only require recently-defined functions to bedeclared if certain macros are defined with large enough values, and onsome compiler/OS combinations¹⁰¹ they are not declared otherwise. So you mayneed to include something like one of

#define _XOPEN_SOURCE 600

or

#ifdef __GLIBC__# define _POSIX_C_SOURCE 200809L#endif

beforeany headers. (strdup,strncasecmp andstrnlen are such functions – there were several older platformswhich did not have the POSIX 2008 functionstrnlen.)

‘Linux’ is not a well-defined operating system: it is a kernel plus acollection of components. Most distributions useglibc toprovide most of the C headers and run-time library, but others, notablyAlpine Linux, use other implementations such asmusl — seehttps://wiki.musl-libc.org/functional-differences-from-glibc.html.

However, some common errors are worth pointing out here. It can behelpful to look up functions athttps://cplusplus.com/reference/ orhttps://en.cppreference.com/w/ and compare what is defined in thevarious standards.

More care is needed for functions such asmallinfo which are notspecified by any of these standards—hopefully theman pageon your system will tell you so. Searching online for such pages forvarious OSes (preferably at least Linux and macOS, and the FreeBSDmanual pages athttps://man.freebsd.org/cgi/man.cgi allow you toselect many OSes) should reveal useful information but aconfigure script is likely to be needed to check availability andfunctionality.

Both the compiler and OS (via system header files, which maydiffer by architecture even for nominally the same OS) affect thecompilability of C/C++ code. Compilers from the GCC, LLVM(clang andflang) Intel and Oracle Developer Studiosuites have been used with R, and both LLVMclang andOracle have more than one implementation of C++ headers and library.The range of possibilities makes comprehensive empirical checkingimpossible, and regrettably compilers are patchy at best on warningabout non-standard code.

• Mathematical functions such assqrt are defined in C++11 forfloating-point arguments:float,double,longdouble and possibly more. The standard specifies what happens with anargument of integer type but this is not always implemented, resultingin a report of ‘overloading ambiguity’: this was commonly seen onSolaris, but forpow also seen on macOS and other platformsusingclang++.

  A not-uncommonly-seen problem is to mistakenly callfloor(x/y) orceil(x/y) forint argumentsx andy. Sincex/y does integer division, the result is of typeint and‘overloading ambiguity’ may be reported. Some people have (pointlessly)calledfloor andceil on arguments of integer type, whichmay have an ‘overloading ambiguity’.

  A surprising common misuse is things likepow(10, -3): thisshould be the constant1e-3. Note that there are constants suchasM_SQRT2 definedviaRmath.h¹⁰² forsqrt(2.0), frequently mis-coded assqrt(2).

• Functionfabs is defined only for floating-point types, except inC++11 and later which have overloads forstd::fabs in<cmath> for integer types. Functionabs is defined inC99’s<stdlib.h> forint and in C++’s<cstdlib> forinteger types, overloaded in<cmath> for floating-point types.C++11 has additional overloads forstd::abs in<cmath> forinteger types. The effect of callingabs with a floating-pointtype is implementation-specific: it may truncate to an integer. Forclarity and to avoid compiler warnings, useabs for integer typesandfabs for double values, and when using C++ include<cmath> and use thestd:: prefix.
• It is an error (and make little sense, although has been seen) to callmacros/functionsisnan,isinf andisfinite forinteger arguments: a few compilers give a compilation error. Functionfinite is obsolete, and some compilers will warn about itsuse¹⁰³.
• The GNU C/C++ compilers support a large number of non-portableextensions. For example,INFINITY (which is afloat valuein C99 and C++11), for which R provides the portable double valueR_PosInf (andR_NegInf for-INFINITY). AndNAN¹⁰⁴ is just one NaNfloat value: for use with R,NA_REAL is often what isintended, butR_NaN is also available.

  Some (but not all) extensions are listed athttps://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html andhttps://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Extensions.html.

  Other GNU extensions which have bitten package writers are the use ofnon-portable characters such as ‘$’ in identifiers and use of C++headers underext.

• Including C-style headers in C++ code is not portable. Including thelegacy header¹⁰⁵math.h in C++ code may conflict withcmath whichmay be included by other headers. In C++11, functions likesqrtandisnan are defined fordouble arguments inmath.h and for a range of types includingdouble incmath. Similar issues have been seen forstdlib.h andcstdlib. Including the C++ header first used to be a sufficientworkaround but for some 2016 compilers only one could be included.
• Be careful to include the headers which define the functions you use.Some compilers/OSes include other system headers in their headers whichare not required by the standards, and so code may compile on suchsystems and not on others. (A prominent example is the C++ header<random> which is indirectly included by<algorithm> byg++. Another issue is the C header<time.h> which isincluded by other headers on Linux and Windows but not macOS.)g++ 11 often needs explicit inclusion of the C++ headers<limits> (fornumeric_limits) or<exception> (forset_terminate and similar), whereas earlier versions includedthese in other headers.g++ 13 requires theexplicit inclusion of<cstdint> for types such asuint32_twhich was previously included implicitly. (For more such, seehttps://gcc.gnu.org/gcc-13/porting_to.html.) There are furtherinstances of this ing++ 15: seehttps://gcc.gnu.org/gcc-13/porting_to.html.

  Note thatmalloc,calloc,realloc andfreeare defined by C99 in the headerstdlib.h and (in thestd:: namespace) by C++ headercstdlib. Some earlierimplementations used a headermalloc.h, but that is not portableand does not exist on macOS.

  This also applies to types such asssize_t. The POSIX standardssay that is declared in headersunistd.h andsys/types.h,and the latter is often included indirectly by other headers on somebut not all systems.

  POSIX mandates the headerunistd.h: most but not all OSes supplyheadersys/unistd.h as a wrapper, so this should not be used.

  Similarly for constants: for exampleSIZE_MAX is defined instdint.h alongsidesize_t.

• Some headers are not portable: we have just mentionedmalloc.hand oftenCRAN submissions attempt to useendian.h.The latter is aglibc extension: some OSes havemachine/endian.h orsys/endian.h but some have neither.Headerexecinfo.h is only available on a few OSes: formerly norin MacOS nor Solaris, and currently not on Linux systems (such as AlpineLinux) usingmusl. Nor is headerfpu_control.h availableon macOS normusl.
• Use#include "my.h" not#include <my.h> for headers inyour package. The second form is intended for system headers and thesearch order for such headers is platform-dependent (and may not includethe current directory). For extra safety, name headers in a way thatcannot be confused with a system header so not, for example,types.h.
• For C++ code, be careful to specify namespaces where needed. Manyfunctions are defined by the standards to be in thestdnamespace, butg++ puts many such also in the C++ mainnamespace. One way to do so is to use declarations such as

  using std::floor;

  but it is usually preferable to use explicit namespace prefixes in the code.

  Examples seen inCRAN packages include

  abs acos atan bind calloc ceil div exp fabs floor fmod free log mallocmemcpy memset pow printf qsort round sin sprintf sqrt strcmp strcpystrerror strlen strncmp strtol tan trunc

  This problem is less common than it used to be, but in 2019LLVMclang did not havebind in the main namespace. Alsoseen has been typesize_t defined only in thestd namespace.

  NB: These functions are only guaranteed to be in thestd namespace if the correct C++ header is included, e.g.<cmath> rather than<math.h>.

  If you define functions in C++ which are inspired by later standards, putthem in a namespace and refer to them using the namespace. We have seenconflicts withstd::make_unique from C++14 andstd::byte,std::data,std::sample andstd::size from C++17.

• In C++ code

  using namespace std;

  is not good practice, and has caused platform-dependent errors ifincluded before headers, especially system headers (which may beincluded by other headers). The best practice is to use explicitstd:: prefixes for all functions declared by the C++ standard tobe in that namespace. It is an error to useusing namespacestd before including any C++ headers, and some recent compilers willwarn if this is done.

• Some C++ compilers refuse to compile constructs such as

        if(ptr > 0) { ....}

  which compares a pointer to the integer0. This could just useif(ptr) (pointer addresses cannot be negative) but if neededpointers can be tested againstnullptr (C++11) orNULL.

• Macros defined by the compiler/OS can cause problems. Identifiersstarting with an underscore followed by an upper-case letter or anotherunderscore are reserved for system macros and should not be used inportable code (including not as guards in C/C++ headers). Other macros,typically upper-case, may be defined by the compiler or system headersand can cause problems.Some of these can be avoided by defining_POSIX_C_SOURCEbefore including any system headers, but it is better to only useall-upper-case names which have a unique prefix such as the packagename.
• typedefs in OS headers can conflict with those in the package:examples have includedulong,index_t,single andthread. (Note that these may conflict with other uses asidentifiers, e.g. defining a C++ function calledsingle.)The POSIX standard reserves (in §2.2.2) all identifiers ending in_t.
• Some compilers do not allow a space between-D and the macro tobe defined. Similarly for-U.
• If you useOpenMP, check carefully that you have followed the advice inthe subsection onOpenMP support. In particular, any use ofOpenMP in C/C++ code will need to use

  #ifdef _OPENMP# include <omp.h>#endif

  Any use ofOpenMP functions, e.g.omp_set_num_threads, alsoneeds to be conditioned. To avoid incessant warnings such as

  warning: ignoring #pragma omp parallel [-Wunknown-pragmas]

  uses of such pragmas should also be conditioned (or commented out ifthey are used in code in a package not enablingOpenMP on any platform).

  Do not hardcode-lgomp: not only is that specific to theGCC family of compilers, using the correct linker flag often sets up therun-time path to the library.

• Package authors commonly assume things are part of C/C++ when they arenot: the most common example is POSIX¹⁰⁶ functionstrdup.The most common C library on Linux,glibc, will hide thedeclarations of such extensions unless a ‘feature-test macro’ is definedbefore (almost) any system header is included. So forstrdup you need

  #define _POSIX_C_SOURCE 200809L...#include <string.h>...strdup call(s)

  where the appropriate value can be found byman strdup onLinux. (Use ofstrncasecmp is similar.)

  However, modes ofgcc with ‘GNU EXTENSIONS’ (which are thedefault, either-std=gnu99 or-std=gnu11) declareenough macros to ensure that missing declarations are rarely seen.

  This applies also to constants such asM_PI andM_LN2,which are part of the X/Open standard: to use these define_XOPEN_SOURCE before including any headers, or include the RheaderRmath.h.

• Usingalloca portably is tricky: it is neither an ISO C/C++ nor aPOSIX function. An adequately portable preamble is

  #ifdef __GNUC__/* Includes GCC, clang and Intel compilers */# undef alloca# define alloca(x) __builtin_alloca((x))#elif defined(__sun) || defined(_AIX)/* this was necessary (and sufficient) for Solaris 10 and AIX 6: */# include <alloca.h>#endif

• Compiler writers feel free to implement features from later standardsthan the one specified, so for example they may implement or warn onC++14/17/20 features when C++11 is specified. Portable code will notuse such features – it can be hard to know what they are but the mostcommon warnings are

  'register' storage class specifier is deprecated and incompatible with C++17ISO C++11 does not allow conversion from string literal to 'char *'

  (where conversion should be toconst char *). Keywordregister was not mentioned in C++98, deprecated in C++11 andremoved in C++17.

  There are quite a lot of other C++98 features deprecated in C++11 andremoved in C++17, and LLVMclang 9 and later warn about them(and as from version 16 they have been removed). Examples includebind1st/bind2nd (usestd::bind orlambdas¹⁰⁷)std::auto_ptr (replaced bystd::unique_ptr),std::mem_fun_ref andstd::ptr_fun.

• Later versions of standards may add reserved words: for examplebool,false andtrue became keywords in C23 and areno longer available as variable names. As noted above, C++17 usesbyte,data,sample andsize.

  So avoid common words and keywords from other programming languages.

• Be careful about including C headers in C++ code. Issues include
  • Use of theregister storage class specifier (see the previous butone item).
  • The C99 keywordrestrict is not part of¹⁰⁸ any C++ standard and is rejected by someC++ compilers.
  • Inclusion by such headers of C-style headers such asmath.h (see above).

  The most portable way to interface to other software with a C API is touse C code (which can normally be mixed with C++ code in a package).

• Include only what is essential inextern "C" {} blocks in C++code. In particular it is not portable to include R headers in suchblocks (although they are themselves C code, they may include C++ systemheaders and the public ones already enclose their declarations in such ablock). And maintainers have include R headers from other headersincluded in such a block.
• reinterpret_cast in C++ is not safe for pointers: for example the typesmay have different alignment requirements. Usememcpy to copythe contents to a fresh variable of the destination type.
• Avoid platform-specific code if at all possible, but if you need to testfor a platform ensure that all platforms are covered. For example,__unix__ is not defined on all Unix-alikes, in particular not onmacOS. A reasonably portable way to condition code for a Unix-alike is

  #if defined (__unix__) || (defined (__APPLE__) && defined (__MACH__))#endif

  but

  #ifdef _WIN32// Windows-specific code# if defined(_M_ARM64) || defined(__aarch64__)// for ARM# else// for Intel# endif#else// Unix-alike code#endif

  would be better. For a Unix-alike it is much better to useconfigure to test for the functionality needed than makeassumptions about OSes (and people all too frequently forget R isused on platforms other than Linux, Windows and macOS — and someforget macOS).

• Headers in subdirectories are often not portable. For C++, thisincludesbits/,tr1/ andtr2/, none of which existon macOS (andext/ exists there but with different content fromg++-based platforms). Headerbits/stdc++.h is both notportable and not recommended for end-user code even on platforms whichinclude it.
• Be careful if usingmalloc orcalloc. First, their returnvalue must always be checked to see if the allocation succeeded – it isalmost always easier to use R’sR_Calloc, which does check.Second, the first argument is of typesize_t¹⁰⁹ and some recent compilerswarn about passingint (signed) arguments (which could getpromoted to ridiculously large values).
• For C code, consider using the flag-Wstrict-prototypes whichis supported bygcc and LLVM and Appleclang.This has found quite a number of errors where functions have beendeclared without arguments and is likely to become the default in futurecompilers. (It already is for Appleclang and for LLVMclang in C23 mode.) Note that usingf() for a functionwithout any parameters was deprecated in C99 and C11, but it becamenon-deprecated in C23. However,f(void) is supported by allstandards and avoids any uncertainty.

  LLVMclang has a separate warning-Wdeprecated-non-prototype which is enabled by-Wstrict-prototypes. This warns on K&R-style usage, which willnot be accepted in C23.

• Several C entry points are warned against in theirman pageson most systems, often in very strong terms such as ’Do not usethese functions’. macOS has started to warn¹¹⁰ if these are usedforsprintf,vsprintf,gets,mktemp,tempmam andtmpnam. It is highly recommended that you usesafer alternatives (on any platform) but the warning can be avoided bydefining ‘_POSIX_C_SOURCE’ to for example ‘200809L’ beforeincluding the (C or C++) header which defines them. (However, this mayhide other extensions.)
• Compilers may interpret comments in source code, so it is necessary toremove any intended for a compiler to interpret. The main example hasbeen comments for Visual Fortran (as the Intel Fortran compiler has beenknown on Windows¹¹¹) like

  !DEC$ ATTRIBUTES DLLEXPORT,C,REFERENCE,ALIAS:'kdenestmlcvb' :: kdenestmlcvb

  which are interpreted by Intel Fortran on all platforms (and areinappropriate for use with R on Windows).gfortran hassimilar forms starting with!GCC$.

• The C++new operator takes argumentstd::size_t size,which is unsigned. Using a signed integer type such asint maylead to compiler warnings such as

  warning: argument 1 value '18446744073709551615' exceeds maximum object  size 9223372036854775807  [-Walloc-size-larger-than=]

  (especially ifLTO is used). So don’t do that!

• Some authors feel the need to print (usingRprintf orsimilar) vector lengths or indices which are of typeR_xlen_t.That is (almost always) a 64-bit type but which integertype it is mapped to is platform-specific. The safest way is to castthe length to double and use a double format. So one could usesomething like

      SEXP Robj; R_xlen_t nelem;    Rf_error("Actual: %0.f; Expected %0.f\n", (double) XLENGTH(Robj), (double) nelem);

  (This could print to full precision, lengths well beyond the address spacelimits of current OSes, let alone practical limits.)

  If you do want to use an integer format, be aware thatR_xlen_tis implemented by theint,long orlong long typeon current platforms and even on 64-bit ones need not be the same typeasint64_t.So the values will need to be cast to the type assumed by the format(and%lld was not supported on Windows until R 4.2.0).

• Variadic macros in C or C++ only portably allow a non-zero number ofarguments, although some compilers have allowed zero, often with awarning. The latter was standardized in C++20 using the__VA_OPT__macro. C23 allows zero arguments in a similar way.

Some additional information for C++ is available athttps://journal.r-project.org/archive/2011-2/RJournal_2011-2_Plummer.pdfby Martyn Plummer.

Several OSes have or currently do provide multiple C++ runtimes —Solaris did and the LLVMclang compiler has a native C++runtime librarylibc++ but is also used with GCC’slibstdc++ (by default on Debian/Ubuntu/Fedora). This makes itunsafe to assume that OS libraries with a C++ interface are compatiblewith the C++ compiler specified by R. Many of these system librariesalso have C interfaces which should be used in preference to their C++interface. Otherwise it is essential that a package checkscompatibility in itsconfigure script, including that C++ codeusing the library can both be linkedand loaded.

• Common symbols
• C++17 issues
• C23 changes

#define extern# include "globals.h"#undef extern

-D_HAS_AUTO_PTR_ETC=0

std::auto_ptrstd::unary_functionstd::binary_functionstd::random_shufflestd::binder1ststd::binder2nd

BOOST_MPL_AUX_STATIC_CAST(AUX_WRAPPER_VALUE_TYPE, (value - 1));

 -Wno-error=enum-constexpr-conversion

CXX="/path/to/clang/clang++ -std=gnu++17 -stdlib=libc++"

1.6.5 Portable Fortran code ¶

For many years almost all known R platforms usedgfortranas their Fortran compiler, but now there are LLVM and ‘classic’flang and the Intel compilersifort¹¹⁶ andifx are nowfree-of-change.

There is still a lot of Fortran code inCRAN packages whichpredates Fortran 77. Modern Fortran compilers are being written totarget a minimum standard of Fortran 2018. and it is desirable thatFortran code in packages complies with that standard. Forgfortran this can be checked by adding-std=f2018 toFFLAGS. The most commonly seen issues are

• The use ofDFLOAT, which was superseded byDBLE in Fortran77. Also, use ofDCMPLX,DCONJG,DIMAG andsimilar.
• Use of whatgfortran calls ‘Fortran 2018 deleted features’,although most were ‘deleted’ in earlier standards: those itemized herewere deleted in Fortran 2008. (In the Fortran standards ‘deleted’ meansfeatures that compilers are not required to implement.) These include
  • ArithmeticIF statements.
  • DO loops which are not terminated with aEND DO orCONTINUE statement. (UnlabelledDO loops terminated byEND DO are preferred for readability.)
  • LabelledDO loops sharing a terminatingCONTINUE statement.
• The use of GNU Fortran extensions. Some are listed athttps://gcc.gnu.org/onlinedocs/gfortran/Extensions-implemented-in-GNU-Fortran.html.Others which have caused problems includeetime,getpid,isnan¹¹⁷ andsizeof.

  One that frequently catches package writers is that it allowsout-of-order declarations: in standard-conformant Fortran variables mustbe declared (explicitly or implicitly) before use in other declarationssuch as dimensions.

Unfortunately this flags extensions such asDOUBLE COMPLEX andCOMPLEX*16. R has tested thatDOUBLE COMPLEX works andso is preferred toCOMPLEX*16. (One can also use something likeCOMPLEX(KIND=KIND(0.0D0)).)

GNU Fortran 10 and later give a compilation error for the previouslywidespread practice of passing a Fortran array element where an array isexpected, or a scalar instead of a length-one array. Seehttps://gcc.gnu.org/gcc-10/porting_to.html. As do the IntelFortran compilers, and they can be stricter.

The use ofIMPLICIT NONE is highly recommended – Intel compilerswith-warn will warn on variables without an explicit type.

Common non-portable constructions include

• The use of Fortran types such asREAL(KIND=8) is very far fromportable. According to the standards this merely enumerates differentsupported types, soDOUBLE PRECISION might beREAL(KIND=3)(and is on an actual compiler). Even if for a particular compiler thevalue indicates the size in bytes, which values are supported isplatform-specific — for examplegfortran supports values of 4and 8 on all current platforms and 10 and 16 on a few (but not forexample on all ‘arm’ CPUs).

  The same applies toINTEGER(KIND=4) andCOMPLEX(KIND=16).

  Many uses of integer and real variable in Fortran code in packages willinterwork with C (for example.Fortran is written in C), and Rhas checked thatINTEGER andDOUBLE PRECISION correspond tothe C typesint anddouble. To make this explicit, fromFortran 2003 one can use the named constantsc_int,c_double andc_double_complex from moduleiso_c_binding.

• The Intel compilers only recognize the extensions.f (fixed-form)and.f90 (free-form) and not.f95.R CMD INSTALLworks around this for packages without asrc/Makefile.
• Use of extensions.F and.F90 to indicate source code tobe preprocessed: the preprocessor used is compiler-specific and may ormay not becpp. Compilers may even preprocess files withextension.f or.f90 (Intel does).
• Fixed form Fortran (with extension.f) should only use 72columns, and free-form at most 132 columns. This includes trailingcomments. Over-long lines may be silently truncated or give a warning.
• Tabs are not part of the Fortran character set: compilers tend to acceptthem but how they are interpreted is compiler-specific.
• Fortran-66-style Hollerith constants.

As well as ‘deleted features’, Fortran standards have ‘obsolescentfeatures’. These are similar to ‘deprecated’ in other languages, butthe Fortran standards committee has said it will only move them to‘deleted’ status when they are no longer much used. These include

• ENTRY statements.
• FORALL statements.
• LabelledDO statements.
• COMMON andEQUIVALENCE statements, andBLOCK DATAunits.
• ComputedGOTO statements, replaced bySELECT CASE.
• Statement functions.
• DATA statements after executable statements.
• Specific (rather than generic) names for intrinsic functions.

gfortran with option-std=f2018 will warn about these:R will report only in the installation log.

1.6.6 Binary distribution ¶

If you want to distribute a binary version of a package on Windows ormacOS, 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 machinethat other users will not have.

For Windows, check what other DLLs your package’s DLL depends on(‘imports’ from in the DLL tools’ parlance). A convenient GUI-basedtool to do so is ‘Dependency Walker’(https://www.dependencywalker.com/) for both 32-bit and 64-bitDLLs – note that this will report as missing links to R’s own DLLssuch asR.dll andRblas.dll. The command-line toolobjdump in the appropriate toolchain will also reveal whatDLLs are imported from. If you use a toolchain other than one providedby the R developers or use your own makefiles, watch out inparticular for dependencies on the toolchain’s runtime DLLs such aslibgfortran,libstdc++ andlibgcc_s.

For macOS, usingR CMD otool -L on the package’s shared object(s)in thelibs directory will show what they depend on: watch forany dependencies in/usr/local/lib or/usr/local/gfortran/lib, notablylibgfortran.?.dylib andlibquadmath.0.dylib.(For ways to fix these,seeBuilding binary packages inR Installation and Administration.)

Many people (including theCRAN package repository) will notaccept source packages containing binary files as the latter are asecurity risk. If you want to distribute a source package which needsexternal software on Windows or macOS, options include

• To arrange for installation of the package to download the additionalsoftware from a URL, as e.g. packageCairo used to.
• To negotiate with Tomas Kalibera to include Windows software inRtools or with Simon Urbanek to include macOS software in his‘recipes’ system.
• (ForCRAN.)To negotiate with Uwe Ligges to host the additional components onWinBuilder, and write aconfigure.win file to install them.

Be aware that license requirements may require you to supply thesources for the additional components (and will if your package has aGPL-like license).

Next:Internationalization, Previous:Writing portable packages, Up:Creating R packages   [Contents][Index]

Next:CITATION files, Previous:Diagnostic messages, Up:Creating R packages   [Contents][Index]

1.8.1 C-level messages ¶

The process of enabling translations is

• In a header file that will be included in all the C (or C++ or ObjectiveC/C++) files containing messages that should be translated, declare

  #include <R.h>  /* to include Rconfig.h */#ifdef ENABLE_NLS#include <libintl.h>#define _(String) dgettext ("pkg", String)/* replacepkg as appropriate */#else#define _(String) (String)#endif

• For each message that should be translated, wrap it in_(...),for example

  error(_("'ord' must be a positive integer"));

  If you want to use different messages for singular and plural forms, youneed to add

  #ifndef ENABLE_NLS#define dngettext(pkg, String, StringP, N) (N == 1 ? String : StringP)#endif

  and mark strings by

  dngettext("pkg",<singular string>,<plural string>, n)

• In the package’ssrc directory run

  xgettext --keyword=_ -opkg.pot *.c

The filesrc/pkg.pot is the template file, andconventionally this is shipped aspo/pkg.pot.

1.8.2 R messages ¶

Mechanisms are also available to support the automatic translation ofRstop,warning andmessage messages. They makeuse of message catalogs in the same way as C-level messages, but usingdomainR-pkg rather thanpkg. Translation ofcharacter strings insidestop,warning andmessagecalls is automatically enabled, as well as other messages enclosed incalls togettext orgettextf. (To suppress this, useargumentdomain=NA.)

Tools to prepare theR-pkg.pot file are provided in packagetools:xgettext2pot will prepare a file from all stringsoccurring insidegettext/gettextf,stop,warning andmessage calls. Some of these are likely to bespurious and so the file is likely to need manual editing.xgettext extracts the actual calls and so is more useful whentidying up error messages.

The R functionngettext provides an interface to the Cfunction of the same name: see example in the previous section. It issafest to usedomain="R-pkg" explicitly in calls tongettext, and necessary for earlier versions of R unless theyare calls directly from a function in the package.

1.8.3 Preparing translations ¶

Once the template files have been created, translations can be made.Conventional translations have file extension.po and are placedin thepo subdirectory of the package with a name that is either‘ll.po’ or ‘R-ll.po’ for translations of the C and Rmessages respectively to language with code ‘ll’.

SeeLocalization of messages inR Installation and Administrationfor details of language codes.

There is an R function,update_pkg_po in packagetools,to automate much of the maintenance of message translations. See itshelp for what it does in detail.

If this is called on a package with no existing translations, it createsthe directorypkgdir/po, creates a template file of Rmessages,pkgdir/po/R-pkg.pot, within it, creates the‘en@quot’ translation and installs that. (The ‘en@quot’pseudo-language interprets quotes in their directional forms in suitable(e.g. UTF-8) locales.)

If the package has C source files in itssrc directorythat are marked for translation, use

touchpkgdir/po/pkg.pot

to create a dummy template file, then callupdate_pkg_po again(this can also be done before it is called for the first time).

When translations to new languages are added in thepkgdir/podirectory, running the same command will check and theninstall the translations.

If the package sources are updated, the same command will update thetemplate files, merge the changes into the translation.po filesand then installed the updated translations. You will often see thatmerging marks translations as ‘fuzzy’ and this is reported in thecoverage statistics. As fuzzy translations arenot used, this isan indication that the translation files need human attention.

The merged translations are run throughtools::checkPofile tocheck that C-style formats are used correctly: if not the mismatches arereported and the broken translations are not installed.

This function needs the GNUgettext-tools installed and on thepath: see its help page.

Next:Package types, Previous:Internationalization, Up:Creating R packages   [Contents][Index]

## R package reference generated from DESCRIPTION metadatacitation(auto = meta)## NLME bookbibentry(bibtype = "Book",         title = "Mixed-Effects Models in S and S-PLUS",         author = c(person(c("José", "C."), "Pinheiro"),                    person(c("Douglas", "M."), "Bates")),         year = "2000", publisher = "Springer", address = "New York",         doi = "10.1007/b98882")

         textVersion =         paste0("Jose Pinheiro, Douglas Bates, Saikat DebRoy, ",                "Deepayan Sarkar and the R Core Team (",                sub("-.*", "", meta$Date),                "). nlme: Linear and Nonlinear Mixed Effects Models. ",                sprintf("R package version %s", meta$Version), ".")

Next:Services, Previous:CITATION files, Up:Creating R packages   [Contents][Index]

1.10.1 Frontend ¶

This is a rather general mechanism, designed for adding new front-endssuch as the formergnomeGUI package (see theArchive area onCRAN). If aconfigure file is found in the top-leveldirectory of the package it is executed, and then if aMakefileis found (often generated byconfigure),make is called.IfR CMD INSTALL --clean is usedmake clean is called. Noother action is taken.

R CMD build can package up this type of extension, butRCMD check will check the type and skip it.

Many packages of this type need write permission for the Rinstallation directory.

Previous:Package types, Up:Creating R packages   [Contents][Index]

Next:Sectioning, Up:Writing R documentation files   [Contents][Index]

2.1.1 Documenting functions ¶

The basic markup commands used for documenting R objects (inparticular, functions) are given in this subsection.

\name{name} ¶

name typically¹¹⁹ is the basename oftheRd file containing the documentation. It is the “name” oftheRd object represented by the file and has to be unique in apackage. To avoid problems with indexing the package manual, it may notcontain ‘!’ ‘|’ nor ‘@’.(LaTeX special characters are allowed, but may not be collatedcorrectly in the index.) There can only be one\name entry in afile, and it must not contain any markup and should only containprintableASCII characters. Entries in the package manualwill be in alphabetic¹²⁰ orderof the\name entries.

\alias{topic} ¶

The\alias sections specify all “topics” the file documents.This information is collected into index data bases for lookup by theon-line (plain text andHTML) help systems. Thetopic cancontain spaces, but (for historical reasons) leading and trailing spaceswill be stripped. Percent and left brace need to be escaped bya backslash.

There may be several\alias entries. Quite often it isconvenient to document several R objects in one file. For example,fileNormal.Rd documents the density, distribution function,quantile function and generation of random variates for the normaldistribution, and hence starts with

\name{Normal}\alias{Normal}\alias{dnorm}\alias{pnorm}\alias{qnorm}\alias{rnorm}

Also, it is often convenient to have several different ways to refer toan R object, and an\alias does not need to be the name of anobject.

Note that the\name is not necessarily a topic documented, and ifso desired it needs to have an explicit\alias entry (as in thisexample).

\title{Title} ¶

Title information for theRd file. This should be capitalizedand not end in a period; try to limit its length to at most 65characters for widest compatibility.

Markup is supported in the text, but use of characters other thanEnglish text and punctuation (e.g., ‘<’) may limit portability.

There must be one (and only one)\title section in a help file.

\description{…} ¶

A short description of what the function(s) do(es) (one paragraph, a fewlines only). (If a description is too long and cannot easily beshortened, the file probably tries to document too much at once.)This is mandatory except for package-overview files.

\usage{fun(arg1,arg2, …)} ¶

One or more lines showing the synopsis of the function(s) and variablesdocumented in the file. These are set in typewriter font. This is anR-like command.

The usage information specified should match the function definitionexactly (such that automatic checking for consistency betweencode and documentation is possible).

To indicate that a function can be used in several different ways,depending on the named arguments specified, use section\details.E.g.,abline.Rd contains

\details{  Typical usages are\preformatted{abline(a, b, ...)......}

Use\method{generic}{class} to indicate the nameof an S3 method for the generic functiongeneric for objectsinheriting from class"class". In the printed versions,this will come out asgeneric (reflecting the understanding thatmethods should not be invoked directly butvia method dispatch), butcodoc() and other QC tools always have access to the full name.

For example,print.ts.Rd contains

\usage{\method{print}{ts}(x, calendar, \dots)}

which will print as

Usage:     ## S3 method for class 'ts':     print(x, calendar, ...)

Usage for replacement functions should be given in the style ofdim(x) <- value rather than explicitly indicating the name of thereplacement function ("dim<-" in the above). Similarly, onecan use\method{generic}{class}(arglist) <-value to indicate the usage of an S3 replacement method for the genericreplacement function"generic<-" for objects inheritingfrom class"class".

Usage for S3 methods for extracting or replacing parts of an object, S3methods for members of the Ops group, and S3 methods for user-defined(binary) infix operators (‘%xxx%’) follows the above rules,using the appropriate function names. E.g.,Extract.factor.Rdcontains

\usage{\method{[}{factor}(x, \dots, drop = FALSE)\method{[[}{factor}(x, \dots)\method{[}{factor}(x, \dots) <- value}

which will print as

Usage:     ## S3 method for class 'factor':     x[..., drop = FALSE]     ## S3 method for class 'factor':     x[[...]]     ## S3 replacement method for class 'factor':     x[...] <- value

\S3method is accepted as an alternative to\method.

\arguments{…} ¶

Description of the function’s arguments, using an entry of the form

\item{arg_i}{Description of arg_i.}

for each element of the argument list. (Note that there isno whitespace between the three parts of the entry.) Arguments can alsobe described jointly by separating their names with commas (and optionalwhitespace) in the\item label. There may beoptional text outside the\item entries, for example to givegeneral information about groups of parameters.

\details{…} ¶

A detailed if possible precise description of the functionalityprovided, extending the basic information in the\descriptionslot.

\value{…} ¶

Description of the function’s return value.

If a list with multiple values is returned, you can use entries of theform

\item{comp_i}{Description of comp_i.}

for each component of the list returned. There may beoptional text outside the\item entries(see for example the joint help forrle andinverse.rle,or the sets of items inl10n_info). Note that\valueis implicitly a\describe environment, so that environment shouldnot be used for listing components, just individual\item{}{}entries.¹²¹

\references{…} ¶

A section with references to the literature. Use\url{} or\href{}{} for web pointers, and\doi{} forDOIs(this needs R >= 3.3, seeUser-defined macros for more info).

\note{...} ¶

Use this for a special note you want to have pointed out. Multiple\note sections are allowed, but might be confusing to the end users.

For example,pie.Rd contains

\note{  Pie charts are a very bad way of displaying information.  The eye is good at judging linear measures and bad at  judging relative areas.  ......}

\author{…} ¶

Information about the author(s) of theRd file. Use\email{} without extra delimiters (such as ‘( )’ or‘< >’) to specify email addresses, or\url{} or\href{}{} for web pointers.

\seealso{…} ¶

Pointers to related R objects, using\code{\link{...}} torefer to them (\code is the correct markup for R object names,and\link produces hyperlinks in output formats which supportthis. SeeMarking text, andCross-references).

\examples{…} ¶

Examples of how to use the function. Code in this section is setin typewriter font without reformatting and is run byexample() unless marked otherwise (see below).

Examples are not only useful for documentation purposes, but alsoprovide test code used for diagnostic checking of R code. Bydefault, text inside\examples{} will be displayed in theoutput of the help page and run byexample() and byR CMDcheck. You can use\dontrun{}for text that should only be shown, but not run, and\dontshow{}for extra commands for testing that should not be shown to users, butwill be run byexample(). (Previously this was called\testonly, and that is still accepted.)

Text inside\dontrun{} is ‘verbatim’, but the other partsof the\examples section are R-like text.

For example,

x <- runif(10)       #Shown and run.\dontrun{plot(x)}    #Only shown.\dontshow{log(x)}    #Only run.

Thus, example code not included in\dontrun must be executable!In addition, it should not use any system-specific features or requirespecial facilities (such as Internet access or write permission tospecific directories). Text included in\dontrun is indicated bycomments in the processed help files: it need not be valid R code butthe escapes must still be used for%,\ and unpairedbraces as in other ‘verbatim’ text.

Example code must be capable of being run byexample, which usessource. This means that it should not accessstdin,e.g. toscan() data from the example file.

Data needed for making the examples executable can be obtained by randomnumber generation (for example,x <- rnorm(100)), or by usingstandard data sets listed bydata() (see?data for moreinfo).

Finally, there is\donttest, used (at the beginning of a separateline) to mark code that should be run byexample() but not byR CMD check (by default: the option--run-donttest canbe used). This should be needed only occasionally but can be used forcode which might fail in circumstances that are hard to test for, forexample in some locales. (Use e.g.capabilities() ornzchar(Sys.which("someprogram")) to test for features needed inthe examples wherever possible, and you can also usetry() ortryCatch(). Useinteractive() to condition examples whichneed someone to interact with.) Note that code included in\donttest must be correct R code, and any packages used shouldbe declared in theDESCRIPTION file. It is good practice toinclude a comment in the\donttest section explaining why it isneeded.

Output from code marked with\dontdiff (requires R >= 4.4.0)or between comment lines

## IGNORE_RDIFF_BEGIN## IGNORE_RDIFF_END

is ignored when comparing check output to reference output (apkg-Ex.Rout.save file).The comment-based markup can also be used for scripts undertests.

\keyword{key} ¶

There can be zero or more\keyword sections per file.Each\keyword section should specify a single keyword, preferablyone of the standard keywords as listed in fileKEYWORDS in theR documentation directory (defaultR_HOME/doc). Usee.g.RShowDoc("KEYWORDS") to inspect the standard keywords fromwithin R. There can be more than one\keyword entry if the Robject being documented falls into more than one category, or none.

Do strongly consider using\concept (seeIndices) instead of\keyword if you are about to use more than very few non-standardkeywords.

The special keyword ‘internal’ marks a page of internal topics(typically, objects that are not part of the package’s API).If the help page for topicfoo has keyword ‘internal’, thenhelp(foo) gives thishelp page, butfoo is excluded from several topic indices,including the alphabetical list of topics in theHTML help system.

help.search() can search by keyword, including user-definedvalues: however the ‘Search Engine & Keywords’HTML page accessedviahelp.start() provides single-click access only to apre-defined list of keywords.

2.1.2 Documenting data sets ¶

The structure ofRd files which document R data sets is slightlydifferent. Sections such as\arguments and\value are notneeded but the format and source of the data should be explained.

As an example, let us look atsrc/library/datasets/man/rivers.Rdwhich documents the standard R data setrivers.

\name{rivers}\docType{data}\alias{rivers}\title{Lengths of Major North American Rivers}\description{ This data set gives the lengths (in miles) of 141 \dQuote{major} rivers in North America, as compiled by the US Geological Survey.}\usage{rivers}\format{A vector containing 141 observations.}\source{World Almanac and Book of Facts, 1975, page 406.}\references{ McNeil, D. R. (1977) \emph{Interactive Data Analysis}. New York: Wiley.}\keyword{datasets}

This uses the following additional markup commands.

\docType{…}

Indicates the “type” of the documentation object. Always ‘data’for data sets, and ‘package’ forpkg-package.Rdoverview files. Documentation for S4 methods and classes uses‘methods’ (frompromptMethods()) and ‘class’ (frompromptClass()).

\format{…} ¶

A description of the format of the data set (as a vector, matrix, dataframe, time series, …). For matrices and data frames this shouldgive a description of each column, preferably as a list or table.SeeLists and tables, for more information.

\source{…} ¶

Details of the original source (a reference orURL,seeSpecifying URLs). In addition, section\references couldgive secondary sources and usages.

Note also that when documenting data setbar,

• The\usage entry is alwaysbar or (for packageswhich do not use lazy-loading of data)data(bar). (Inparticular, only document asingle data object perRd file.)
• The\keyword entry should always be ‘datasets’.

Ifbar is a data frame, documenting it as a data set canbe initiatedviaprompt(bar). Otherwise, thepromptDatafunction may be used.

2.1.3 Documenting S4 classes and methods ¶

There are special ways to use the ‘?’ operator, namely‘class?topic’ and ‘methods?topic’, to accessdocumentation for S4 classes and methods, respectively. This mechanismdepends on conventions for the topic names used in\aliasentries. The topic names for S4 classes and methods respectively are ofthe form

class-classgeneric,signature_list-method

wheresignature_list contains the names of the classes in thesignature of the method (without quotes) separated by ‘,’ (withoutwhitespace), with ‘ANY’ used for arguments without an explicitspecification. E.g., ‘genericFunction-class’ is the topic name fordocumentation for the S4 class"genericFunction", and‘coerce,ANY,NULL-method’ is the topic name for documentation forthe S4 method forcoerce for signaturec("ANY", "NULL").

Skeletons of documentation for S4 classes and methods can be generatedby using the functionspromptClass() andpromptMethods()from packagemethods. If it is necessary or desired to provide anexplicit function declaration (in a\usage section) for an S4method (e.g., if it has “surprising arguments” to be mentionedexplicitly), one can use the special markup

\S4method{generic}{signature_list}(argument_list)

(e.g., ‘\S4method{coerce}{ANY,NULL}(from, to)’).

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 leasthave a suitable\alias entry in one of the package’sRd files.If a package has methods for a function defined originally somewhereelse, and does not change the underlying default method for thefunction, the package is responsible for documenting the methods itcreates, but not for the function itself or the default method.

An S4 replacement method is documented in the same way as an S3 one: seethe description of\method inDocumenting functions.

Seehelp("Documentation", package = "methods") for moreinformation on using and creating on-line documentation for S4 classes andmethods.

2.1.4 Documenting packages ¶

Packages may have an overview help page with an\aliaspkgname-package, e.g. ‘utils-package’ for theutils package, whenpackage?pkgname will open thathelp page. If a topic namedpkgname does not exist inanotherRd file, it is helpful to use this as an additional\alias.

Skeletons of documentation for a package can be generated using thefunctionpromptPackage(). If thefinal = TRUE argumentis used, then theRd file will be generated in final form, containingonly basic information from theDESCRIPTION file. Otherwise (thedefault) comments will be inserted giving suggestions for content.

Apart from the mandatory\name and\title and thepkgname-package alias, the only requirement for the packageoverview page is that it include a\docType{package} statement.All other content is optional. We suggest that it should be a shortoverview, to give a reader unfamiliar with the package enoughinformation to get started. More extensive documentation is betterplaced into a package vignette (seeWriting package vignettes) andreferenced from this page, or into individual man pages for thefunctions, datasets, or classes.

Next:Marking text, Previous:Rd format, Up:Writing R documentation files   [Contents][Index]

\section{Warning}{  You must not call this function unless ...}

Next:Lists and tables, Previous:Sectioning, Up:Writing R documentation files   [Contents][Index]

Next:Cross-references, Previous:Marking text, Up:Writing R documentation files   [Contents][Index]

  \enumerate{    \item A database consists of one or more records, each with one or    more named fields.    \item Regular lines start with a non-whitespace character.    \item Records are separated by one or more empty lines.  }

Next:Mathematics, Previous:Lists and tables, Up:Writing R documentation files   [Contents][Index]

Next:Figures, Previous:Cross-references, Up:Writing R documentation files   [Contents][Index]

Next:Insertions, Previous:Mathematics, Up:Writing R documentation files   [Contents][Index]

\if{html}{\figure{Rlogo.svg}{options: width=100 alt="R logo"}}\if{latex}{\figure{Rlogo.pdf}{options: width=0.5in}}

Next:Indices, Previous:Figures, Up:Writing R documentation files   [Contents][Index]

Next:Platform-specific documentation, Previous:Insertions, Up:Writing R documentation files   [Contents][Index]

\concept{Kendall correlation coefficient}\concept{Pearson correlation coefficient}\concept{Spearman correlation coefficient}

Next:Conditional text, Previous:Indices, Up:Writing R documentation files   [Contents][Index]

Next:Dynamic pages, Previous:Platform-specific documentation, Up:Writing R documentation files   [Contents][Index]

\ifelse{latex}{\out{$\alpha$}}{\ifelse{html}{\out{α}}{alpha}}

Next:User-defined macros, Previous:Conditional text, Up:Writing R documentation files   [Contents][Index]

Next:Encoding, Previous:Dynamic pages, Up:Writing R documentation files   [Contents][Index]

\newcommand{\PR}{\Sexpr[results=rd]{tools:::Rd_expr_PR(#1)}}

\PR{1234}

\Sexpr[results=rd]{tools:::Rd_expr_PR(1234)}

Next:Processing documentation files, Previous:User-defined macros, Up:Writing R documentation files   [Contents][Index]

\inputencoding{utf8}

\usepackage[utf8]{inputenc}

Next:Editing Rd files, Previous:Encoding, Up:Writing R documentation files   [Contents][Index]

Previous:Processing documentation files, Up:Writing R documentation files   [Contents][Index]

Next:Profiling R code for speed, Up:Tidying and profiling R code   [Contents][Index]

Next:Profiling R code for memory use, Previous:Tidying R code, Up:Tidying and profiling R code   [Contents][Index]

Next:Profiling compiled code, Previous:Profiling R code for speed, Up:Tidying and profiling R code   [Contents][Index]