Building R packages with skeleton CRAN
Overview
This tutorial describes how to quickly build an R-language package on macOS for an R module that is already available on CRAN.
You will build a simple package that can be installed in any conda environment of the same R version as your root environment. The tutorial will also tell you how to build the dependencies that may arise while building the package.
Who is this for?
This tutorial is for macOS users who wish to build an R-language package from CRAN. No prior knowledge of conda-build or conda recipes is required.
Before you start
Before you start, check the prerequisites.
Building a simple package with conda skeleton CRAN
The conda skeleton command picks up the CRAN package metadata and prepares the conda-build recipe. The final step is to build the package itself and install it into your conda environment.
It is easy to build a skeleton recipe for any R package that is hosted on CRAN. In this section you are going to use conda skeleton to generate a conda recipe, which informs conda-build about where the source files are located and how to build and install the package.
You'll be working with a package that is hosted on CRAN named fansi, a tool that accounts for the effects of ANSI text formatting control sequences.
First, in your user home directory, run the conda skeleton command:
conda skeleton cran fansi
The two arguments to conda skeleton
are the type of hosting location,
in this case cran
, and the name of the package.
This creates a directory named r-fansi
and creates 1
skeleton file in that directory: meta.yaml
. Many other files
can be added there as necessary, such as build.sh
and bld.bat
,
test scripts, or anything else you need to build your software.
Use the ls
command to verify that this file has been created.
The meta.yaml
file has been populated with information from the
CRAN metadata and in many cases will not need to be edited.
Files in the folder with meta.yaml
are collectively referred to
as the "conda-build recipe":
meta.yaml
---Contains all the metadata in the recipe. The package name and package version sections are required---everything else is optional.bld.bat
---Windows commands to build the package.build.sh
---macOS and Linux commands to build the package.
Now that you have the conda-build recipe ready, you can use conda-build to create the package:
conda-build r-fansi
When conda-build is finished, it displays the exact path and
filename of the conda package. See Troubleshooting a sample issue if the
conda-build
command fails. If you receive an error with SDK on macOS,
review our resources for macOS and SDK.
Example file path:
/Users/jsmith/anaconda3/conda-bld/osx-64/r-fansi-0.4.0-r353h46e59ec_0.tar.bz2
Note
Your path and filename will vary depending on your installation and operating system. Save the path and filename information for the next step.
Now you can install your newly built package in your conda environment by using the use-local flag:
conda install --use-local r-fansi
Now verify that fansi installed successfully:
conda list
Scroll through the list until you find r-fansi
.
Notice that fansi is coming from the local conda-build channel.
(base) 0561:~ jsmith$ conda list
# packages in environment at /Users/Jsmith/anaconda3:
# Name Version Build Channel
qtpy 1.5.0 py37_0
r-base 3.5.1 h539fb6c_1
r-fansi 0.4.0 r353h46e59ec_0 local
The version of R will be what you have in your base environment.
See Optional---Building for a different R version to set your own R version.
At this point you now have a conda package for fansi that can be installed in any conda environment of its R version.
Building an R package with dependencies
The fansi package was a simple one that didn’t have dependencies. To build an R package with dependencies, let’s look at the example of janitor. Janitor is a package hosted on CRAN that is used for examining and cleaning up data.
To begin building it, type:
conda skeleton cran janitor
This creates a directory named r-janitor
and
creates one skeleton file in that directory: meta.yaml
.
Many other files can be added there as necessary, such
as build.sh
and bld.bat
, test scripts, or anything else
you need to build your software. Use the ls
command
to verify that this file has been created. The meta.yaml
file has been populated with information from the CRAN
metadata and in many cases will not need to be edited.
Now that you have the conda-build recipe ready, you can use conda-build to create the package:
conda-build r-janitor
What may happen at this point is that you will have dependencies of this package that do not exist as conda packages yet. They need to be turned into conda packages. Use conda skeleton to recursively build out recipes for the packages that it depends on:
conda skeleton cran janitor --recursive
You can manually build each package individually by typing:
conda-build package-name
Note
Replace "package-name" with the name of each package.
Once all of the package dependencies are resolved, you can build the R package by using:
conda-build .
Now you can install your newly built package in your conda environment by using the use-local flag:
conda install --use-local r-janitor
The remaining optional sections show you how to make R packages for other R versions and other architectures and how to upload them to your Anaconda.org account.
Optional---Building for a different R version
By default, conda-build creates packages for the version
of R installed in the root environment. To build packages
for other versions of R, you use the --R
flag followed by
a version.
For example, to explicitly build a version of the fansi package for R 3.6.1, use:
conda-build --R 3.6.1 r-fansi
Notice that the file printed at the end of the conda-build output has changed to reflect the requested version of R. Conda install will look in the package directory for the file that matches your current R version.
Example file path:
/Users/jsmith/anaconda3/conda-bld/osx-64/r-fansi-0.4.0-r353h46e59ec_0.tar.bz2
Note
Your path and filename will vary depending on your installation and operating system. Save the path and filename information for the next task.
Optional---Uploading packages to Anaconda.org
Anaconda.org is a repository for public or private packages.
Uploading to Anaconda.org allows you to easily install your package
in any environment with just the conda install
command,
rather than manually copying or moving the tarball file from
one location to another. You can choose to make your files
public or private.
For more information about Anaconda.org, see the Anaconda.org documentation.
Create a free Anaconda.org account and record your new Anaconda.org username and password.
Run
conda install anaconda-client
and enter your Anaconda.org username and password.Log into your Anaconda.org account from your terminal with the command
anaconda login
.
Now you can upload the new local packages to Anaconda.org.
anaconda upload /Users/jsmith/anaconda3/conda-bld/osx-64/r-fansi-0.4.0-r353h46e59ec_0.tar.bz2
Note
Change your path and filename to the exact path and
filename you saved in Optional---Building for a different R version. Your path and filename
will vary depending on your installation and operating system.
If you created packages for multiple versions of R,
you must use the anaconda upload
command to upload each one.
Tip
If you want to always automatically upload a successful build to Anaconda.org, run:
conda config --set anaconda_upload yes
You can log out of your Anaconda.org account with the command:
anaconda logout
More information
For more options, see the full conda skeleton command documentation.