AKKU

NAME

akku - R6RS/R7RS Scheme language package manager

SYNOPSIS

akku [--debug] [--trace] {init directory | list | show pkg | install pkg[@version-range]... | update | add [--dev] pkg[@version-range] | lock | install | remove pkg... | uninstall pkg... | version | scan [directory] | publish [--version=version] [--tag=tag] | graph [directory] | dependency-scan --implementation=impl filename... | license-scan --implementation=impl filename... | archive-scan directory... | compat-scan filename...}

DESCRIPTION

Akku.scm is a project-based language package manager for R6RS and R7RS Scheme. It is mainly meant for programmers who develop portable programs or libraries in Scheme, but could potentially work for end-users of those programs. It also has a translator from R7RS, which allows most R7RS code to run on R6RS implementations.

Being project-based means that dependencies are local to each project you manage with Akku. Each project specifies its dependencies through a manifest and a lockfile. When working on a project, you run akku install and then .akku/env to start a new shell with that project’s environment variables set. This ensures that the code you load into your program is that of your direct or indirect dependencies, instead of something that just happened to exist somewhere in your load path.

A project’s direct dependencies are listed in the manifest. By running a dependency solver, specific versions of those dependencies are locked. The lockfile contains locations, cryptographic checksums and other information needed for Akku to install selected versions of all dependencies. This means that everyone using the same lockfile will get exactly the same dependencies installed as you.

This manpage mostly describes the command line interface, where these commands are available:
init directory

Initialize a new project with a simple template that demonstrates a program, a library and a test. This is not necessary to start using Akku in an existing project. In that case you simply go to the root directory of the project and start running akku.

show pkg

Display details about a package in the local package index. The first few sections are for your information only. Any dependencies are listed together with a simplified version range in braces. The source code section shows all information that will be used to download the package when it is installed.

install pkg[@version-range]...

Running install with a list of packages will add them to the package manifest, lock dependencies and install everything in the lockfile.

install

Run this command to rebuild .akku/lib. Also run this command after adding new libraries to your project since they need to be symlinked into .akku/lib.

This command follows the instructions in the lockfile to download and install the listed dependencies. A file scanner looks at each file in the downloaded projects and figures out what type of source it is and where it goes in the file system.

The index files are signed with GnuPG signatures that are verified before they are used. The SHA-2 implementation is a little slow, so this takes a few seconds.

add [--dev] pkg[@version-range]

Adds a package to the manifest using a version range that allows forwards-compatible upgrades. Optionally the range can be specified manually using the pkg@version-range syntax, e.g. semver@ˆ1.0.0. It’s also possible to edit the manifest by hand, but formatting will not be preserved by these commands.

The range notation is provided by the semver package.

The --dev option adds the package as a development dependency. Development dependencies are ignored when the package is used as a dependency by a third package (they are only needed when doing development on the current package).

It is wise to commit both the manifest and the lockfile in your source code repository. Neither are used by your reverse dependencies after a package has been published, but both are useful for yourself and other people.

remove pkg...

Updates the package manifest to remove dependencies, doing the opposite of add.

uninstall pkg...

Does three things: removes dependencies from the manifest, locks dependencies and runs install to remove the files that are no longer needed.

version

Print the Akku.scm version number to standard output.

scan [directory]

Scans a directory recursively and analyses all files. The result of the analysis is printed as a series of YAML documents (syntax might be a bit off: send bug reports). Useful for figuring out what type of code Akku thinks the repository contains.

publish [--version=version] [--tag=tag]

Guides you through publishing your package. It generates a package index snippet and asks if you want to submit it. If you answer yes then it fires up gpg to sign the displayed snippet, which is then submitted to the archive server.

The version to publish is taken from the manifest but can be overridden by using the --version=version option. By default it looks for a tag named vversion. It is possible to override the tag using the --tag=tag option if the repository does not use the v1.2.3 tagging scheme. If it does not find a tag then the published revision will match the current HEAD.

It is always the lock section of the printed index snippet that controls which revision is used for the published version. It is also the currently checked out manifest that will be used to populate the metadata of the index snippet; not the manifest that happens to be checked in under the revision.

There is no strong requirement to commit the manifest before publishing. This means that you can also publish other people’s repositories, even if you do not have commit rights.

