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.

  1. Create a free Anaconda.org account and record your new Anaconda.org username and password.

  2. Run conda install anaconda-client and enter your Anaconda.org username and password.

  3. 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.