Racket code is organised in collections and packages. A collection is a directory of modules, named by a path such as racket/list or net/url (the first part is the collection, the rest are folders and a file). A package is a unit of distribution: it holds one collection (a single-collection package) or several (a multi-collection package), and it has a name, a version and dependencies. The command raco is the front door to the tools.
raco pkg
raco pkg installs, updates and removes packages. A package source is a name looked up in a catalog (the default catalog lists the packages of the Racket package server), a GitHub or Git address, a local directory, or a file or URL that holds an archive. The kinds are chosen with --type: file, dir, file-url, dir-url, git, git-url, github or name; it is normally inferred.
| Command | Does |
|---|---|
raco pkg install SOURCE … | installs packages, with their dependencies as directed by --deps (fail, force, search-ask or search-auto; --auto means search-auto). With no source it links the current directory as a package (--link), and --clone checks out a Git source for editing |
raco pkg update PACKAGE … (--all, --update-deps) | updates installed packages to newer versions |
raco pkg uninstall PACKAGE … (also remove) | removes packages; those that others depend on are protected unless forced |
raco pkg show | lists the installed packages with their versions, sources and scopes |
raco pkg new NAME | makes a new package folder with a starter info.rkt |
raco pkg create SOURCE | bundles a package into an archive to publish; not needed for a package served from a Git repository. raco pkg archive DEST PKG … instead copies installed packages and a catalog describing them into a directory |
raco pkg migrate VERSION | installs the packages that another Racket version had |
raco pkg config, search, catalog-show, catalog-copy, catalog-archive, empty-trash | read and set configuration, search catalogs, and manage catalogs |
A package scope says whose installation changes: user (the default: the current user and this version of Racket), installation (all users of this installation), or a directory used as a scope. Packages that are installed only to satisfy another's dependency are auto-installed and removed with their last dependent by raco pkg uninstall --auto.
The info.rkt file
Each package and collection may have a file named info.rkt. It is a module in the language info (or setup/infotab), but a strongly restricted one: a sequence of (define id expression), where an expression is a quoted or quasiquoted datum, an if, a string, number, boolean or other defined name, or a call of one of these functions: cons car cdr list list* reverse append equal? string-append make-immutable-hash hash hash-set hash-set* hash-remove hash-clear hash-update path->string build-path collection-path system-library-subpath getenv. The tools read it without running the rest of the language, and getenv works only for variables named in PLT_INFO_ALLOW_VARS.
#lang info
(define collection "greeter")
(define version "1.2")
(define pkg-desc "Prints friendly greetings")
(define deps '("base" ("rackunit-lib" #:version "1.0")))
(define build-deps '("scribble-lib" "racket-doc"))
(define scribblings '(("scribblings/greeter.scrbl" ())))
(define test-omit-paths '("examples"))info.rkt for a package.| Field | Meaning |
|---|---|
collection | 'multi for a multi-collection package, or the collection's name as a string; 'use-pkg-name uses the package name |
version | a version string (default "0.0") |
deps, build-deps | packages needed to run, and (only) to build; each is a source string or a list with #:version (a lower bound) and #:platform (only for a matching platform) |
implies, update-implies, umbrella | packages that this one stands for, that are updated with it, and an umbrella package name |
setup-collects, language-families, license, distribution-preference, package-content-state, build-platforms | extra collections to set up, documentation language families, a license expression, how to distribute, content state and platforms to build for |
scribblings | the Scribble documents to build: a list of ("path.scrbl" (flags …) category …) |
test-omit-paths, test-include-paths, test-command-line-arguments, compile-omit-paths | what raco test skips or adds, the arguments to give a test file, and what raco make and raco setup leave out |
pkg-desc, pkg-authors, name, release-note-files | descriptive fields shown in catalogs and documentation (the first two come from the package metadata conventions; I read only the fields above in the Reference) |
The other raco commands
| Command | Does |
|---|---|
raco make FILE … | compiles modules and everything they require to compiled/NAME_rkt.zo and NAME_rkt.dep. Flags: -j n (parallel), -l path (a library path), -v and -vv (verbose), --disable-inline, --disable-constant, and --no-deps with -p and --no-prim for non-module files |
raco test PATH … | runs the test submodule of each file (-s name for another, -c for collections, -p for packages, -l for libraries); a directory is searched for files ending in .rkt, .scrbl, .ss, .scm; a test fails if it logs a failing result or exits non-zero |
raco exe FILE | makes a stand-alone executable that embeds the module and every module it requires into a copy of the runtime (--gui for the GUI variant, --lib to include a library that is loaded only dynamically). It does not make a program faster; a smaller language and raco make do |
raco distribute DIR EXE … | packages executables made by raco exe with the shared libraries and run-time files they need into a folder that works on another machine of the same system |
raco setup | builds collections, compiled files, documentation and indexes for an installation; run by raco pkg after changes |
raco demod, raco decompile, raco expand, raco read, raco link, raco docs, raco scribble, raco ctool, raco unpack, raco plt | flatten a program into one module, show compiled code, show a form after expansion or after reading, add a collection link, open documentation, render Scribble to HTML or PDF, compile C extension code, unpack and inspect .plt archives |
raco help lists the commands installed, and other packages can add more.
Where things go
- Compiled code:
compiled/NAME_rkt.zoand.depbeside each source, as File structure says. A compiled file is used only if it is not older than its source, unless told otherwise. The.zoholds a linklet bundle (a module with no submodules) or a linklet directory; in Racket CS the linklets inside are machine code and opaque to the bytecode libraries (compiler/zo-parse), which handle BC bytecode. The librarycompiler/zo-structswarns that its structures change across versions. - Packages: installed under the user's or installation's package folders, with the collections found through the links files that
raco pkgkeeps.(find-system-path 'addon-dir)and(find-system-path 'collects-dir)name the main places. - Documentation:
raco setupbuilds each package's Scribble documents into the HTML under the installation'sdocfolder, andraco docsopens it.
Not described
Known, not yet covered
- Reference: from the package manager's manual only the concepts, the
installsub-command's opening flags and the metadata section's first fields were read; the other sub-commands' flags, the catalog and server protocols, package conflicts and checksums, the names of the remaininginfo.rktfields (includingpkg-descandpkg-authors, named from memory), the PLaneT compatibility layer and the FAQ are not described. The collection-level fields ofinfo.rkt(thesetup-infochapter, 45 KB) were not read beyondscribblingsand the documentation settings. - Reference:
raco distribute,raco demod,raco decompile,raco ctool,raco linkand the other minor commands are named from the table of contents of the raco manual and not described. - Viewer: an
info.rktis shown as Racket; its restricted expressions get ordinary colouring and its field names are not marked.
See also
- Modules –
requireand collection paths - Scribble – the documents that
scribblingsnames - The standard library – what comes with Racket