In sboehringer/package: Create packages from R-code directly

Purpose of the package

This package is meant to allow the development of ad-hoc packages in a couple of minutes. All that is needed is a single R list that defines project properties and is typically 20-30 lines long. Here is an example:

packageDefinition = list(
    name = 'pkg-minimal',
    description = list(
            title = 'Minimal R-package created with `package`',
            author = 'Stefan Böhringer <[e-mail]>',
            description = 'This appears in the package-documentaion, the markdown of the git-repository and in the package details.',
            depends = c(),
            suggests = c(),
            license = 'LGPL',
            news = "0.1-0   Initial release"
    )
);

The description key contains a list with information that goes into the DESCRIPTION file of the R-package. Apart from this list, the file (or another one) should contain the functions you want to put into the package. For example:

#' Subject yourself to a message
#' 
#' This function will subject yourself to a message
#' 
#' @author Stefan Böhringer, \email{r-packages@@s-boehringer.org}
#' @examples
#' 
#' myLittlePony()
#'
#' @export myLittlePony
myLittlePony = function() {
    print('this is pateta');
}

The documentation is handled via package roxygen2, please consult the package documentation. In the example above, the function is exported using the roxygen2 directive @export.

Git use

The package definition can be amended with a git section like so:

packageDefinition = list(
    name = 'pkg-minimal',
    description = list(
            title = 'Minimal R-package created with `package`',
            author = 'Stefan Böhringer <[e-mail]>',
            description = 'This appears in the package-documentaion, the markdown of the git-repository and in the package details.',
            depends = c(),
            suggests = c(),
            license = 'LGPL',
            news = "0.1-0   Initial release"
    ),
    git = list(
        readme = '## Installation\n```r\nlibrary(devtools);\ninstall_github("githubuser/pkg-minimal")\n```\n',
        push = F,
        pushOnNewVersion = T,
        remote = 'https://github.com/githubuser/pkg-minimal.git'
    )
);

readme is a character string containing the content of the README file in markdown format. It will be literally written to the file README.md in the main folder of the package and is displayed on the homepage of the respository by sites such as github. push is a boolean to indicate whether createPackage should automatically push the local source tree. pushOnNewVersion restricts pusing to the creation of new versions (see next section). remote is the URL of the remote git server to be pushed to.

Creating Releases

Releases can be created through the news section of the package definition. If you use git and add a line for a new release, a git-tag with this version number is added to the repository. On github, this leads to the creation of a new release (i.e. tarball/zip for download). In the following example version 0.2-0 is created.

packageDefinition = list(
    name = 'pkg-minimal',
    description = list(
            title = 'Minimal R-package created with `package`',
            author = 'Stefan Böhringer <[e-mail]>',
            description = 'This appears in the package-documentaion, the markdown of the git-repository and in the package details.',
            depends = c(),
            suggests = c(),
            license = 'LGPL',
            news = "0.2-0  Release 0.2-0 was created by adding this line.\n0.1-0   Initial release"
    )
);

Supporting files

Supporing files are installed in subfolder Rscripts of the inst folder of the package. A character vector with path names can be supplied. All elements are copied recursively to the inst subfolder, taking the last path component as file/directory name in inst. For example:

packageDefinition = list(
    name = 'pkg-minimal',
    instFiles = list(Rscripts = 'Dev/pkg-minimal.R')
    #...
);

In the example above, the file pkg-minimal.R will be copied to the inst folder. These files can be accessed using the system.file function as documented in the general R-package creation documentation.

Vignettes

Vignettes can be written in R-markdown. A vignette entry in the list indicates all files to be included.

packageDefinition = list(
    name = 'pkg-minimal',
    description = list(
            title = 'Minimal R-package created with `package`',
            vignettes = "vignettes/vignette-package.Rmd"
            # ...
    )
);

Compiled files are copied to the doc subfolder of the package. The creation of markdown files (.md) is enforced. These can be used to create wiki-pages on popular code hosting sites (gitlab, github).

sboehringer/package documentation built on Jan. 12, 2023, 6:33 a.m.