forked from eddelbuettel/drat
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathDratForPackageAuthors.html
135 lines (113 loc) · 16 KB
/
DratForPackageAuthors.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="pandoc" />
<meta name="author" content="Dirk Eddelbuettel" />
<meta name="date" content="2015-05-24" />
<title>Drat Basics for Package Authors: Distributing Packages</title>
<style type="text/css">code{white-space: pre;}</style>
<style type="text/css">
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
margin: 0; padding: 0; vertical-align: baseline; border: none; }
table.sourceCode { width: 100%; line-height: 100%; }
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
td.sourceCode { padding-left: 5px; }
code > span.kw { color: #007020; font-weight: bold; }
code > span.dt { color: #902000; }
code > span.dv { color: #40a070; }
code > span.bn { color: #40a070; }
code > span.fl { color: #40a070; }
code > span.ch { color: #4070a0; }
code > span.st { color: #4070a0; }
code > span.co { color: #60a0b0; font-style: italic; }
code > span.ot { color: #007020; }
code > span.al { color: #ff0000; font-weight: bold; }
code > span.fu { color: #06287e; }
code > span.er { color: #ff0000; font-weight: bold; }
</style>
<style type="text/css">
pre:not([class]) {
background-color: white;
}
</style>
<link href="data:text/css,body%20%7B%0A%20%20background%2Dcolor%3A%20%23fff%3B%0A%20%20margin%3A%201em%20auto%3B%0A%20%20max%2Dwidth%3A%20700px%3B%0A%20%20overflow%3A%20visible%3B%0A%20%20padding%2Dleft%3A%202em%3B%0A%20%20padding%2Dright%3A%202em%3B%0A%20%20font%2Dfamily%3A%20%22Open%20Sans%22%2C%20%22Helvetica%20Neue%22%2C%20Helvetica%2C%20Arial%2C%20sans%2Dserif%3B%0A%20%20font%2Dsize%3A%2014px%3B%0A%20%20line%2Dheight%3A%201%2E35%3B%0A%7D%0A%0A%23header%20%7B%0A%20%20text%2Dalign%3A%20center%3B%0A%7D%0A%0A%23TOC%20%7B%0A%20%20clear%3A%20both%3B%0A%20%20margin%3A%200%200%2010px%2010px%3B%0A%20%20padding%3A%204px%3B%0A%20%20width%3A%20400px%3B%0A%20%20border%3A%201px%20solid%20%23CCCCCC%3B%0A%20%20border%2Dradius%3A%205px%3B%0A%0A%20%20background%2Dcolor%3A%20%23f6f6f6%3B%0A%20%20font%2Dsize%3A%2013px%3B%0A%20%20line%2Dheight%3A%201%2E3%3B%0A%7D%0A%20%20%23TOC%20%2Etoctitle%20%7B%0A%20%20%20%20font%2Dweight%3A%20bold%3B%0A%20%20%20%20font%2Dsize%3A%2015px%3B%0A%20%20%20%20margin%2Dleft%3A%205px%3B%0A%20%20%7D%0A%0A%20%20%23TOC%20ul%20%7B%0A%20%20%20%20padding%2Dleft%3A%2040px%3B%0A%20%20%20%20margin%2Dleft%3A%20%2D1%2E5em%3B%0A%20%20%20%20margin%2Dtop%3A%205px%3B%0A%20%20%20%20margin%2Dbottom%3A%205px%3B%0A%20%20%7D%0A%20%20%23TOC%20ul%20ul%20%7B%0A%20%20%20%20margin%2Dleft%3A%20%2D2em%3B%0A%20%20%7D%0A%20%20%23TOC%20li%20%7B%0A%20%20%20%20line%2Dheight%3A%2016px%3B%0A%20%20%7D%0A%0Atable%20%7B%0A%20%20margin%3A%201em%20auto%3B%0A%20%20border%2Dwidth%3A%201px%3B%0A%20%20border%2Dcolor%3A%20%23DDDDDD%3B%0A%20%20border%2Dstyle%3A%20outset%3B%0A%20%20border%2Dcollapse%3A%20collapse%3B%0A%7D%0Atable%20th%20%7B%0A%20%20border%2Dwidth%3A%202px%3B%0A%20%20padding%3A%205px%3B%0A%20%20border%2Dstyle%3A%20inset%3B%0A%7D%0Atable%20td%20%7B%0A%20%20border%2Dwidth%3A%201px%3B%0A%20%20border%2Dstyle%3A%20inset%3B%0A%20%20line%2Dheight%3A%2018px%3B%0A%20%20padding%3A%205px%205px%3B%0A%7D%0Atable%2C%20table%20th%2C%20table%20td%20%7B%0A%20%20border%2Dleft%2Dstyle%3A%20none%3B%0A%20%20border%2Dright%2Dstyle%3A%20none%3B%0A%7D%0Atable%20thead%2C%20table%20tr%2Eeven%20%7B%0A%20%20background%2Dcolor%3A%20%23f7f7f7%3B%0A%7D%0A%0Ap%20%7B%0A%20%20margin%3A%200%2E5em%200%3B%0A%7D%0A%0Ablockquote%20%7B%0A%20%20background%2Dcolor%3A%20%23f6f6f6%3B%0A%20%20padding%3A%200%2E25em%200%2E75em%3B%0A%7D%0A%0Ahr%20%7B%0A%20%20border%2Dstyle%3A%20solid%3B%0A%20%20border%3A%20none%3B%0A%20%20border%2Dtop%3A%201px%20solid%20%23777%3B%0A%20%20margin%3A%2028px%200%3B%0A%7D%0A%0Adl%20%7B%0A%20%20margin%2Dleft%3A%200%3B%0A%7D%0A%20%20dl%20dd%20%7B%0A%20%20%20%20margin%2Dbottom%3A%2013px%3B%0A%20%20%20%20margin%2Dleft%3A%2013px%3B%0A%20%20%7D%0A%20%20dl%20dt%20%7B%0A%20%20%20%20font%2Dweight%3A%20bold%3B%0A%20%20%7D%0A%0Aul%20%7B%0A%20%20margin%2Dtop%3A%200%3B%0A%7D%0A%20%20ul%20li%20%7B%0A%20%20%20%20list%2Dstyle%3A%20circle%20outside%3B%0A%20%20%7D%0A%20%20ul%20ul%20%7B%0A%20%20%20%20margin%2Dbottom%3A%200%3B%0A%20%20%7D%0A%0Apre%2C%20code%20%7B%0A%20%20background%2Dcolor%3A%20%23f7f7f7%3B%0A%20%20border%2Dradius%3A%203px%3B%0A%20%20color%3A%20%23333%3B%0A%7D%0Apre%20%7B%0A%20%20white%2Dspace%3A%20pre%2Dwrap%3B%20%20%20%20%2F%2A%20Wrap%20long%20lines%20%2A%2F%0A%20%20border%2Dradius%3A%203px%3B%0A%20%20margin%3A%205px%200px%2010px%200px%3B%0A%20%20padding%3A%2010px%3B%0A%7D%0Apre%3Anot%28%5Bclass%5D%29%20%7B%0A%20%20background%2Dcolor%3A%20%23f7f7f7%3B%0A%7D%0A%0Acode%20%7B%0A%20%20font%2Dfamily%3A%20Consolas%2C%20Monaco%2C%20%27Courier%20New%27%2C%20monospace%3B%0A%20%20font%2Dsize%3A%2085%25%3B%0A%7D%0Ap%20%3E%20code%2C%20li%20%3E%20code%20%7B%0A%20%20padding%3A%202px%200px%3B%0A%7D%0A%0Adiv%2Efigure%20%7B%0A%20%20text%2Dalign%3A%20center%3B%0A%7D%0Aimg%20%7B%0A%20%20background%2Dcolor%3A%20%23FFFFFF%3B%0A%20%20padding%3A%202px%3B%0A%20%20border%3A%201px%20solid%20%23DDDDDD%3B%0A%20%20border%2Dradius%3A%203px%3B%0A%20%20border%3A%201px%20solid%20%23CCCCCC%3B%0A%20%20margin%3A%200%205px%3B%0A%7D%0A%0Ah1%20%7B%0A%20%20margin%2Dtop%3A%200%3B%0A%20%20font%2Dsize%3A%2035px%3B%0A%20%20line%2Dheight%3A%2040px%3B%0A%7D%0A%0Ah2%20%7B%0A%20%20border%2Dbottom%3A%204px%20solid%20%23f7f7f7%3B%0A%20%20padding%2Dtop%3A%2010px%3B%0A%20%20padding%2Dbottom%3A%202px%3B%0A%20%20font%2Dsize%3A%20145%25%3B%0A%7D%0A%0Ah3%20%7B%0A%20%20border%2Dbottom%3A%202px%20solid%20%23f7f7f7%3B%0A%20%20padding%2Dtop%3A%2010px%3B%0A%20%20font%2Dsize%3A%20120%25%3B%0A%7D%0A%0Ah4%20%7B%0A%20%20border%2Dbottom%3A%201px%20solid%20%23f7f7f7%3B%0A%20%20margin%2Dleft%3A%208px%3B%0A%20%20font%2Dsize%3A%20105%25%3B%0A%7D%0A%0Ah5%2C%20h6%20%7B%0A%20%20border%2Dbottom%3A%201px%20solid%20%23ccc%3B%0A%20%20font%2Dsize%3A%20105%25%3B%0A%7D%0A%0Aa%20%7B%0A%20%20color%3A%20%230033dd%3B%0A%20%20text%2Ddecoration%3A%20none%3B%0A%7D%0A%20%20a%3Ahover%20%7B%0A%20%20%20%20color%3A%20%236666ff%3B%20%7D%0A%20%20a%3Avisited%20%7B%0A%20%20%20%20color%3A%20%23800080%3B%20%7D%0A%20%20a%3Avisited%3Ahover%20%7B%0A%20%20%20%20color%3A%20%23BB00BB%3B%20%7D%0A%20%20a%5Bhref%5E%3D%22http%3A%22%5D%20%7B%0A%20%20%20%20text%2Ddecoration%3A%20underline%3B%20%7D%0A%20%20a%5Bhref%5E%3D%22https%3A%22%5D%20%7B%0A%20%20%20%20text%2Ddecoration%3A%20underline%3B%20%7D%0A%0A%2F%2A%20Class%20described%20in%20https%3A%2F%2Fbenjeffrey%2Ecom%2Fposts%2Fpandoc%2Dsyntax%2Dhighlighting%2Dcss%0A%20%20%20Colours%20from%20https%3A%2F%2Fgist%2Egithub%2Ecom%2Frobsimmons%2F1172277%20%2A%2F%0A%0Acode%20%3E%20span%2Ekw%20%7B%20color%3A%20%23555%3B%20font%2Dweight%3A%20bold%3B%20%7D%20%2F%2A%20Keyword%20%2A%2F%0Acode%20%3E%20span%2Edt%20%7B%20color%3A%20%23902000%3B%20%7D%20%2F%2A%20DataType%20%2A%2F%0Acode%20%3E%20span%2Edv%20%7B%20color%3A%20%2340a070%3B%20%7D%20%2F%2A%20DecVal%20%28decimal%20values%29%20%2A%2F%0Acode%20%3E%20span%2Ebn%20%7B%20color%3A%20%23d14%3B%20%7D%20%2F%2A%20BaseN%20%2A%2F%0Acode%20%3E%20span%2Efl%20%7B%20color%3A%20%23d14%3B%20%7D%20%2F%2A%20Float%20%2A%2F%0Acode%20%3E%20span%2Ech%20%7B%20color%3A%20%23d14%3B%20%7D%20%2F%2A%20Char%20%2A%2F%0Acode%20%3E%20span%2Est%20%7B%20color%3A%20%23d14%3B%20%7D%20%2F%2A%20String%20%2A%2F%0Acode%20%3E%20span%2Eco%20%7B%20color%3A%20%23888888%3B%20font%2Dstyle%3A%20italic%3B%20%7D%20%2F%2A%20Comment%20%2A%2F%0Acode%20%3E%20span%2Eot%20%7B%20color%3A%20%23007020%3B%20%7D%20%2F%2A%20OtherToken%20%2A%2F%0Acode%20%3E%20span%2Eal%20%7B%20color%3A%20%23ff0000%3B%20font%2Dweight%3A%20bold%3B%20%7D%20%2F%2A%20AlertToken%20%2A%2F%0Acode%20%3E%20span%2Efu%20%7B%20color%3A%20%23900%3B%20font%2Dweight%3A%20bold%3B%20%7D%20%2F%2A%20Function%20calls%20%2A%2F%20%0Acode%20%3E%20span%2Eer%20%7B%20color%3A%20%23a61717%3B%20background%2Dcolor%3A%20%23e3d2d2%3B%20%7D%20%2F%2A%20ErrorTok%20%2A%2F%0A%0A" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="header">
<h1 class="title">Drat Basics for Package Authors: Distributing Packages</h1>
<h4 class="author"><em>Dirk Eddelbuettel</em></h4>
<h4 class="date"><em>2015-05-24</em></h4>
</div>
<div id="drat-overview" class="section level2">
<h2>Drat Overview</h2>
<p>The <a href="http://dirk.eddelbuettel.com/code/drat.html">drat</a> package makes it trivially easy to deploy package repositories. There are essentially just two ways to use a package repository:</p>
<ol style="list-style-type: decimal">
<li>You <em>write</em> to the repository as a <em>package author</em> to publish your package; or</li>
<li>You <em>read</em> from the reposiory as a <em>package user</em> to install or update one or more packages.</li>
</ol>
<p>This vignette deals with the first case: How to use <a href="http://dirk.eddelbuettel.com/code/drat.html">drat</a> as a package author. A <a href="DratForPackageUsers.html">companion vignette for package users</a> is available as well.</p>
</div>
<div id="case-1-using-github" class="section level2">
<h2>Case 1: Using GitHub</h2>
<div id="github-as-a-web-server" class="section level3">
<h3>GitHub as a Web Server</h3>
<p>The core motivation for <a href="http://dirk.eddelbuettel.com/code/drat.html">drat</a> comes from <a href="http://github.com">GitHub</a> and its implied web server. As you may know, <em>any</em> GitHub user (or organization) can enable a website for a given repository. All it takes is to create a <a href="http://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging">git branch</a> named <code>gh-pages</code>. After that, a website is automatically visible.</p>
<p>To make this more explicit, consider a hypothetical user John with account <code>johndoe</code>. Once John creates a repo <code>foo</code> and in it a branch <code>gh-pages</code>, he will have a web address <code>http://johndoe.github.io/foo</code> for this repo.</p>
<p>More formally, for a user <code>USER</code>, and a given repo named <code>drat</code>, we can always assume <code>http://USER.github.io/drat</code>.</p>
<p>So for you as a package author with a given GitHub account, all that is needed is a repository named <code>drat</code> with a <code>gh-pages</code> branch. If you are familiar with <code>git</code> at the command-line, you can just create the branch (and the <code>src/contrib/</code> directory structure in it; see below).</p>
<p>If you are less familiar with git, a really easy shortcut is to simply <a href="https://help.github.com/articles/fork-a-repo/">fork</a> the actual <a href="http://dirk.eddelbuettel.com/code/drat.html">drat</a> repo. It contains the drat source code which you could keep, or remove. The fork only serves to set up the required <code>gh-pages</code> branch, and the <code>src/contrib/</code> directory.</p>
</div>
<div id="place-files-into-the-local-repo" class="section level3">
<h3>Place Files into the Local Repo</h3>
<p>We can now assume that you have a local git repository named <code>drat</code> with a subdirectory <code>src</code> containing a further subdirectory <code>contrib</code>.</p>
<p>You are now ready to insert a package into it. For simplicit, let us assume the package is named <code>myPkg</code> and is at version 0.5. So <code>R CMD build</code> created a file <code>myPkg_0.5.tar.gz</code>.</p>
<p>Then via</p>
<pre class="sourceCode r"><code class="sourceCode r">## insert given package into default drat repo on local file system
drat::<span class="kw">insertPackage</span>(<span class="st">"myPkg_0.5.tar.gz"</span>)</code></pre>
<p>the source package will be copied into the default drat repo at location <code>~/git/drat</code>. Should your git repository checkouts live in a different place on your machine, just specify this either via the <code>options()</code> entry “dratRepo” or directly:</p>
<pre class="sourceCode r"><code class="sourceCode r">## insert given package into given repo on local file system
drat::<span class="kw">insertPackage</span>(<span class="st">"myPkg_0.5.tar.gz"</span>, <span class="st">"/srv/projects/git/drat"</span>)</code></pre>
<p>In either case, the package will be copied into the repo, and the PACKAGES file will be updated.</p>
<p>Lastly, if you have <code>git</code> (the command-line tool) or the wicked <a href="http://cran.r-project.org/package=git2r">git2r</a> package installed, then you can also use the <code>commit=TRUE</code> 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).</p>
</div>
<div id="github-and-travis-integration" class="section level3">
<h3>GitHub and Travis Integration</h3>
<p><a href="https://github.com/csgillespie">Colin Gillespie</a> has provided a nice walk-through of how to have <a href="https://travis-ci.org/">Travis CI</a> automagically push packages into a <a href="http://dirk.eddelbuettel.com/code/drat.html">drat</a> repo. This is included as another (currently work-in-progress) vignette entitled <a href="https://github.com/eddelbuettel/drat/blob/master/vignettes/CombiningDratAndTravis.Rmd">Combining Drat And Travis</a> which can be found in the <a href="http://dirk.eddelbuettel.com/code/drat.html">drat</a> package just like this vignette.</p>
</div>
</div>
<div id="case-2-using-another-server-or-local-storage" class="section level2">
<h2>Case 2: Using Another Server or Local Storage</h2>
<p>Use of <a href="http://dirk.eddelbuettel.com/code/drat.html">drat</a> is not limited to GitHub. Any server you can</p>
<ul>
<li>write files to, and</li>
<li>serve via http or file access from</li>
</ul>
<p>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.</p>
<div id="place-files-into-the-local-repo-1" class="section level3">
<h3>Place Files into the Local Repo</h3>
<p>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 <code>/nfs/groups/groupABC/</code> where you created a directory <code>drat</code> within a directory <code>R</code>. We once again require that the resulting directory <code>/nfs/groups/groupABC/R/drat</code> contains a <code>src/contrib</code> directory structure.</p>
<p>Hence, the following command would copy the package and update the index files:</p>
<pre class="sourceCode r"><code class="sourceCode r">## insert given package into given repo on a network-local file system
drat::<span class="kw">insertPackage</span>(<span class="st">"myPkg_0.5.tar.gz"</span>, <span class="st">"file:/nfs/groups/groupABC/R/drat"</span>)</code></pre>
<p>This updates the PACKAGES file (and its compressed variant) after which the repository is ready to serve files. See <a href="DratForPackageUsers.html">the companion vignette</a> for how to deploy it. Note that the location URL should begin with <code>file:</code>.</p>
</div>
</div>
<div id="summary" class="section level2">
<h2>Summary</h2>
<p><a href="http://dirk.eddelbuettel.com/code/drat.html">drat</a> 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 the <code>gh-pages</code> branch of a drat.</p>
<p>Repositories can also be local (and private) as well: all that <a href="http://dirk.eddelbuettel.com/code/drat.html">drat</a> requires to add packages is write access to a directory.</p>
<p>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 <a href="http://dirk.eddelbuettel.com/code/drat.html">drat</a> repository is described in <a href="DratForPackageUsers.html">the companion vignette</a>.</p>
</div>
<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
(function () {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
document.getElementsByTagName("head")[0].appendChild(script);
})();
</script>
</body>
</html>