This step-by-step tutorial shows how to use
drat to let
an R package utilise an R package available on some other
place that is not CRAN. We will
assume GitHub here as the (source)
location of the ‘other’ package, but any other source repository applies
equally for the source part of the other package.
The situation assumes your package (which you would like to publish
on CRAN) has a weak dependency on this other package (which is
something CRAN allows via an
entry). We will use this feature here, and have
drat be the
helper to create one such additional repository. The other package may
be written by you, or maybe someone else. Here we assume for simplicity
that it is written by someone else, under a suitable license but for
whichever reason not on CRAN. So the plan is to get the
other package into a
drat repo we set up so that
your package can refer to it via
Additional_repositories in its
We assume the following tools to be available, as well as reasonable familiarity with them:
git(and some familiarity with
giton the command-line).
We first prepare the other depended-upon R package so it is ready for upload to the to-be-created (not yet existing) new repository.
We start by downloading this R package from its GitHub repository.
https://github.com/donaldduck/quacking, and click the green “Code” button.
git clone email@example.com:donalduck/quacking
This will clone the repository to your local machine which creates a local copy typically used for read-only access.
Now that you have the source, create a package from them via
R CMD build . inside the
This will generate a source file, say
quacking_1.2.3.tar.gz, for this repository.
(You can also create a binary package if you want, and/or do so from,
say, within RStudio.
We focus on command-line use here.)
Go to https://github.com/drat-base/drat and fork the repository by
clicking the button “Fork”. You now have a remote copy of that
https://github.com/YourName/drat that can
serve as your
drat repository, and to which we will add
your own content below. (There are other ways using e.g.
dratInit() but we ignore this here to focus on the start
Next, we have to ensure your
drat repository can server
over https. Go to “Settings” on
https://github.com/YourName/drat and scroll down to “GitHub
Pages”. Specify “master” below “Branch” and “docs” right of it and click
“Save”. GitHub should now state that Your site is ready to be
published and list
its address. Note that the forked
drat repository still
contains a copy of the
drat sources (in order to be a
viable repository.) Once you added your content, you can remove it, or
just keep it.
This follows the steps above for creating a local copy of the
depended-upon package. Now we bring the freshly-forked
repository ‘home’ to your computer. So in the directory in which you
keep your git repositories, say
git clone https://github.com/YourName/drat
git clone firstname.lastname@example.org:YourName/drat.git
depending upon whether you prefer authentication via http or ssh.
This usually entails just a simple
drat is on
CRAN. However, currently
(spring 2021), we also want to ensure you have the most current version
that can use
docs/. To ensure this, install
its source repo from within R
(as we are using the
drat repo serving from
docs/ whereas the CRAN version still defaults to the older
scheme of a
Now continue in R (and we
assume we are in your
git working directory with both the
quacking repository as well as a
drat repo right below the working directory).
library(drat) options(dratBranch="docs") # to default to using docs/ as we set up insertPackage(file=c("quacking/quacking_1.2.3.tar.gz", "quacking/quacking_1.2.3.zip"), repodir="drat/")
In the above “1.2.3” is a possible placeholder for the actual version
number of the quacking package, just as quacking is a placeholder for
your actual package of interest. This will add the quacking source and
binary package to the folders
drat/docs/bin/windows/contrib/4.0. If you only have a
source package, just omit the binary package ending in
Optionally, change the content of the file
drat/README.md to fit your purpose. The file can be also be
In the terminal, execute
cd drat to get into the
If you use
git for the first time, execute:
git config --global user.email "youremail@yourdomainhere" git config --global user.name "YourName"
This will tell git your identity. If you want to use
ssh, you may want to upload an ssh key; see the relevant
git add . git commit -m "Added quacking" git push origin master
This will upload the quacking package to the repository on GitHub.
(You could add the
quacking package version and/or
git sha1 to the commit message but that is entirely
To test whether the package can be installed from your new repository, type in R
and verify that the package is installed successfully. (Note that you
may have to say
type="source" if your operating system
prefers source installation and you only added a source version to your
DESCRIPTION file of your R package:
Test the package via
R CMD check --as-cran packageName_0.1.2.tar.gz. If
everything passes, you are now ready for submission to CRAN.
If a directory has no content, browsing
https://yourname.github.io/drat will show “404 File not
found”. This can upset checks as for example the ones done by CRAN. As
of release 0.2.1,
inserts a minimal placeholder file to avoid this error.
This step by step demonstrated how to set up a
repository to serve an optional package referenced by
Suggests in a