See section PUBLISHING PACKAGES below for a checklist of things to go through before publishing.

This command requires gpg, a gpg key and curl.

graph [directory]

Runs the repository analyser and prints a digraph of library dependencies. It’s kind of a proof of concept at this point. Example usage: akku graph | dot -Tx11.

dependency-scan --implementation=impl filename...

Traces the dependencies of a set of program source files. At least one implementation should be specified. They are named by the short names used in sls filenames, e.g. ikarus.

license-scan --implementation=impl filename...

Does the same dependency scanning as dependency-scan, but then searches through all files it finds to look for license notices and similar legal text. This command is useful as a first step in gathering notices when distributing a compiled Scheme program.

Some words are worth repeating here: this program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

archive-scan directory...

Scans the given directories for *.akku files and gathers them into a single index file. This is used at repository servers as part of maintaining the archive.

compat-scan filename...

Scans the given files for Scheme implementation compatibility. The files should be programs or libraries. All their imports are recursively checked for compatibility and missing libraries are printed.

PUBLISHING PACKAGES

You can make R6RS packages available to other users through the central Akku.scm registry with the publish command described above. If your package is written in R7RS then please publish to Snow instead so that your package will also be available in other R7RS package managers. Here is a checklist of items to consider before publishing:

All packages in the index are signed with GnuPG signatures. This provides important benefits: third parties can verify the package index and the archive software can verify that a newly uploaded version came from same author as previously uploaded versions. The email on your GnuPG key is used to contact you if there are any questions.

Packages are manually reviewed before they are accepted into the package index. Ask in #akku on Libera.Chat if there are problems.

Publishing is meant to be easy and hassle-free after some initial setup, so please report any usability problems with the publish command.

BUGS

Implementation-specific language constructs such as modules and lexical syntax are handled rather poorly.

The conversion of R7RS code is not complete. It does not add quotes to vectors, which are self-quoting in R7RS but not in R6RS. If the R7RS code uses shared data at the lexical level then the written R6RS library will also use that and may end up not being loadable by a conformant R6RS implementation. The R7RS support needs the akku-r7rs package to be installed.

The lock command (and any command that uses it behind the scenes) does not preserve the versions of previously locked packages. This is planned to be fixed.

The Cygwin and MSYS2 ports do not support colons in filenames. This has the unfortunate consequence that Chez Scheme and SRFI 97-compliant SRFI distributions do not work on these platforms. Symlinks are also not supported.

Whereas GNU Guile 3.0 has the --r6rs command line argument, GNU Guile 2.2 does not provide a direct way to enable full R6RS support. It should be started with the flags -x .guile.sls -x .sls on the command line. Alternatively you can add these lines to your ˜/.guile:

(set! %load-extensions (append '(".guile.sls" ".sls")
%load-extensions))
(read-enable 'r6rs-hex-escapes)
(read-enable 'hungry-eol-escapes)

Please report bugs to GitLab issues or by email.

EXAMPLES

Updating the local package index

Right after installation and before doing anything else, it’s a good idea to update the local package index:

$ akku update

Quick start in a new project

A quick way to get a new project up and running is the init command:

$ akku init my-project
$ cd my-project
$ akku install
$ .akku/env

Use akku list to find some package you want to use, or browse the package list on the Akku website. When you want to install a package, e.g. json-tools, run akku install json-tools. This adds it to the package manifest, locks all dependencies to specific versions and rewrites .akku/ to the locked versions.

Install dependencies step-by-step

Dependencies can be installed step-by-step in order to follow the process:

$ akku add chez-srfi # writes Akku.manifest
$ akku lock # writes Akku.lock
$ akku install # updates .akku/

ENVIRONMENT

The AKKU_SETTINGS variable can contain these settings:

copy-current-project copy (do not symlink) the current project

FILES

AUTHOR

Written by G. Weinholt.

Thanks to everyone who has contributed to Scheme over the years.

HISTORY

The dependency solver comes from Andreas Rottmann’s dorodango, an earlier R6RS package manager, and he ported it from the solver in aptitude(8).

COPYRIGHT

Copyright © 2023 G. Weinholt. License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

SEE ALSO

The project website: https://akkuscm.org/
The project wiki: https://gitlab.com/akkuscm/akku/wikis/home