/usr/share/doc/racket/guide/module-basics.html is in racket-doc 6.7-3.
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 | <!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>6.1 Module Basics</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"><span style="font-weight: bold">The Racket Guide</span></a></td></tr></table></div><div class="tocviewsublisttop" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="intro.html" class="tocviewlink" data-pltdoc="x">Welcome to Racket</a></td></tr><tr><td align="right">2 </td><td><a href="to-scheme.html" class="tocviewlink" data-pltdoc="x">Racket Essentials</a></td></tr><tr><td align="right">3 </td><td><a href="datatypes.html" class="tocviewlink" data-pltdoc="x">Built-<wbr></wbr>In Datatypes</a></td></tr><tr><td align="right">4 </td><td><a href="scheme-forms.html" class="tocviewlink" data-pltdoc="x">Expressions and Definitions</a></td></tr><tr><td align="right">5 </td><td><a href="define-struct.html" class="tocviewlink" data-pltdoc="x">Programmer-<wbr></wbr>Defined Datatypes</a></td></tr><tr><td align="right">6 </td><td><a href="modules.html" class="tocviewselflink" data-pltdoc="x">Modules</a></td></tr><tr><td align="right">7 </td><td><a href="contracts.html" class="tocviewlink" data-pltdoc="x">Contracts</a></td></tr><tr><td align="right">8 </td><td><a href="i_o.html" class="tocviewlink" data-pltdoc="x">Input and Output</a></td></tr><tr><td align="right">9 </td><td><a href="regexp.html" class="tocviewlink" data-pltdoc="x">Regular Expressions</a></td></tr><tr><td align="right">10 </td><td><a href="control.html" class="tocviewlink" data-pltdoc="x">Exceptions and Control</a></td></tr><tr><td align="right">11 </td><td><a href="for.html" class="tocviewlink" data-pltdoc="x">Iterations and Comprehensions</a></td></tr><tr><td align="right">12 </td><td><a href="match.html" class="tocviewlink" data-pltdoc="x">Pattern Matching</a></td></tr><tr><td align="right">13 </td><td><a href="classes.html" class="tocviewlink" data-pltdoc="x">Classes and Objects</a></td></tr><tr><td align="right">14 </td><td><a href="units.html" class="tocviewlink" data-pltdoc="x">Units</a></td></tr><tr><td align="right">15 </td><td><a href="reflection.html" class="tocviewlink" data-pltdoc="x">Reflection and Dynamic Evaluation</a></td></tr><tr><td align="right">16 </td><td><a href="macros.html" class="tocviewlink" data-pltdoc="x">Macros</a></td></tr><tr><td align="right">17 </td><td><a href="languages.html" class="tocviewlink" data-pltdoc="x">Creating Languages</a></td></tr><tr><td align="right">18 </td><td><a href="concurrency.html" class="tocviewlink" data-pltdoc="x">Concurrency and Synchronization</a></td></tr><tr><td align="right">19 </td><td><a href="performance.html" class="tocviewlink" data-pltdoc="x">Performance</a></td></tr><tr><td align="right">20 </td><td><a href="parallelism.html" class="tocviewlink" data-pltdoc="x">Parallelism</a></td></tr><tr><td align="right">21 </td><td><a href="running.html" class="tocviewlink" data-pltdoc="x">Running and Creating Executables</a></td></tr><tr><td align="right">22 </td><td><a href="More_Libraries.html" class="tocviewlink" data-pltdoc="x">More Libraries</a></td></tr><tr><td align="right">23 </td><td><a href="dialects.html" class="tocviewlink" data-pltdoc="x">Dialects of Racket and Scheme</a></td></tr><tr><td align="right">24 </td><td><a href="other-editors.html" class="tocviewlink" data-pltdoc="x">Command-<wbr></wbr>Line Tools and Your Editor of Choice</a></td></tr><tr><td align="right"></td><td><a href="doc-bibliography.html" class="tocviewlink" data-pltdoc="x">Bibliography</a></td></tr><tr><td align="right"></td><td><a href="doc-index.html" class="tocviewlink" data-pltdoc="x">Index</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>6 </td><td><a href="modules.html" class="tocviewlink" data-pltdoc="x">Modules</a></td></tr></table><div class="tocviewsublist" style="display: block;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">6.1 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Module Basics</a></td></tr><tr><td align="right">6.2 </td><td><a href="Module_Syntax.html" class="tocviewlink" data-pltdoc="x">Module Syntax</a></td></tr><tr><td align="right">6.3 </td><td><a href="module-paths.html" class="tocviewlink" data-pltdoc="x">Module Paths</a></td></tr><tr><td align="right">6.4 </td><td><a href="module-require.html" class="tocviewlink" data-pltdoc="x">Imports:<span class="mywbr"> </span> <span class="RktSym"><span class="RktStxLink">require</span></span></a></td></tr><tr><td align="right">6.5 </td><td><a href="module-provide.html" class="tocviewlink" data-pltdoc="x">Exports:<span class="mywbr"> </span> <span class="RktSym"><span class="RktStxLink">provide</span></span></a></td></tr><tr><td align="right">6.6 </td><td><a href="module-set.html" class="tocviewlink" data-pltdoc="x">Assignment and Redefinition</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_2");">►</a></td><td>6.1 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Module Basics</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_2"><table cellspacing="0" cellpadding="0"><tr><td align="right">6.1.1 </td><td><a href="#%28part._module-org%29" class="tocviewlink" data-pltdoc="x">Organizing Modules</a></td></tr><tr><td align="right">6.1.2 </td><td><a href="#%28part._.Library_.Collections%29" class="tocviewlink" data-pltdoc="x">Library Collections</a></td></tr><tr><td align="right">6.1.3 </td><td><a href="#%28part._packages-and-collections%29" class="tocviewlink" data-pltdoc="x">Packages and Collections</a></td></tr><tr><td align="right">6.1.4 </td><td><a href="#%28part._link-collection%29" class="tocviewlink" data-pltdoc="x">Adding Collections</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">6.1.1<tt> </tt></span><a href="#%28part._module-org%29" class="tocsubseclink" data-pltdoc="x">Organizing Modules</a></td></tr><tr><td><span class="tocsublinknumber">6.1.2<tt> </tt></span><a href="#%28part._.Library_.Collections%29" class="tocsubseclink" data-pltdoc="x">Library Collections</a></td></tr><tr><td><span class="tocsublinknumber">6.1.3<tt> </tt></span><a href="#%28part._packages-and-collections%29" class="tocsubseclink" data-pltdoc="x">Packages and Collections</a></td></tr><tr><td><span class="tocsublinknumber">6.1.4<tt> </tt></span><a href="#%28part._link-collection%29" class="tocsubseclink" data-pltdoc="x">Adding Collections</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><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.7", "../");" 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.7");">top</a></span><span class="navright"> <a href="modules.html" title="backward to "6 Modules"" data-pltdoc="x">← prev</a> <a href="modules.html" title="up to "6 Modules"" data-pltdoc="x">up</a> <a href="Module_Syntax.html" title="forward to "6.2 Module Syntax"" data-pltdoc="x">next →</a></span> </div><h4 x-source-module="(lib "scribblings/guide/guide.scrbl")" x-source-pkg="racket-doc" x-part-tag=""module-basics"">6.1<tt> </tt><a name="(part._module-basics)"></a>Module Basics</h4><p>Each Racket module typically resides in its own file. For example,
suppose the file <span class="stt">"cake.rkt"</span> contains the following module:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"cake.rkt"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=index.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket</span></a></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">provide</a></span><span class="hspace"> </span><span class="RktSym">print-cake</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">draws a cake with </span><span class="RktSym">n</span><span class="RktCmt"> candles</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=define.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._define%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">print-cake</span><span class="hspace"> </span><span class="RktSym">n</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">show</span><span class="hspace"> </span><span class="RktVal">"</span><span class="hspace"> </span><span class="RktVal">~a</span><span class="hspace"> </span><span class="RktVal">"</span><span class="hspace"> </span><span class="RktSym">n</span><span class="hspace"> </span><span class="RktVal">#\.</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">show</span><span class="hspace"> </span><span class="RktVal">" .-~a-. "</span><span class="hspace"> </span><span class="RktSym">n</span><span class="hspace"> </span><span class="RktVal">#\|</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">show</span><span class="hspace"> </span><span class="RktVal">" | ~a | "</span><span class="hspace"> </span><span class="RktSym">n</span><span class="hspace"> </span><span class="RktVal">#\space</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">show</span><span class="hspace"> </span><span class="RktVal">"---~a---"</span><span class="hspace"> </span><span class="RktSym">n</span><span class="hspace"> </span><span class="RktVal">#\-</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=define.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._define%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">show</span><span class="hspace"> </span><span class="RktSym">fmt</span><span class="hspace"> </span><span class="RktSym">n</span><span class="hspace"> </span><span class="RktSym">ch</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=Writing.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._printf%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">printf</a></span><span class="hspace"> </span><span class="RktSym">fmt</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=strings.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._make-string%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">make-string</a></span><span class="hspace"> </span><span class="RktSym">n</span><span class="hspace"> </span><span class="RktSym">ch</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=Byte_and_String_Output.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._newline%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">newline</a></span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote></blockquote><p>Then, other modules can import <span class="stt">"cake.rkt"</span> to use the
<span class="RktSym">print-cake</span> function, since the <span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._provide%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">provide</a></span> line in
<span class="stt">"cake.rkt"</span> explicitly exports the definition
<span class="RktSym">print-cake</span>. The <span class="RktSym">show</span> function is private to
<span class="stt">"cake.rkt"</span> (i.e., it cannot be used from other modules),
since <span class="RktSym">show</span> is not exported.</p><p>The following <span class="stt">"random-cake.rkt"</span> module imports
<span class="stt">"cake.rkt"</span>:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"random-cake.rkt"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=index.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket</span></a></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="hspace"> </span><span class="RktVal">"cake.rkt"</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym">print-cake</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._random%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">random</a></span><span class="hspace"> </span><span class="RktVal">30</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote></blockquote><p>The relative reference <span class="RktVal">"cake.rkt"</span> in the import
<span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="stt"> </span><span class="RktVal">"cake.rkt"</span><span class="RktPn">)</span> works if the <span class="stt">"cake.rkt"</span> and
<span class="stt">"random-cake.rkt"</span> modules are in the same
directory. Unix-style relative paths are used for relative module
references on all platforms, much like relative URLs in HTML pages.</p><h5 x-source-module="(lib "scribblings/guide/guide.scrbl")" x-source-pkg="racket-doc" x-part-tag=""module-org"">6.1.1<tt> </tt><a name="(part._module-org)"></a>Organizing Modules</h5><p>The <span class="stt">"cake.rkt"</span> and <span class="stt">"random-cake.rkt"</span> example
demonstrates the most common way to organize a program into modules:
put all module files in a single directory (perhaps with
subdirectories), and then have the modules reference each other
through relative paths. A directory of modules can act as a
project, since it can be moved around on the filesystem or copied to
other machines, and relative paths preserve the connections among
modules.</p><p>As another example, if you are building a candy-sorting program, you
might have a main <span class="stt">"sort.rkt"</span> module that uses other modules
to access a candy database and a control sorting machine. If the
candy-database module itself is organized into sub-modules that handle
barcode and manufacturer information, then the database module could
be <span class="stt">"db/lookup.rkt"</span> that uses helper modules
<span class="stt">"db/barcodes.rkt"</span> and <span class="stt">"db/makers.rkt"</span>. Similarly,
the sorting-machine driver <span class="stt">"machine/control.rkt"</span> might use
helper modules <span class="stt">"machine/sensors.rkt"</span> and
<span class="stt">"machine/actuators.rkt"</span>.</p><blockquote class="SCentered"><p><img style="vertical-align: -16.830078125px; margin: -3px -3px -3px -3px;" src="pict.png" alt="image" width="462.33203125" height="322.0"/></p></blockquote><p>The <span class="stt">"sort.rkt"</span> module uses the relative paths
<span class="stt">"db/lookup.rkt"</span> and <span class="stt">"machine/control.rkt"</span> to import
from the database and machine-control libraries:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"sort.rkt"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=index.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket</span></a></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="hspace"> </span><span class="RktVal">"db/lookup.rkt"</span><span class="hspace"> </span><span class="RktVal">"machine/control.rkt"</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktSym">....</span></td></tr></table></blockquote></blockquote></blockquote><p>The <span class="stt">"db/lookup.rkt"</span> module similarly uses paths relative to
its own source to access the <span class="stt">"db/barcodes.rkt"</span> and
<span class="stt">"db/makers.rkt"</span> modules:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"db/lookup.rkt"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=index.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket</span></a></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="hspace"> </span><span class="RktVal">"barcode.rkt"</span><span class="hspace"> </span><span class="RktVal">"makers.rkt"</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktSym">....</span></td></tr></table></blockquote></blockquote></blockquote><p>Ditto for <span class="stt">"machine/control.rkt"</span>:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"machine/control.rkt"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=index.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket</span></a></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="hspace"> </span><span class="RktVal">"sensors.rkt"</span><span class="hspace"> </span><span class="RktVal">"actuators.rkt"</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktSym">....</span></td></tr></table></blockquote></blockquote></blockquote><p>Racket tools all work automatically with relative paths. For example,</p><p><span class="hspace"> </span><span class="stt">racket sort.rkt</span></p><p>on the command line runs the <span class="stt">"sort.rkt"</span> program and
automatically loads and compiles required modules. With a large enough
program, compilation from source can take too long, so use</p><p><span class="hspace"> </span><span class="stt">raco make sort.rkt</span></p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>See <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=raco&rel=make.html&version=6.7" class="Sq" data-pltdoc="x"><span class="stt">raco make</span>: Compiling Source to Bytecode</a> for more information on <span class="stt">raco make</span>.</p></blockquote></blockquote></blockquote><p>to compile <span class="stt">"sort.rkt"</span> and all its dependencies to bytecode
files. Running <span class="stt">racket sort.rkt</span> will automatically use bytecode
files when they are present.</p><h5 x-source-module="(lib "scribblings/guide/guide.scrbl")" x-source-pkg="racket-doc" x-part-tag=""Library_Collections"">6.1.2<tt> </tt><a name="(part._.Library_.Collections)"></a>Library Collections</h5><p>A <a name="(tech._collection)"></a><span style="font-style: italic">collection</span> is a hierarchical grouping of installed library modules. A
module in a <a href="#%28tech._collection%29" class="techoutside" data-pltdoc="x"><span class="techinside">collection</span></a> is referenced through an unquoted,
suffixless path. For example, the following module refers to the
<span class="stt">"date.rkt"</span> library that is part of the <span class="stt">"racket"</span>
<a href="#%28tech._collection%29" class="techoutside" data-pltdoc="x"><span class="techinside">collection</span></a>:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=index.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket</span></a></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="hspace"> </span><span class="RktSym">racket/date</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=Writing.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._printf%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">printf</a></span><span class="hspace"> </span><span class="RktVal">"Today is ~s\n"</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=time.html%23%2528def._%2528%2528lib._racket%252Fdate..rkt%2529._date-%7E3estring%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">date->string</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=time.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._seconds-%7E3edate%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">seconds->date</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=time.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._current-seconds%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">current-seconds</a></span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></blockquote><p>When you search the online Racket documentation, the search results
indicate the module that provides each binding. Alternatively, if you
reach a binding’s documentation by clicking on hyperlinks, you can
hover over the binding name to find out which modules provide
it.</p><p>A module reference like <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=time.html%23%2528mod-path._racket%252Fdate%2529&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket/date</span></a> looks like an
identifier, but it is not treated in the same way as <span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=Writing.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._printf%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">printf</a></span>
or <span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=time.html%23%2528def._%2528%2528lib._racket%252Fdate..rkt%2529._date-%7E3estring%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">date->string</a></span>. Instead, when <span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span> sees a module
reference that is unquoted, it converts the reference to a
collection-based module path:</p><ul><li><p>First, if the unquoted path contains no <span class="RktInBG"><span class="hspace"></span><span class="RktIn">/</span><span class="hspace"></span></span>, then
<span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span> automatically adds a <span class="stt">"/main"</span> to the
reference. For example, <span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="stt"> </span><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=slideshow&rel=index.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">slideshow</span></a><span class="RktPn">)</span> is equivalent to <span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="stt"> </span><span class="RktSym">slideshow/main</span><span class="RktPn">)</span>.</p></li><li><p>Second, <span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span> implicitly adds a <span class="stt">".rkt"</span>
suffix to the path.</p></li><li><p>Finally, <span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span> resolves the path by searching among
installed <a href="#%28tech._collection%29" class="techoutside" data-pltdoc="x"><span class="techinside">collections</span></a>, instead of treating the path as relative to
the enclosing module’s path.</p></li></ul><p>To a first approximation, a <a href="#%28tech._collection%29" class="techoutside" data-pltdoc="x"><span class="techinside">collection</span></a> is implemented as a
filesystem directory. For example, the <span class="stt">"racket"</span> collection is
mostly located in a <span class="stt">"racket"</span> directory within the Racket
installation’s <span class="stt">"collects"</span> directory, as reported by</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=index.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket</span></a></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="hspace"> </span><span class="RktSym">setup/dirs</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=Manipulating_Paths.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._build-path%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">build-path</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=raco&rel=dirs.html%23%2528def._%2528%2528lib._setup%252Fdirs..rkt%2529._find-collects-dir%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">find-collects-dir</a></span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">main collection directory</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVal">"racket"</span><span class="RktPn">)</span></td></tr></table></blockquote><p>The Racket installation’s <span class="stt">"collects"</span> directory, however, is
only one place that <span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span> looks for collection directories.
Other places include the user-specific directory reported by
<span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=raco&rel=dirs.html%23%2528def._%2528%2528lib._setup%252Fdirs..rkt%2529._find-user-collects-dir%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">find-user-collects-dir</a></span><span class="RktPn">)</span> and directories configured through
the <span class="stt">PLTCOLLECTS</span> search path. Finally, and most typically,
collections are found through installed <a href="#%28tech._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">packages</span></a>.</p><h5 x-source-module="(lib "scribblings/guide/guide.scrbl")" x-source-pkg="racket-doc" x-part-tag=""packages-and-collections"">6.1.3<tt> </tt><a name="(part._packages-and-collections)"></a>Packages and Collections</h5><p><div class="SIntrapara">A <a name="(tech._package)"></a><span style="font-style: italic">package</span> is a set of libraries that are installed through
the Racket package manager (or included as pre-installed in a Racket
distribution). For example, the <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=gui&rel=index.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket/gui</span></a> library is
provided by the <span class="stt">"gui"</span> package, while
<a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=parser-tools&rel=Lexers.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">parser-tools/lex</span></a> is provided by the
<span class="stt">"parser-tools"</span> library.</div><div class="SIntrapara"><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>More precisely,
<a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=gui&rel=index.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket/gui</span></a> is provided by <span class="stt">"gui-lib"</span>,
<a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=parser-tools&rel=Lexers.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">parser-tools/lex</span></a> is provided by
<span class="stt">"parser-tools-lib"</span>, and the <span class="stt">"gui"</span> and
<span class="stt">"parser-tools"</span> packages extend <span class="stt">"gui-lib"</span> and
<span class="stt">"parser-tools-lib"</span> with documentation.</p></blockquote></blockquote></blockquote></div></p><p>Racket programs do not refer to <a href="#%28tech._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">packages</span></a> directly. Instead,
programs refer to libraries via <a href="#%28tech._collection%29" class="techoutside" data-pltdoc="x"><span class="techinside">collections</span></a>, and adding or
removing a <a href="#%28tech._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">package</span></a> changes the set of collection-based
libraries that are available. A single package can supply
libraries in multiple collections, and two different packages can
supply libraries in the same collection (but not the same libraries,
and the package manager ensures that installed packages do not
conflict at that level).</p><p>For more information about packages, see <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=pkg&rel=index.html&version=6.7" class="Sq" data-pltdoc="x">Package Management in Racket</a>.</p><h5 x-source-module="(lib "scribblings/guide/guide.scrbl")" x-source-pkg="racket-doc" x-part-tag=""link-collection"">6.1.4<tt> </tt><a name="(part._link-collection)"></a>Adding Collections</h5><p>Looking back at the candy-sorting example of <a href="#%28part._module-org%29" data-pltdoc="x">Organizing Modules</a>,
suppose that modules in <span class="stt">"db/"</span> and <span class="stt">"machine/"</span> need a
common set of helper functions. Helper functions could be put in a
<span class="stt">"utils/"</span> directory, and modules in <span class="stt">"db/"</span> or
<span class="stt">"machine/"</span> could access utility modules with relative paths
that start <span class="stt">"../utils/"</span>. As long as a set of modules work
together in a single project, it’s best to stick with relative paths.
A programmer can follow relative-path references without knowing about
your Racket configuration.</p><p>Some libraries are meant to be used across multiple projects, so that
keeping the library source in a directory with its uses does not make
sense. In that case, the best option is add a new
<a href="#%28tech._collection%29" class="techoutside" data-pltdoc="x"><span class="techinside">collection</span></a>. After the library is in a collection, it can be
referenced with an unquoted path, just like libraries that are
included with the Racket distribution.</p><p>You could add a new collection by placing files in the Racket
installation or one of the directories reported by
<span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=raco&rel=dirs.html%23%2528def._%2528%2528lib._setup%252Fdirs..rkt%2529._get-collects-search-dirs%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">get-collects-search-dirs</a></span><span class="RktPn">)</span>. Alternatively, you could add to
the list of searched directories by setting the <span class="stt">PLTCOLLECTS</span>
environment variable.<span class="refelem"><span class="refcolumn"><span class="refcontent">If you set <span class="stt">PLTCOLLECTS</span>,
include an empty path in by starting the value with a colon (Unix and
Mac OS X) or semicolon (Windows) so that the original search paths are
preserved.</span></span></span> The best option, however, is to add a <a href="#%28tech._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">package</span></a>.</p><p>Creating a package <span style="font-style: italic">does not</span> mean that you have to register with
a package server or perform a bundling step that copies your source
code into an archive format. Creating a package can simply mean using
the package manager to make your libraries locally accessible as a
collection from their current source locations.</p><p>For example, suppose you have a directory <span class="stt">"/usr/molly/bakery"</span>
that contains the <span class="stt">"cake.rkt"</span> module (from the
<a href="" data-pltdoc="x">beginning</a> of this section) and other
related modules. To make the modules available as a <span class="stt">"bakery"</span>
collection, either</p><ul><li><p>Use the <span class="stt">raco pkg</span> command-line tool:</p><p><span class="hspace"> </span><span class="stt">raco pkg install --link /usr/molly/bakery</span></p><p>where the <span class="nobreak"><span class="stt">--link</span></span> flag is not actually needed when the
provided path includes a directory separator.</p></li><li><p>Use DrRacket’s <span class="ssansserif">Package Manager</span> item from the
<span class="ssansserif">File</span> menu. In the <span class="ssansserif">Do What I Mean</span> panel,
click <span class="ssansserif">Browse...</span>, choose the
<span class="stt">"/usr/molly/bakery"</span> directory, and click
<span class="ssansserif">Install</span>.</p></li></ul><p>Afterward, <span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="stt"> </span><span class="RktSym">bakery/cake</span><span class="RktPn">)</span> from any module will import
the <span class="RktSym">print-cake</span> function from
<span class="stt">"/usr/molly/bakery/cake.rkt"</span>.</p><p>By default, the name of the directory that you install is used both as
the <a href="#%28tech._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">package</span></a> name and as the <a href="#%28tech._collection%29" class="techoutside" data-pltdoc="x"><span class="techinside">collection</span></a> that is provided
by the package. Also, the package manager normally defaults to
installation only for the current user, as opposed to all users of a
Racket installation. See <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=pkg&rel=index.html&version=6.7" class="Sq" data-pltdoc="x">Package Management in Racket</a> for more information.</p><p>If you intend to distribute your libraries to others, choose
collection and package names carefully. The collection namespace is
hierarchical, but top-level collection names are global, and the
package namespace is flat. Consider putting one-off libraries under
some top-level name like <span class="stt">"molly"</span> that identifies the
producer. Use a collection name like <span class="stt">"bakery"</span> when producing
the definitive collection of baked-goods libraries.</p><p>After your libraries are put in a <a href="#%28tech._collection%29" class="techoutside" data-pltdoc="x"><span class="techinside">collection</span></a> you can still
use <span class="stt">raco make</span> to compile the library sources, but it’s better
and more convenient to use <span class="stt">raco setup</span>. The <span class="stt">raco setup</span>
command takes a collection name (as opposed to a file name) and
compiles all libraries within the collection. In addition, <span class="stt">raco setup</span> can
build documentation for the collection and add it to the documentation
index, as specified by a <span class="stt">"info.rkt"</span> module in the collection.
See <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=raco&rel=setup.html&version=6.7" class="Sq" data-pltdoc="x"><span class="stt">raco setup</span>: Installation Management</a> for
more information on <span class="stt">raco setup</span>.</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.7", "../");" 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.7");">top</a></span><span class="navright"> <a href="modules.html" title="backward to "6 Modules"" data-pltdoc="x">← prev</a> <a href="modules.html" title="up to "6 Modules"" data-pltdoc="x">up</a> <a href="Module_Syntax.html" title="forward to "6.2 Module Syntax"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|