3 Tutorial
3.1 Warning
In addition to this tutorial, the document assumes that the user has read the official tutorial on creating packages.
This tutorial uses the JSON format. I want to inform the user, that Req also supports the RKTD format that would probably please Symbolic-Expression lovers (which most users of Racket probably are) more than JSON.
3.2 Project setup
Let’s assume we are creating a package "mypkg".
We want to cut it into smaller packages so the users can install only the library, only the docs and/or only the tests, thus our project repository will contain:
mypkg-lib - core library,
mypkg-test - package containg tests,
mypkg-doc - project documentation,
mypkg - metapackage depending on the other 3 packages above.
Let’s put those packages into directory "src" in the project’s root and let’s create adequate "info.rkt" and source files. The structure of the project could look simialr to the following:
└── src/
├── mypkg/
│ └── info.rkt
├── mypkg-doc/
│ ├── info.rkt
│ └── mypkg/
│ └── scribblings/
│ └── main.scrbl
├── mypkg-lib/
│ ├── info.rkt
│ └── mypkg/
│ └── main.rkt
└── mypkg-test/
├── info.rkt
└── mypkg/
└── tests/
├── integration/
│ └── integration-test.rkt
└── unit/
└── unit-test.rkt
Normally if we would install a package from this project we would have to invoke a rather long, forgettable raco command which would have to be typed for each local package, for example: raco pkg install --no-docs --skip-installed ./src/mypkg-lib.
Req can bring a little bit of automation into the installation process. With Req all of project’s packages can be installed with one command.
First, create a "req.json" file at the project’s root.
├── req.json
└── src/
├── mypkg/
├── mypkg-doc/
├── mypkg-lib/
└── mypkg-test/
Then, fill it with adequate data:
project packages root is in src, so the "root" key will hold a "src" string,
all of the packages begin with "mypkg", so we can glob them using a "mypkg*" string, thus the "local" key (which lists projects’s own packages) will hold (list "mypkg*"),
Thus, a basic Req file setup for our imaginary project will look like the following:
{
"root": "src",
"local": [
"mypkg*"
]
}
3.3 The raco req command
After the project is set up we can invoke the raco req command.
We can check the information of the project using the raco req -s comamnd.
catalogs:
local:
- mypkg-test ✗
/tmp/racket-mypkg/src/mypkg-test
- mypkg-lib ✗
/tmp/racket-mypkg/src/mypkg-lib
- mypkg ✗
/tmp/racket-mypkg/src/mypkg
- mypkg-doc ✗
/tmp/racket-mypkg/src/mypkg-doc
dependencies:
- base ✓
- racket-doc ✓
- rackunit-lib ✓
- scribble-lib ✓
extras:
We can install all (not yet installed) dependencies and local packages with raco req -A.
If we would invoke the above command again we should see Req informing us that all required packages are installed.
Package "racket-doc" already installed in "/usr/share/racket/pkgs/racket-doc".
Package "scribble-lib" already installed in "/usr/share/racket/pkgs/scribble-lib".
Package "rackunit-lib" already installed in "/usr/share/racket/pkgs/rackunit-lib".
Package "base" already installed in "/usr/share/racket/pkgs/base".
Package "mypkg-test" already installed in "/tmp/racket-mypkg/src/mypkg-test".
Package "mypkg-lib" already installed in "/tmp/racket-mypkg/src/mypkg-lib".
Package "req" already installed in "/tmp/racket-mypkg/src/mypkg".
Package "mypkg-doc" already installed in "/tmp/racket-mypkg/src/mypkg-doc".
3.4 Further reading
For more information about supported keys see req-supported-formats-keys.
For more information about supported formats see req-supported-formats.
For more information about supported command-line options see req-cli.