/usr/share/doc/racket/pkg/getting-started.html is in racket-doc 6.1-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><title>1 Getting Started with Packages</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="../racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">▼</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">Package Management in Racket</a></td></tr></table></div><div class="tocviewsublisttop" style="display: block;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Getting Started with Packages</a></td></tr><tr><td align="right">2 </td><td><a href="Package_Concepts.html" class="tocviewlink" data-pltdoc="x">Package Concepts</a></td></tr><tr><td align="right">3 </td><td><a href="cmdline.html" class="tocviewlink" data-pltdoc="x">Using <span class="stt">raco pkg</span></a></td></tr><tr><td align="right">4 </td><td><a href="metadata.html" class="tocviewlink" data-pltdoc="x">Package Metadata</a></td></tr><tr><td align="right">5 </td><td><a href="strip.html" class="tocviewlink" data-pltdoc="x">Source, Binary, and Built Packages</a></td></tr><tr><td align="right">6 </td><td><a href="apis.html" class="tocviewlink" data-pltdoc="x">Package APIs</a></td></tr><tr><td align="right">7 </td><td><a href="catalog-protocol.html" class="tocviewlink" data-pltdoc="x">Package Catalog Protocol</a></td></tr><tr><td align="right">8 </td><td><a href="PLaneT_Compatibility.html" class="tocviewlink" data-pltdoc="x"><span class="planetName">PLane<span class="mywbr"> </span>T</span> Compatibility</a></td></tr><tr><td align="right">9 </td><td><a href="FAQ.html" class="tocviewlink" data-pltdoc="x">FAQ</a></td></tr><tr><td align="right">10 </td><td><a href="Future_Plans.html" class="tocviewlink" data-pltdoc="x">Future Plans</a></td></tr><tr><td align="right">11 </td><td><a href="implementation.html" class="tocviewlink" data-pltdoc="x">How Package Installation and Distribution Works</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_1");">►</a></td><td>1 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Getting Started with Packages</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">1.1 </td><td><a href="#%28part._.What_is_a_.Package_%29" class="tocviewlink" data-pltdoc="x">What is a Package?</a></td></tr><tr><td align="right">1.2 </td><td><a href="#%28part._.Inspecting_.Your_.Installation%29" class="tocviewlink" data-pltdoc="x">Inspecting Your Installation</a></td></tr><tr><td align="right">1.3 </td><td><a href="#%28part._finding-packages%29" class="tocviewlink" data-pltdoc="x">Finding Packages</a></td></tr><tr><td align="right">1.4 </td><td><a href="#%28part._installing-packages%29" class="tocviewlink" data-pltdoc="x">Installing Packages</a></td></tr><tr><td align="right">1.5 </td><td><a href="#%28part._updating-packages%29" class="tocviewlink" data-pltdoc="x">Updating Packages</a></td></tr><tr><td align="right">1.6 </td><td><a href="#%28part._removing-packages%29" class="tocviewlink" data-pltdoc="x">Removing Packages</a></td></tr><tr><td align="right">1.7 </td><td><a href="#%28part._how-to-create%29" class="tocviewlink" data-pltdoc="x">Creating Packages</a></td></tr><tr><td align="right">1.8 </td><td><a href="#%28part._how-to-share%29" class="tocviewlink" data-pltdoc="x">Sharing Packages</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber">1.1<tt> </tt></span><a href="#%28part._.What_is_a_.Package_%29" class="tocsubseclink" data-pltdoc="x">What is a Package?</a></td></tr><tr><td><span class="tocsublinknumber">1.2<tt> </tt></span><a href="#%28part._.Inspecting_.Your_.Installation%29" class="tocsubseclink" data-pltdoc="x">Inspecting Your Installation</a></td></tr><tr><td><span class="tocsublinknumber">1.3<tt> </tt></span><a href="#%28part._finding-packages%29" class="tocsubseclink" data-pltdoc="x">Finding Packages</a></td></tr><tr><td><span class="tocsublinknumber">1.4<tt> </tt></span><a href="#%28part._installing-packages%29" class="tocsubseclink" data-pltdoc="x">Installing Packages</a></td></tr><tr><td><span class="tocsublinknumber">1.5<tt> </tt></span><a href="#%28part._updating-packages%29" class="tocsubseclink" data-pltdoc="x">Updating Packages</a></td></tr><tr><td><span class="tocsublinknumber">1.6<tt> </tt></span><a href="#%28part._removing-packages%29" class="tocsubseclink" data-pltdoc="x">Removing Packages</a></td></tr><tr><td><span class="tocsublinknumber">1.7<tt> </tt></span><a href="#%28part._how-to-create%29" class="tocsubseclink" data-pltdoc="x">Creating Packages</a></td></tr><tr><td><span class="tocsublinknumber">1.8<tt> </tt></span><a href="#%28part._how-to-share%29" class="tocsubseclink" data-pltdoc="x">Sharing Packages</a></td></tr><tr><td><span class="tocsublinknumber">1.8.1<tt> </tt></span><a href="#%28part._github-deploy%29" class="tocsubseclink" data-pltdoc="x">Git<span class="mywbr"> </span>Hub Deployment</a></td></tr><tr><td><span class="tocsublinknumber">1.8.2<tt> </tt></span><a href="#%28part._manual-deploy%29" class="tocsubseclink" data-pltdoc="x">Manual Deployment</a></td></tr><tr><td><span class="tocsublinknumber">1.8.3<tt> </tt></span><a href="#%28part._register-at-catalog%29" class="tocsubseclink" data-pltdoc="x">Helping Others Discover Your Package</a></td></tr><tr><td><span class="tocsublinknumber">1.8.4<tt> </tt></span><a href="#%28part._.Naming_and_.Designing_.Packages%29" class="tocsubseclink" data-pltdoc="x">Naming and Designing Packages</a></td></tr><tr><td><span class="tocsublinknumber">1.8.5<tt> </tt></span><a href="#%28part._.Packages_.Compatible_with_.Racket_5_3_5_and_5_3_6%29" class="tocsubseclink" data-pltdoc="x">Packages Compatible with Racket 5.3.5 and 5.3.6</a></td></tr><tr><td><span class="tocsublinknumber">1.8.5.1<tt> </tt></span><a href="#%28part._.Version_.Exceptions%29" class="tocsubseclink" data-pltdoc="x">Version Exceptions</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox"><span class="version">6.1</span></div><div class="navsettop"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="index.html" title="backward to "Package Management in Racket"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "Package Management in Racket"" data-pltdoc="x">up</a> <a href="Package_Concepts.html" title="forward to "2 Package Concepts"" data-pltdoc="x">next →</a></span> </div><h3 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""getting-started"">1<tt> </tt><a name="(part._getting-started)"></a>Getting Started with Packages</h3><p>There are two ways to manage Racket package installations:</p><ul><li><p>The package manager graphical interface.</p><p>Most users access the package manager graphical interface
through DrRacket, which provides a <span class="ssansserif">Package
Manager...</span> item in the <span class="ssansserif">File</span> menu.</p><p>You can also install the <span class="stt">gui-pkg-manager</span> package,
with provides a <span class="ssansserif">Racket Package Manager</span> application
(which can be launched as <span class="stt">racket-package-manager</span> in a
command-line environment).</p></li><li><p>The <span class="stt">raco pkg</span> command-line tool.</p><p>The <span class="stt">raco</span> executable launches various Racket command-line
tools, and the <span class="stt">raco pkg</span> command groups various
package-management sub-commands. The different <span class="stt">raco pkg</span>
sub-commands are documented in <a href="cmdline.html" data-pltdoc="x">Using <span class="stt">raco pkg</span></a>.</p></li></ul><p>We’ll use the <span class="stt">raco pkg</span> command to describe package-management
operations here, but the graphical interface allows the same
operations.</p><h4 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""What_is_a_Package_"">1.1<tt> </tt><a name="(part._.What_is_a_.Package_)"></a>What is a Package?</h4><p>A <a href="Package_Concepts.html#%28tech._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">package</span></a> is not something that you refer to directly in your
Racket programs. Instead, a <a href="Package_Concepts.html#%28tech._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">package</span></a> is a set of libraries that
fit into the <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=collects.html%23%2528tech._collection%2529&version=6.1" class="techoutside Sq" data-pltdoc="x"><span class="techinside">collection</span></a> hierarchy, and you refer to libraries
through their <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=collects.html%23%2528tech._collection%2529&version=6.1" class="techoutside Sq" data-pltdoc="x"><span class="techinside">collection</span></a>-based paths. Libraries that are close
in the hierarchy may be provided by different packages, while a single
package may provide libraries that are far from each other in the
hierarchy (but that are conceptually related, somehow).</p><p>Racket documentation tells you which package provides a given library.
For example, the documentation for the <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=pict&rel=More_Pict_Constructors.html%23%2528mod-path._pict%252Fface%2529&version=6.1" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">pict/face</span></a>
library says that it is provided by the <span class="stt">pict-lib</span>
package.<span class="refelem"><span class="refcolumn"><span class="refcontent">If you’re reading this in a web browser, click
<a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=pict&rel=More_Pict_Constructors.html%23%2528mod-path._pict%252Fface%2529&version=6.1" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">pict/face</span></a> to go straight to its documentation.</span></span></span></p><p>Over time, packages may be refactored so that a library moves to a
different package, but the original package should continue to provide
the library, too, by declaring a dependency on the new package. More
generally, a package is intended to have an interface that only grows
in terms of libraries, bindings, and functionality, which provides a
basic level of backward compatibility. Incompatible changes should be
implemented in a new package.</p><h4 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""Inspecting_Your_Installation"">1.2<tt> </tt><a name="(part._.Inspecting_.Your_.Installation)"></a>Inspecting Your Installation</h4><p>To see the packages that you have installed already, use the
<a href="cmdline.html#%28part._raco-pkg-show%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg show</span></a> subcommand:</p><p><span class="hspace"> </span><span class="stt">raco pkg show</span></p><p>Unless you have an especially minimal Racket installation, you will
have packages installed already, probably listed in the
“Installation-wide” section. In fact, if you have a typical Racket
installation, then <a href="cmdline.html#%28part._raco-pkg-show%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg show</span></a> will initially show a
<span class="stt">main-distribution</span> package and a <span class="stt">racket-lib</span>
package:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="hspace"> </span><span class="stt">Installation-wide:</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt">Package</span><span class="hspace"> </span><span class="stt">Checksum</span><span class="hspace"> </span><span class="stt">Source</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt">main-distribution</span><span class="hspace"> </span><span class="stt">01..........ef</span><span class="hspace"> </span><span class="stt">(catalog main-distribution)</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt">racket-lib</span><span class="hspace"> </span><span class="stt">fe..........01</span><span class="hspace"> </span><span class="stt">(catalog racket-lib)</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt">User-specific for installation ....:</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt">[none]</span></p></td></tr></table></p><p>The “Checksum” column reports the specific implementation of each
package that is installed. A package can have a <a href="Package_Concepts.html#%28tech._version%29" class="techoutside" data-pltdoc="x"><span class="techinside">version</span></a> in a
more traditional sense, but the <a href="Package_Concepts.html#%28tech._checksum%29" class="techoutside" data-pltdoc="x"><span class="techinside">checksum</span></a> is the “version” as
far as the package system is concerned. When you request an update,
then a package installation is updated if the current implementation
of the package has a different <a href="Package_Concepts.html#%28tech._checksum%29" class="techoutside" data-pltdoc="x"><span class="techinside">checksum</span></a> than the installed
package, whether or not the package author adjusted the package’s
<a href="Package_Concepts.html#%28tech._version%29" class="techoutside" data-pltdoc="x"><span class="techinside">version</span></a>.</p><p>The “Source” column indicates how each package was installed. A
<span class="stt">catalog</span> source indicates that the package was installed by
consulting a <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a>. The name after <span class="stt">catalog</span> indicates the
name of the package as requested from the catalog, which is normally
(but not necessarily) the name of the package as it exists in your
installation. We discuss other possibilities for “Source” in
<a href="#%28part._installing-packages%29" data-pltdoc="x">Installing Packages</a>.</p><p>Neither the <span class="stt">main-distribution</span> package nor the
<span class="stt">racket-lib</span> package actually provides any libraries on its own,
but each declares dependencies on other packages. The
<span class="stt">racket-lib</span> package depends on native-library packages, if
any, for your platform. The <span class="stt">main-distribution</span> package
depends on lots of packages that have been selected for inclusion in
the main Racket distribution. If you provide the <span class="nobreak"><span class="stt">--all</span></span> flag to
<a href="cmdline.html#%28part._raco-pkg-show%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg show</span></a>, then you can see the packages that were
automatically installed as a result of installing
<span class="stt">main-distribution</span> and <span class="stt">racket-lib</span> (or whatever
packages you have explicitly selected for your installation).</p><p><span class="hspace"> </span><span class="stt">raco pkg show --all</span></p><p>An asterisk appears beside the name of every package that was
“auto-installed” to satisfy a dependency. All auto-installed
packages are as available for your use in the same way as explicitly
installed packages, but normally your code should refer only to
packages that you have explicitly installed. The difference between an
auto-installed and an explicitly installed package is how various
commands, such as <a href="cmdline.html#%28part._raco-pkg-show%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg show</span></a>, treat the package. If you
specifically request installation of a package that is
auto-installed, then the package is promoted and thereafter
treated as a explicitly installed package.</p><h4 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""finding-packages"">1.3<tt> </tt><a name="(part._finding-packages)"></a>Finding Packages</h4><p>The PLT <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a> at</p><blockquote class="SCentered"><p><a href="http://pkgs.racket-lang.org"><span class="url">http://pkgs.racket-lang.org</span></a></p></blockquote><p>provides a centralized listing of available Racket packages. The PLT
<a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a> normally will be the first place you check when
looking for a package.</p><p>There are other ways to distribute and reference packages. For
example, a package can be installed directly from a <span class="stt">".zip"</span>
file—<wbr></wbr>available locally or served from on a web site—<wbr></wbr>or from a
Github repository. Such direct references make sense when a package is
not yet ready for wide distribution or when it will never be of
interest to a wide audience. So, you may find non-catalog references
in mailing-list posts, recommended by your friends, or advertised in
e-mail spam.</p><p>There may be other <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a> services besides PLT’s. Note
that even if you discover a package name from PLT’s <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package
catalog</span></a>, your installation may be configured to consult a different
<a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a> to locate the package’s implementation (to
obtain a pre-built version of the package, for example), but you
should expect the installation-configured <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a> to
deliver the package that is described on the PLT <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package
catalog</span></a>.</p><h4 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""installing-packages"">1.4<tt> </tt><a name="(part._installing-packages)"></a>Installing Packages</h4><p>If you find a package by name from a <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a>, then
use the package’s name with <a href="cmdline.html#%28part._raco-pkg-install%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg install</span></a>:</p><p><span class="hspace"> </span><span class="stt">raco pkg install </span><span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span></p><p>If the package depends on other packages that you do not have
installed already, then <a href="cmdline.html#%28part._raco-pkg-install%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg install</span></a> will alert you and ask
whether it should install them, too. Use <span class="nobreak"><span class="stt">--auto</span></span> to
skip the question and make dependencies installed automatically.
Either way, packages installed to satisfy dependencies are marked as
auto-installed, which makes them easier to uninstall, and it also makes them hidden by
default for <a href="cmdline.html#%28part._raco-pkg-show%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg show</span></a> (since packages that are installed for
dependencies are an implementation detail that you usually do not care
about).</p><p>The argument that you provide to <a href="cmdline.html#%28part._raco-pkg-install%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg install</span></a> does not have
to be a package name that is recognized by a <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package
catalog</span></a>. In general, each argument to <a href="cmdline.html#%28part._raco-pkg-install%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg install</span></a> is a
<a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package source</span></a>. A <a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package source</span></a> can refer to a
<span class="stt">".zip"</span> file, a <span class="stt">".tar"</span> file, a Github repository, a
directory-structured web site, or a few other possibilities. In each
of those cases, a <a href="Package_Concepts.html#%28tech._package._name%29" class="techoutside" data-pltdoc="x"><span class="techinside">package name</span></a> is inferred from the
<a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package source</span></a>. After the package is installed, you use the
package name with other <span class="stt">raco pkg</span> commands to refer to the installed
package.</p><p>In fact, a <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a> does not actually serve package
implementations. It simply maps each <a href="Package_Concepts.html#%28tech._package._name%29" class="techoutside" data-pltdoc="x"><span class="techinside">package name</span></a> to a
<a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package source</span></a>. When the package manager consults a
<a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a>, it gets back a <a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package source</span></a> for the
actual package implementation, so each package installed from a
<a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a> is actually installed from a <span class="stt">".zip"</span>
file, Github repository, etc. Registering with a <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package
catalog</span></a> is just a way of making your package easier to find and
update.</p><h4 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""updating-packages"">1.5<tt> </tt><a name="(part._updating-packages)"></a>Updating Packages</h4><p>If your package installations become out of date, you can update
packages with <a href="cmdline.html#%28part._raco-pkg-update%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg update</span></a>:</p><p><span class="hspace"> </span><span class="stt">raco pkg update </span><span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span></p><p>Either specify individual packages to update, or use <span class="nobreak"><span class="stt">--all</span></span> to
update all installed packages for which a new <a href="Package_Concepts.html#%28tech._checksum%29" class="techoutside" data-pltdoc="x"><span class="techinside">checksum</span></a> is
available.</p><p>The way that the package manager finds updates depends on the way that
a package was installed. If it was installed by using a <a href="Package_Concepts.html#%28tech._package._name%29" class="techoutside" data-pltdoc="x"><span class="techinside">package
name</span></a> that was resolved by a <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a>, then the
<a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a> is consulted again to get the current
<a href="Package_Concepts.html#%28tech._checksum%29" class="techoutside" data-pltdoc="x"><span class="techinside">checksum</span></a> for the package, and the package is updated if the
<a href="Package_Concepts.html#%28tech._checksum%29" class="techoutside" data-pltdoc="x"><span class="techinside">checksum</span></a> doesn’t match the current installation. If the package
was installed directly from a Github reference, then Github is
consulted to get the current commit of a particular branch, and the
package is updated if the commit identifier doesn’t match the
<a href="Package_Concepts.html#%28tech._checksum%29" class="techoutside" data-pltdoc="x"><span class="techinside">checksum</span></a> of the current installation.</p><p>In some cases, updating a package may require an update to one of the
package’s dependencies. That should happen only when the package
requires a new binding, feature, or bug fix from the dependent
package, since packages are meant to evolve in an otherwise
backward-compatible way. Package <a href="Package_Concepts.html#%28tech._version%29" class="techoutside" data-pltdoc="x"><span class="techinside">versions</span></a> provide a way for
package authors to declare (and for the package manager to check)
those dependencies. The end result is that <a href="cmdline.html#%28part._raco-pkg-update%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg update</span></a> might
report a version-mismatch error that forces you to request more
package updates than you originally requested.</p><p>Normally, you provide <a href="Package_Concepts.html#%28tech._package._name%29" class="techoutside" data-pltdoc="x"><span class="techinside">package names</span></a> to
<a href="cmdline.html#%28part._raco-pkg-update%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg update</span></a>. More generally, you can provide a <a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package
source</span></a> to <a href="cmdline.html#%28part._raco-pkg-update%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg update</span></a>. In that case, a package with the same
name must be installed already, and the installed package is replaced
with the specified one. Replacing a package with a new <a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package
source</span></a> is a generalization of fetching a replacement package that has
a new <a href="Package_Concepts.html#%28tech._checksum%29" class="techoutside" data-pltdoc="x"><span class="techinside">checksum</span></a> at a previously specified source.</p><h4 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""removing-packages"">1.6<tt> </tt><a name="(part._removing-packages)"></a>Removing Packages</h4><p>As you might expect, <a href="cmdline.html#%28part._raco-pkg-remove%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg remove</span></a> removes a package:</p><p><span class="hspace"> </span><span class="stt">raco pkg remove </span><span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span></p><p>If the installation of a package triggered auto-installs of other
packages, then removing the package <span style="font-style: italic">does not</span> automatically
remove the auto-installed packages. Supply the <span class="nobreak"><span class="stt">--auto</span></span> flag for
<a href="cmdline.html#%28part._raco-pkg-remove%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg remove</span></a>, either by itself or when uninstalling packages,
to also remove any auto-installed packages that are left without
dependents.</p><p>The <a href="cmdline.html#%28part._raco-pkg-remove%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg remove</span></a> command will not remove a package if other
installed packages depend on it, unless you force the removal. If you want
to demote a package from explicitly installed to auto-installed (for
clean-up later, perhaps when other packages are removed), then
supply the <span class="nobreak"><span class="stt">--demote</span></span> flag to <a href="cmdline.html#%28part._raco-pkg-remove%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg remove</span></a>.</p><h4 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""how-to-create"">1.7<tt> </tt><a name="(part._how-to-create)"></a>Creating Packages</h4><p>A package normally starts life as a directory containing module files
and grows up to become a Github repository that is registered with a
<a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a>.</p><p>So, to create a package, first make a directory and select its name,
<span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span>:</p><p><span class="hspace"> </span><span class="stt">mkdir </span><span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span></p><p>Although a package can provide libraries in any number of
<a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=collects.html%23%2528tech._collection%2529&version=6.1" class="techoutside Sq" data-pltdoc="x"><span class="techinside">collections</span></a>, it’s common for a package to provide only
libraries in a collection that matches the package name. If that’s the
case for your package, then files implementing modules in the
<span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span> collection will go directly in the
<span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span> directory that you have created.</p><p>If your package implements multiple <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=collects.html%23%2528tech._collection%2529&version=6.1" class="techoutside Sq" data-pltdoc="x"><span class="techinside">collections</span></a>, then you’ll
need to add a basic <span class="stt">"info.rkt"</span> file in the
<span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span> directory:</p><p><div class="SIntrapara"><span class="hspace"> </span><span class="stt">cd </span><span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span></div><div class="SIntrapara"><span class="hspace"> </span><span class="stt">echo "#lang info" > info.rkt</span></div><div class="SIntrapara"><span class="hspace"> </span><span class="stt">echo "(define collection 'multi)" >> info.rkt</span></div></p><p>The <span class="RktSym">collection</span> definition tells the package manager that the
package implements libraries in multiple collections, and each
collection is represented by a sub-directory whose name matches the
collection name. Libraries for each collection go in the collection’s
directory.</p><p>You can start with a <a href="Package_Concepts.html#%28tech._single._collection._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">single-collection package</span></a> and later change
it to a <a href="Package_Concepts.html#%28tech._multi._collection._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">multi-collection package</span></a> by restructuring the package
directory, so you don’t have to worry much about the choice when you
get started.</p><p>Whether creating a <a href="Package_Concepts.html#%28tech._single._collection._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">single-collection package</span></a> or a
<a href="Package_Concepts.html#%28tech._multi._collection._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">multi-collection package</span></a>, the next step is to link your
development directory as a locally installed package. Use
<a href="cmdline.html#%28part._raco-pkg-install%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg install</span></a> in the <span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span> directory:</p><p><span class="hspace"> </span><span class="stt">raco pkg install</span></p><p>If you use <a href="cmdline.html#%28part._raco-pkg-show%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg show</span></a> at this point, you’ll see a line for
<span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span>. The “Source” column will show that it’s a
linked package, and the “Checksum” column will say <span class="stt">#f</span>,
which means that there is no checksum. Sub-commands like
<a href="cmdline.html#%28part._raco-pkg-update%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg update</span></a> will not work on a linked package, because
“updates” to the package happen whenever you modify the package’s
implementation.</p><p>Finally, inside the <span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span> directory, add directories
and/or files to implement the collections and/or modules that your
package provides. For example, the developer of a
<span class="stt">tic-tac-toe</span> <a href="Package_Concepts.html#%28tech._multi._collection._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">multi-collection package</span></a> that provides
<span class="RktSym">games/tic-tac-toe/main</span> and <span class="RktSym">data/matrix</span>
libraries might create directories and files like this:</p><p><div class="SIntrapara"><span class="hspace"> </span><span class="stt">mkdir -p games/tic-tac-toe</span></div><div class="SIntrapara"><span class="hspace"> </span><span class="stt">touch games/tic-tac-toe/info.rkt</span></div><div class="SIntrapara"><span class="hspace"> </span><span class="stt">touch games/tic-tac-toe/main.rkt</span></div><div class="SIntrapara"><span class="hspace"> </span><span class="stt">mkdir -p data</span></div><div class="SIntrapara"><span class="hspace"> </span><span class="stt">touch data/matrix.rkt</span></div></p><p>An <span class="stt">"info.rkt"</span> file is not necessary for a
<a href="Package_Concepts.html#%28tech._single._collection._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">single-collection package</span></a> with no dependencies, but you may
wish to create one, anyway, to hold dependency declarations. Every
package at least depends on <span class="stt">base</span>, which provides the
collections and libraries of a minimal Racket installation. To make
your package work best for other users, you will ultimately need to
declare all dependencies. (Fortunately, <span class="stt">raco setup</span> can check
dependencies and help you figure out what dependencies to declare.)</p><p>Even for a <a href="Package_Concepts.html#%28tech._single._collection._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">single-collection package</span></a>, you may want to create
<span class="stt">"info.rkt"</span> and include the definition</p><blockquote class="SCodeFlow"><p><span class="RktPn">(</span><span class="RktSym">define</span><span class="hspace"> </span><span class="RktSym">collection</span><span class="hspace"> </span><span class="RktVal">"</span><span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span><span class="RktVal">"</span><span class="RktPn">)</span></p></blockquote><p>This definition may seem redundant, since <span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span> is
available as the name of the enclosing directory, but declaring the
collection name explicitly prevents the meaning of your package’s implementation
from depending on the way that the implementation is referenced.</p><p>Finally, in the case of a <a href="Package_Concepts.html#%28tech._multi._collection._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">multi-collection package</span></a>, note that
the <span class="stt">"info.rkt"</span> file in <span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span> is for the
package, not for a collection. Definitions such as
<span class="RktSym">scribblings</span> or <span class="RktSym">raco-commands</span> work only in a
collection’s <span class="stt">"info.rkt"</span>. For a <a href="Package_Concepts.html#%28tech._single._collection._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">single-collection
package</span></a>, the <span class="stt">"info.rkt"</span> file serves double-duty for the
package and collection.</p><h4 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""how-to-share"">1.8<tt> </tt><a name="(part._how-to-share)"></a>Sharing Packages</h4><p>After your package is ready to deploy, choose either <a href="#%28part._github-deploy%29" data-pltdoc="x">GitHub Deployment</a>
or <a href="#%28part._manual-deploy%29" data-pltdoc="x">Manual Deployment</a>, and then go on to <a href="#%28part._register-at-catalog%29" data-pltdoc="x">Helping Others Discover Your Package</a>.</p><h5 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""github-deploy"">1.8.1<tt> </tt><a name="(part._github-deploy)"></a>GitHub Deployment</h5><p>First, <a href="https://github.com/signup/free">create a free account</a>
on GitHub, then
<a href="https://help.github.com/articles/create-a-repo">create a
repository for your package</a>. After that, your <a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package source</span></a>
is:</p><blockquote><p><span class="stt">git://github.com/</span><span class="sroman">‹<span style="font-style: italic">user</span>›</span><span class="stt">/</span><span class="sroman">‹<span style="font-style: italic">package</span>›</span></p></blockquote><p>If you want the package to be <span class="sroman">‹<span style="font-style: italic">branch</span>›</span> instead of <span class="stt">master</span>,
then add <span class="stt">"#<span class="sroman">‹<span style="font-style: italic">branch</span>›</span>"</span> to the end of the package source.</p><p>Whenever you</p><p><span class="hspace"> </span><span class="stt">git push</span></p><p>your changes will automatically be discovered by those who use
<span class="stt">raco pkg update</span> after installing from your
github-based <a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package source</span></a>.</p><h5 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""manual-deploy"">1.8.2<tt> </tt><a name="(part._manual-deploy)"></a>Manual Deployment</h5><p>Alternatively, you can deploy your package by publishing it on a URL
you control. If you do this, it is preferable to create an archive
from your package directory first:</p><p><span class="hspace"> </span><span class="stt">raco pkg create </span><span class="sroman">‹<span style="font-style: italic">package</span>›</span></p><p>Then, upload the archive and its <a href="Package_Concepts.html#%28tech._checksum%29" class="techoutside" data-pltdoc="x"><span class="techinside">checksum</span></a> to your site:</p><p><span class="hspace"> </span><span class="stt">scp </span><span class="sroman">‹<span style="font-style: italic">package</span>›</span><span class="stt">.zip </span><span class="sroman">‹<span style="font-style: italic">package</span>›</span><span class="stt">.zip.CHECKSUM your-host:public_html/</span></p><p>Your <a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package source</span></a> is then something like</p><blockquote><p><span class="stt">http://your-host/~</span><span class="sroman">‹<span style="font-style: italic">user</span>›</span><span class="stt">/</span><span class="sroman">‹<span style="font-style: italic">package</span>›</span><span class="stt">.zip</span></p></blockquote><p>Whenever you want to provide a new release of a package, recreate and reupload the
package archive (and <a href="Package_Concepts.html#%28tech._checksum%29" class="techoutside" data-pltdoc="x"><span class="techinside">checksum</span></a>). Your changes will automatically be
discovered by those who used your package source when they use
<span class="stt">raco pkg update</span>.</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>By default, <span class="stt">raco pkg create</span> generates a
<span class="stt">".zip"</span> archive. For more options, refer to the
<a href="cmdline.html#%28part._raco-pkg-create%29" class="plainlink" data-pltdoc="x"><span class="stt">raco pkg create</span></a> documentation. If you want to generate an archive
through some other means, simply archive what you made in the first
part of this section. For more formal details, refer to the
<a href="Package_Concepts.html#%28tech._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">package</span></a> definition.</p></blockquote></blockquote></blockquote><h5 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""register-at-catalog"">1.8.3<tt> </tt><a name="(part._register-at-catalog)"></a>Helping Others Discover Your Package</h5><p>By using either <a href="#%28part._github-deploy%29" data-pltdoc="x">GitHub Deployment</a> or <a href="#%28part._manual-deploy%29" data-pltdoc="x">Manual Deployment</a>,
anyone will be able to install your package by referring to your
<a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package source</span></a>. However, they will not be able to refer to it
by a simple name until it is listed on a <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a>.</p><p>If you’d like to use the PLT <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a>, browse
to
<a href="http://pkgs.racket-lang.org/">http://pkgs.racket-lang.org/</a>
and upload a new package. You will need to create an account and log
in first.</p><p>You only need to go to this site <span style="font-style: italic">once</span> to list your package. The
server will periodically check the package source you designate for
updates.</p><p>If you use this server, and if you use GitHub for deployment, then you
will never need to open a web browser to update your package for end
users. You just need to push to your GitHub repository, then within 24
hours, the PLT <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a> will notice, and <span class="stt">raco
pkg update</span> will work on your user’s machines.</p><h5 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""Naming_and_Designing_Packages"">1.8.4<tt> </tt><a name="(part._.Naming_and_.Designing_.Packages)"></a>Naming and Designing Packages</h5><p>We suggest the following conventions for naming and designing
packages:</p><ul><li><p>Packages should not include the name of the author or
organization that produces them, but be named based on the content of
the package. For example, <span class="stt">data-priority-queue</span> is preferred
to <span class="stt">johns-amazing-queues</span>.</p></li><li><p>Packages that provide an interface to a foreign library or
service should be named the same as the service. For example,
<span class="stt">cairo</span> is preferred to <span class="stt">Racket-cairo</span> or a similar
name.</p></li><li><p>Packages should not generally contain version-like elements in
their names, initially. Instead, version-like elements should be added
when backwards incompatible changes are necessary. For example,
<span class="stt">data-priority-queue</span> is preferred to
<span class="stt">data-priority-queue1</span>. Exceptions include packages that
present interfaces to external, versioned things, such as
<span class="stt">sqlite3</span> or <span class="stt">libgtk2</span>.</p></li><li><p>A <a href="Package_Concepts.html#%28tech._version%29" class="techoutside" data-pltdoc="x"><span class="techinside">version</span></a> declaration for a package is used only by other
package implementors to effectively declare dependencies on provided
features. Such declarations allow <span class="stt">raco pkg install</span> and
<span class="stt">raco pkg update</span> to help check dependencies. Declaring and
changing a version is optional, and the <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package catalog</span></a>
ignores version declarations; in particular, a package is a candidate
for updating when its <a href="Package_Concepts.html#%28tech._checksum%29" class="techoutside" data-pltdoc="x"><span class="techinside">checksum</span></a> changes, independent of whether
the package’s version changes or even in which direction the version
changes. We suggest using a version smaller than <span class="RktVal">"1.0"</span> to
indicate that a package’s interface is unstable and changing it to
<span class="RktVal">"1.0"</span> when you are ready to commit to backwards compatibility
going forward.</p></li><li><p>Packages should not combine large sets of utilities libraries
with other functionality. For example,
a package that contain many extensions to the <span class="stt">"racket"</span> collection, like
<span class="stt">"racket/more-lists.rkt"</span> and
<span class="stt">"racket/more-bools.rkt"</span>
should not also contain complete applications, as other packages
interested in the <span class="stt">"racket/more-bools.rkt"</span> library
will not wish to depend on in such application.</p></li><li><p>Packages should normally include both documentation and
implementation. To make the implementation of a package available
separately from its documentation (for use in environments where local
documentation is not useful), define a package
<span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span><span class="stt">-lib</span> to hold just the implementation,
<span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span><span class="stt">-doc</span> to hold the documentation, and
<span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span> that depends on both and that
“re-exports” both with an <span class="RktSym">implies</span> declaration (see
<a href="metadata.html" data-pltdoc="x">Package Metadata</a>). If you want to keep tests separate, put them a
<span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span><span class="stt">-test</span> package that is <span style="font-style: italic">not</span> a
dependency of <span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span>. Similarly, use
<span class="sroman">‹<span style="font-style: italic">pkg-name</span>›</span><span class="stt">-exe</span> for executables.</p></li><li><p>Packages should generally provide one collection with a name
similar to the name of the package. For example, <span class="stt">libgtk1</span>
should provide a collection named <span class="stt">"libgtk"</span>. Exceptions
include extensions to existing collection, such as new data-structures
for the <span class="stt">"data"</span> collection, DrRacket tools, new games for PLT
Games, etc.</p></li></ul><h5 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""Packages_Compatible_with_Racket_5_3_5_and_5_3_6"">1.8.5<tt> </tt><a name="(part._.Packages_.Compatible_with_.Racket_5_3_5_and_5_3_6)"></a>Packages Compatible with Racket 5.3.5 and 5.3.6</h5><p>A beta version of the package system was added to Racket starting in
version 5.3.5. By the time version 6.0 was released, some features
were added.</p><p>By using only certain older features, it is possible to make a package
that can be used with Racket versions 5.3.5, 5.3.6, 6.0, and newer.</p><p>In your <span class="RktSym">info.rkt</span>, you should:</p><ul><li><p>Use <span class="stt">#lang setup/infotab</span> (not <span class="stt">#lang info)</span>.</p></li><li><p>Use <span class="RktPn">(</span><span class="RktSym">define</span><span class="stt"> </span><span class="RktSym">collection</span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">multi</span><span class="RktPn">)</span>. Even if your package
has a single collection, put it in a subdirectory and make a
multi-collection package.</p></li><li><p>If you depend on a specific version of another package, state
this using the <span class="RktPn">(</span><span class="RktVar">other-package-name</span><span class="stt"> </span><span class="RktVar">required-version</span><span class="RktPn">)</span>
form (not the form with <span class="RktPn">#:version</span>).</p></li></ul><p>Finally, when listing your package on
<a href="http://pkgs.racket-lang-org"><span class="url">http://pkgs.racket-lang-org</span></a>, you should supply a GitHub source
using the URL format
<span class="stt">github://github.com/</span><span class="sroman">‹<span style="font-style: italic">user</span>›</span><span class="stt">/</span><span class="sroman">‹<span style="font-style: italic">repo</span>›</span><span class="stt">/</span><span class="sroman">‹<span style="font-style: italic">rev</span>›</span><span class="sroman">[</span>/<span class="sroman">‹<span style="font-style: italic">path</span>›</span><span class="sroman">]</span> (not
the <span class="stt">git:</span> format).</p><h5 x-source-module="(lib "pkg/scribblings/pkg.scrbl")" x-part-tag=""Version_Exceptions"">1.8.5.1<tt> </tt><a name="(part._.Version_.Exceptions)"></a>Version Exceptions</h5><p>To make supporting multiple versions of Racket easier, the <a href="Package_Concepts.html#%28tech._package._catalog%29" class="techoutside" data-pltdoc="x"><span class="techinside">package
catalog</span></a> software supports <a name="(tech._version._exception)"></a><span style="font-style: italic">version exception</span>s. Version exceptions
allow package authors to specify alternative <a href="Package_Concepts.html#%28tech._package._source%29" class="techoutside" data-pltdoc="x"><span class="techinside">package source</span></a>s to be used
when installing a given package using a specific version of Racket.</p><p>For example, a package that uses on Racket 6.0-specific features could provide
a <a href="#%28tech._version._exception%29" class="techoutside" data-pltdoc="x"><span class="techinside">version exception</span></a> for Racket 5.3.6 using a different branch in the
package’s Github repository, or a different zip archive, as package source.
Users installing the package from Racket 6.0 will use the default source for
the package, while those using Racket 5.3.5 will use the alternative branch /
archive.</p><p>For more details, see <a href="catalog-protocol.html" data-pltdoc="x">Package Catalog Protocol</a>.</p><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="index.html" title="backward to "Package Management in Racket"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "Package Management in Racket"" data-pltdoc="x">up</a> <a href="Package_Concepts.html" title="forward to "2 Package Concepts"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|