"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’."
"Source packages can be built. This involves taking a source directory and creating a tarball ready for distribution"
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-…)
- 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"
This two steps process explains the difference between .onAttach() and .onLoad():
"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
✅ 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
⛔️ 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
- does not need to be set in UTF8
- does not support # comments
- 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
- Package (Letters, Numbers, dots, w/ at least 2 chars)
- Version (at least 2 non negative integers separates by . or -)
(The last two can be generated with ‘Authors@R’)
- "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."
✅ 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
✅ 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 <>
🖊 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."
Mandatory, "This field is what is reported by the maintainer function and used by bug.report"
✅ valid ( and "remain valid for the lifetime of the package")
✅ a person
⛔️ not a mailing list
⛔️ not a corporate entity
©️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)
🔐 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
▶️ 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