Thread by @_ColinFay

#NowReading — Writing #RStats Extensions.
colinfay.me/writing-r-exte…

[Notes on terminology]
"A package is not a library."
Library refers to:
- "A directory into which packages are installed"
- "That used by the operating system, as a shared, dynamic or static library or (especially on Windows) a DLL, where the second L stands for ‘library’."

"Installation takes a source package and installs it in a library using R CMD INSTALL or install.packages."
"Source packages can be built. This involves taking a source directory and creating a tarball ready for distribution"

⚠️ "Compilation is not a correct term for a package"
Compilation refers to:
- compiling source code in 📦 with C, C++ or Fortran
- byte compiling 📦, which is done by default since R 3.5
(See also cran.r-project.org/doc/manuals/r-…)

There are 2 ways to bring a 📦 in memory:
- loading ⤴️, which is using pkg namespace without attaching it to the search path (done for example with pkg::fun() )
- attaching 🔗, which is making the 📦 visible in the search path.

Note that "Function library performs both steps"

[side note]
This two steps process explains the difference between .onAttach() and .onLoad():
stat.ethz.ch/R-manual/R-dev…

😴 Lazy loading — "When used the R objects of the package are created at installation time and stored in a database in the R directory of the installed package, being loaded into the session at first use. This makes the R session start up faster and use less (virtual) memory."

[Package structure]
"sources of an R package consists of a subdirectory containing a files DESCRIPTION and NAMESPACE, and the subdirectories R, data, demo, exec, inst, man, po, src, tests, tools and vignettes"
- some of which can be missing,
- ⚠️ but which should not be empty

Other possible files:
✅ INDEX, configure, cleanup, LICENSE, LICENCE and NEWS.
🙈 Other files such as INSTALL (for non-standard installation instructions), README/README.md2, or ChangeLog will be ignored by R

For configuration on install — 🛠 & 🧹:
Unix: ˋconfigureˋ and ˋcleanup` -> (Bourne) shell scripts executed before and (if option --clean was given) after installation
Windows: configure.win and cleanup.win

About file names:
⛔️ Not allowed characters :
- ‘"’, ‘*’, ‘:’, ‘/’, ‘<’, ‘>’, ‘?’, ‘\’, and ‘|’
⛔️ not allowed file names :
- ‘con’, ‘prn’, ‘aux’, ‘clock$’, ‘nul’, ‘com1’ to ‘com9’, and ‘lpt1’ to ‘lpt9’
✅ for maximal compatibility :
- only use ASCII characters

[The DESCRIPTION file]
The format of this file is based on the Debian Control Files :
debian.org/doc/debian-pol…
(Hence the read.dcf() — stat.ethz.ch/R-manual/R-dev…)

DESCRIPTION:
- does not need to be set in UTF8
- does not support # comments

Fields:
- start with an ASCII name immediately followed by a colon and a space
- continuation lines start with a tab or a space
- are case sensitive, and those used by R are capitalized

✔️ The mandatory fields in the DESCRIPTION are:
- Package (Letters, Numbers, dots, w/ at least 2 chars)
- Version (at least 2 non negative integers separates by . or -)
- License
- Description
- Author
- Maintainer
(The last two can be generated with ‘Authors@R’)

About version number :

- "A version such as ‘0.01’ or ‘0.01.0’ will be handled as if it were ‘0.1-0’."

- "It is not a decimal number, so for example 0.9 < 0.75 since 9 < 75."

Title field:

✅ gives a short description of the 📦
✅is in Title Case (use tools::toTitleCase if needed)

It doesn't :
⛔️ include markup
⛔️ have continuation line
⛔️ end in a period
⛔️ contain 📦 name

Software names -> in single quote
Book names -> in double quote

Description field:

✅ comprehensive explanation of the 📦
✅ one or more *complete* sentence(s)
⚠️ but only one paragraph
⚠️ "It is good practice not to start with the package name, ‘This package’ or similar."

Software & book names -> same as Title
URLs -> between <>

Author field:

🖊 who wrote the package — every significant contributor should be included.

⚠️ "if you wrote an R wrapper for the work of others included in the src directory, you are not the sole (and maybe not even the main) author."

Maintainer:

Mandatory, "This field is what is reported by the maintainer function and used by bug.report"

Must be:
✅ valid ( and "remain valid for the lifetime of the package")
✅ a person
⛔️ not a mailing list
⛔️ not a corporate entity

Possible fields:

©️Copyright: copyright holder, and refer to a file inst/COPYRIGHTS

📅 Date: in "yyyy-mm-dd" format

🔗 URL & BugReports

🧮 Collate: control the order in which the R files are processed on install (must contain all files of present)

💤 LazyData: wether or not the data are lazily loaded

🔐 KeepSource: wether or not to source with keep.source = TRUE

💱 Encoding: if not ASCII, the encoding for DESCRIPTION and NAMESPACE

➿ NeedsCompilation: if the package contains code to be compiled

(And others...)

TIL that you can "Classify' your #RStats 📦, and specify a Language

[licensing]
Disclaimer: licensing is complex but crucial

Possible licences :

▶️ GPL-2 GPL-3 LGPL-2 LGPL-2.1 LGPL-3 AGPL-3 Artistic-2.0 BSD_2_clause BSD_3_clause MIT
▶️ one defined in share/licenses/license.db
▶️ ‘file LICENCE’ (or LICENSE) (w/ a file)
▶️ ‘Unlimited’: no restriction whatsoever

⛔️'public Domain': not a valid licence