2015-05-24
The drat package makes it trivially easy to deploy package repositories. There are essentially just two ways to use a package repository:
This vignette deals with the first case: How to use drat as a package author. A companion vignette for package users is available as well.
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 git
branch named 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 gh-pages (or 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 always assume
http://USER.github.io/drat.
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 familiar with git
at the command-line, you can just create the branch (and the
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
src/contrib/ directory.
We can now assume that you have a local git repository named
drat with a subdirectory src containing a
further subdirectory contrib.
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 a file
myPkg_0.5.tar.gz.
Then via
## 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 options() entry “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 git2r
package 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).
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.
Use of drat is not limited to GitHub. Any server you can
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.
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 under /nfs/groups/groupABC/ where you
created a directory drat within a directory 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
file:.
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 or a
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.