dylan tool provides a number of subcommands to simplify the management
of Dylan workspaces and packages, eliminates the need to manually maintain the
“registry” (which enables the compiler to locate libraries) by hand, and
eliminates the need to use git submodules to track dependencies.
A blob of files that can be unpacked into a directory and which has a
dylan-package.jsonfile in the top-level directory which describes its attributes. A package currently corresponds to a single Git repository. A package has a set of versioned releases.
A directory containing a
dylancommands may be run from anywhere within the workspace directory.
- active package
A package checked out into the top-level of a workspace. Active packages are found by looking for
updatesubcommand scans active packages when creating the registry.
A specific version of a package. A release has a Semantic Version associated with it, such as
To find and install packages on the local file system many of the
subcommands use the
DYLAN environment variable. If
$HOME/dylan is used instead. (Much of this documentation is written
to assume that
DYLAN is set, but it is not required.)
git is on your
PATH so it can be found by the package
manager, which currently exec’s
git clone to install packages. (This
dependency will be removed in a future release.)
dylan tool installs packages, including the pacman-catalog package
which describes where to find other packages, under
Don’t put files you want to keep into the
$DYLAN/pkg/ directory. The
expectation should be that anything in this directory may be deleted at any
time by the package manager.
In an upcoming release of Open Dylan, the
dylan tool will be included in the
release. For now, follow these steps to build and install.
Because an executable named “dylan” conflicts with the base Dylan
library during the build process, this library is named
then the executable is installed as
dylan by the
examples in this document use the name
dylan instead of
Read the Requirements section, above.
Make sure you have
Clone and build the
$ git clone --recursive https://github.com/dylan-lang/dylan-tool.git $ cd dylan-tool $ make test $ make install
Make sure that
$DYLAN/binis on your
$PATH. If you prefer not to set
$DYLAN, make sure that
$HOME/dylan/binis on your
You should now be able to run the Hello World example, below.
To make sure everything is working correctly, and to get a quick sense of
what’s available, start by running the
dylan help command.
To fully test your installation, try creating a temp workspace and updating
it. Here’s an example using the
logging library as an “active package” in
$ cd /tmp $ dylan new workspace log $ cd log $ git clone --recursive https://github.com/dylan-lang/logging $ dylan update $ dylan-compiler -build logging-test-suite # optional $ _build/bin/logging-test-suite # optional
You should see a lot of output from the
dylan update command. If you run
the last two steps to build the
logging-test-suite library you will see a
bunch of compiler warnings for the core Dylan library, which may be ignored.
dylan tool relies on pacman, the Dylan package manager
(unrelated to the Arch Linux tool by the same name), to install
dependencies. See the pacman documentation for information on
how to define a package, version syntax, and how dependency resolution works.
Note that global command line options must be specified between “dylan” and the
first subcommand name. Example:
dylan --debug new library --exe my-lib
Disables error handling so that when an error occurs the debugger will be entered, or if not running under a debugger a stack trace will be printed.
Enables debug logging to standard error. Each line is preceded by a single letter indicating the type of message: I: info, D: debug, W: warning, E: error, T: trace
Displays overall help or help for a specific subcommand.
dylan help <subcommand> [<sub-subcommand> ...]
dylan <subcommand> [<sub-subcommand> ...] --help
Install a package into the package cache,
dylan install <package> [<package> ...]
This command may be removed. It was mainly useful during early development.
Generate the boilerplate for a new library.
dylan new library [options] <library-name> [<dependency> ...]
Specifying dependencies is optional. They should be in the same form as
specified in the
This command generates the following code:
A main library and module definition and initial source files
A corresponding test suite library and initial source files
make-dylan-app binary included with Open Dylan, this command
does not generate a “registry” directory. Instead, it is expected that you will
dylan update to generate the registry.
Create an executable library. The primary difference is that with this flag a
mainfunction is generated and called.
Here’s an example of creating an executable named “killer-app” which depends on http version 1.0 and the latest version of logging. It assumes you are in the top-level directory of a Dylan workspace.
$ dylan new library --exe killer-app firstname.lastname@example.org logging $ dylan update # generate registry files, assumes in a workspace $ dylan-compiler -build killer-app-test-suite $ _build/bin/killer-app-test-suite
You should edit the generated
dylan-package.json file to set the repository
URL and description for your package, or if this library is part of an existing
package you can just delete
Create a new workspace.
dylan new workspace [options] <workspace-name>
Create the workspace under this directory instead of in the current working directory.
new workspace command creates a new workspace directory and initializes
it with a
workspace.json file. The workspace name is the only required
$ dylan new workspace http $ cd http $ ls -l total 8 -rw-r--r-- 1 you you 28 Dec 29 18:03 workspace.json
Clone repositories in the top-level workspace directory to create active packages, then run dylan update.
publish command adds a new release of a package to the package catalog.
dylan publish <package-name>
For now, until a fully automated solution is implemented, it works by modifying the local copy of the catalog so that you can manually run the pacman-catalog tests and submit a pull request. This eliminates a lot of possibilities for making mistakes while editing the catalog by hand.
This command may (as usual) be run from anywhere inside a workspace. Once you’re satisfied that you’re ready to release a new version of your package (tests pass, doc updated, etc.) follow these steps:
dylan-package.jsonto be the new release’s version, and commit the change.
Make a new release on GitHub with a tag that matches the release version. For example, if the
"0.5.0"the GitHub release should be tagged
dylan publish my-package. (If pacman-catalog isn’t already an active package in your workspace the command will abort and give you instructions how to fix it.)
Commit the changes to pacman-catalog and submit a pull request. The tests to verify the catalog will be run automatically by the GitHub CI.
Once your PR has been merged, verify that the package is available in the catalog by running
dylan install email@example.com, substituting your new release name and version.
Display the status of the current workspace.
Only show the workspace directory and skip showing the active packages. This is intended for use by tooling.
$ dylan status Workspace: /home/cgay/dylan/workspaces/dt/ Active packages: http : ## master...origin/master (dirty) dylan-tool : ## dev...master [ahead 2] (dirty) pacman-catalog : ## publish...master [ahead 1] (dirty)
Update the workspace based on the current set of active packages.
update command may be run from anywhere inside a workspace directory
and performs two actions:
Installs all active package dependencies, as specified in their
Updates the registry to have an entry for each library in the workspace’s active packages or their dependencies.
registrydirectory is created at the same level as the
workspace.jsonfile and all registry files are written to a subdirectory named after the local platform.
If a dependency is also an active package in this workspace, the active package is preferred over the specific version listed as a dependency.
Registry files are only created if they apply to the architecture of the local machine. For example, on
x86_64-linuxLID files that specify
Platforms: win32will not cause a registry file to be generated.
Create a workspace named
http, with one active package,
it, and build the test suite:
$ dylan new workspace http $ cd http $ git clone --recursive https://github.com/dylan-lang/http $ dylan update $ dylan-compiler -build http-server-test-suite
dylan-compiler must always be invoked in the workspace directory
so that it can find the
registry directory. (This will be easier when the
dylan build command is implemented since it will ensure the compiler is
invoked in the right environment.)