Drat Basics for Package Authors: Distributing Packages
The drat package makes it trivially easy to deploy package repositories. There are essentially just two ways to use a package repository:
1) You write to the repository as a package author to publish your package; or 1) You read from the reposiory as a package user to install or update one or more packages.
Case 1: Using GitHub
GitHub as a Web Server
The core motivation for drat
comes from GitHub and its implied web server. As you
may know, any GitHub user (or organization) can enable a website for a
given repository. All it takes is to create either a
gh-pages (if following the original scheme), or creating a directory
docs/ in the main branch. After that, a website should be automatically
visible (though you should check under 'Settings').
To make this more explicit, consider a hypothetical user John with account
johndoe. Once John creates a repo
foo and in it a branch
an activated directory
docs/), he will have a web address
http://johndoe.github.io/foo for this repo.
More formally, for a user
USER, and a given repo named
drat, we can
So for you as a package author with a given GitHub account, all that is
needed is a repository named
drat with a
gh-pages branch. If you are
git at the command-line, you can just create the branch (and
src/contrib/ directory structure in it; see below).
If you are less familiar with git, a really easy shortcut is to simply fork the actual
drat repo. It contains the
drat source code which you could keep, or remove. The fork only serves to
set up the required directory layout, and the
Place Files into the Local Repo
We can now assume that you have a local git repository named
drat with a
src containing a further subdirectory
You are now ready to insert a package into it. For simplicit, let us assume
the package is named
myPkg and is at version 0.5. So
R CMD build created
## insert given package into default drat repo on local file system drat::insertPackage("myPkg_0.5.tar.gz")
the source package will be copied into the default drat repo at location
~/git/drat. Should your git repository checkouts live in a different place
on your machine, just specify this either via the
"dratRepo" or directly:
## insert given package into given repo on local file system drat::insertPackage("myPkg_0.5.tar.gz", "/srv/projects/git/drat")
In either case, the package will be copied into the repo, and the PACKAGES file will be updated.
Lastly, if you have
git (the command-line tool) or the wicked
installed, then you can also use the
commit=TRUE option to have the new
files added and committed. Neither of these variant pushes, so that last
step is left to the user (as it commonly requires authentication).
GitHub and Travis Integration
Colin Gillespie has provided a nice walk-through of how to have Travis CI automagically push packages into a drat repo. This is included as another (currently work-in-progress) vignette entitled Combining Drat And Travis which can be found in the drat package just like this vignette.
Case 2: Using Another Server or Local Storage
Use of drat is not limited to GitHub. Any server you can
- write files to, and
- serve via http or file access from
is suitable. A common use case may be a local repository within a work group or deparment, meant to be locally accessible but not from an outside network.
Place Files into the Local Repo
This is similar to the usage described above. Suppose that you are part of
groupABC which has access to directory on shared filesystem somewhere, say
/nfs/groups/groupABC/ where you created a directory
drat within a
R. We once again require that the resulting directory
/nfs/groups/groupABC/R/drat contains a
src/contrib directory structure.
Hence, the following command would copy the package and update the index files:
## insert given package into given repo on a network-local file system drat::insertPackage("myPkg_0.5.tar.gz", "file://nfs/groups/groupABC/R/drat")
This updates the PACKAGES file (and its compressed variant) after which the
repository is ready to serve files. See
the companion vignette for how to deploy it.
Note that the location URL should begin with
drat permits package authors
to add packages very easily to R package repositories. These repositories can
be public, and GitHub provides a very natural option to serve a package
repository via the web server (based on either the
gh-pages branch of a drat
docs/ directory) to serve as GitHub Pages.
Repositories can also be local (and private) as well: all that drat requires to add packages is write access to a directory.
Lastly, serving that directory as a repository then requires a web server (easiest via the automatic GitHub repo option) or other file access. How to access packages from drat repository is described in the companion vignette.