crant toolkit is designed to streamline the package development process.
crant is designed to be used on the command line and by
crant offers more than package development, providing utilities that span
the process of creating multiple working instances of R, to installing
packages from various sources, and building your own packages.
Make sure crant is in your path and then build your instances of R. If you already have an R instance and don't want to build from source, you can skip this step (although you still need to have crant in your path).
export PATH=$PATH:path/to/crant buildenv.sh -u
If the OS is brand new, then include the -d option to install dependencies. These include packages like make, gcc, gfortran, java, etc.
The end result is that you will have 3 installations of R built from source that correspond to the latest minor release (e.g. 2.15), the latest patch release (e.g. 2.15.2), and the current development source (R-devel).
As the source changes over time, you can re-build the R versions to stay current. The defaults will change by the maintainer to be current with the latest point and patch releases.
Libraries need to be built once R has been built successfully. These are typically the package dependencies you have. At a minimum you will probably want the unit testing packages since these are usually listed as 'suggested', so will not be downloaded automatically.
rpackage -R path/to/R RUnit testthat
The rpackage command knows about more than CRAN. You can also specify github repositories or private git repos.
rpackage futile.logger https://github.com/zatonovo/odessa/archive/master.zip https://user:firstname.lastname@example.org/repo.git
Note that if your R instance is in your path, you do not need to manually set the path to the R executable. This option is if you have multiple R installations (e.g. devel, patch, release) in your environment.
Building your package
crant script will build and check your package. If your source is within
a source repository, crant will attempt to export the latest committed version
to a separate directory (export). If you are in a source directory, crant
doesn't require any options. The no option call will build and check a package.
In active development, you might want to use these options:
which uses the local modified source code, skips checks, and installs the package after building.
When preparing for a release, consider
crant -u 3
which automatically increments the release version number. Use
-u 2 to
increment the minor version number.
If your documentation is inline with ROxygen, use the
(These options require the
The lower case
crant -SCix variant will build the source along with the
documentation, while the upper case variant
crant -X will halt the process.
This is useful if you need to test formatting. Once documentation is generated,
it is more efficient to not regenerate it on subsequent builds.
NOTE: If you use the
-X option on a project that does not use
man directory might become corrupted. ROxygen takes care to avoid
Crant will automatically increment version numbers by using the
The argument to
-u specifies the version number position. Many packages have
a three segment version number denoted major.minor.release. To increment the
minor version number, use
-u 2. Similarly, to increment the release version
-u 3 should be used.
Version numbers can also be set manually with the
crant -v 1.0.0
To ignore the repository version and pull the latest working copy use the
If testing your package just before uploading to CRAN, it is wise to test
against the three versions of R you built before. Use the same
-R option as
crant -v 1.0.0 -R path/to/R your.package
Note that crant will automatically update the version and date in the
R/*-package.R files for you.
In addition, for the files
ChangeLog, if a corresponding
file with the extension
.tmpl exists, its contents are prepended to the file
$BUILDDATE are substituted).
-s- Do not autocommit, allow dirty working copy
-S- Build against uncommitted source. Implies
-i- Install the package after building
-I- Copy (overwrite) the package
.tar.gzto the parent directory after building
-r- Run the CRAN checks
-C- Do not run
R CMD check
-V- Do not build vignettes, even not when running CRAN checks
-M- Do not build manual, even not when running CRAN checks
-u #- Increment version number at specific position, # = 1..4 (instead of
-d DATE- Specify build date
-X- Roxygenize and exit
-o- Copy output of example runs back to package source
-R /path/to/R- Use specific R interpreter
-b- Build binary package
-h HOSTNAME- Build binary package on Windows host
- SSH service and bash is assumed to be installed on remote Windows host
- Package is assumed to be located in directory
$WORKSPACEon remote host
-eExport to CRAN (not yet implemented)
R CMD build
Mac OS X Notes
Since Mac OS X comes from a BSD lineage, the versions of base utility
commands have different syntax. This causes a lot of problems. The
workaround is to install
coreutils, which installs the GNU
variants of all the commands. The crant script detects a Darwin platform
and will substitute the
g variants for the standard commands.
In addition, the
mktemp utility is coerced to use the proper options
depending on platform.