AKKU

NAME
SYNOPSIS
DESCRIPTION
PUBLISHING PACKAGES
BUGS
EXAMPLES
ENVIRONMENT
FILES
AUTHOR
HISTORY
COPYRIGHT
SEE ALSO

NAME

akku - R6RS Scheme language package manager

SYNOPSIS

akku {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 | dependency-scan [--implementation=impl] filename... | license-scan [--implementation=impl] filename... | archive-scan directory...}

DESCRIPTION

Akku.scm is a project-based language package manager for R6RS Scheme. It is mainly meant for schemers who develop programs or libraries in R6RS Scheme, but could potentially work for end-users of those programs.

Being project-based means that dependencies are local to each project you manage with Akku. The idea is that each project will specify its dependencies through a manifest and a lockfile. When developing on a project, you set your environment variables by sourcing that project’s activate script into your shell (source .akku/bin/activate). 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. This means that others who also use your lockfile will get exactly the same dependencies installed as you had while developing.

This manpage mostly goes over the details of the command line interface, where these command 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.

list

List the local package index. For each package in the index it shows the name (used in command line arguments), the version and a short synopsis. When used in the project directory it will read the manifest and the lockfile and use that information to highlight versions that match the dependencies.

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

This command follows the instructions in the lockfile to download and install the listed projects. 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.

This command requires git.

update

Updates the local package index. The index files are signed with GnuPG signatures that are verified before they are used.

This command requires libcurl.

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 --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).

lock

Locks dependencies. Runs a dependency solver over the manifest and the local package index and generates the lockfile. The lockfile contains the location of each transitive dependency together with a cryptographic identity.

It is wise to commit both the manifest and the lockfile in your source code repository; the lockfile is not used when your package is pulled in as a dependency.

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. If there is no manifest then it first creates a draft that you will need to edit. Otherwise it generates a package index snippet and asks if you want to submit it. Have a careful look. If you answer yes then it fires up gpg to sign the displayed snippet and then it submits the signed snippet to the 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 will dictate which revision of your code is associated with the version you’re publishing.

Note that no matter which revision is published, it is the currently checked out manifest that will be used to populate the metadata of the index snippet.

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

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 library of program source files.

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.

PUBLISHING PACKAGES

You can make packages available to other users through the central Akku.scm registry with the publish command described above. Here is a checklist of items to consider before publishing:

1.

Check that your manifest is up to date and contains at least the right package name, version, synopsis, at least one author and a license identifier. If you don’t have a manifest yet, then run akku publish to get a draft.

2.

Version numbers must follow the SemVer specification. If you are packaging software that does not follow the SemVer rules then adjust the version numbers so that they follow the rules (they don’t need to match the original software exactly).

3.

Please pay some attention to the license field to make sure that it is accurate. Use the identifiers from the SPDX project, making sure to use an open source license.

4.

Prepare and publish your GnuPG key if you do not yet have one. If you’re not too particular on the details of this and just want a key that works then you can run gpg --quick-generate-key "Name Goes Here <schemer@example.com>", filling in the name and email address that you want to use. Afterwards you need to publish your key to the public key servers using the command gpg --keyserver pgp.mit.edu --send-keys keyID, using the key ID associated with your new key.

5.

Currently all projects need to be in a publicly available git repository, but this will change later. The release should preferably be tagged using their SemVer version numbers: version 1.0.0 gets tagged with v1.0.0. You can use git tag -s v1.0.0 to make a signed tag (and don’t forget to use git push --tags).

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.

Packages are manually reviewed before they are accepted into the package index. Ask in #akku on Freenode 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.

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
$ source .akku/bin/activate

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

AKKU_HOME override the application home directory

AKKU_LOG_LEVEL

log level: trace, debug, info, warning, error, critical

HOME

user’s home directory

FILES

~/.akku/

default Akku.scm home directory

~/.akku/bin/

akku binary and supporting programs

~/.akku/boot/

Chez Scheme boot files

~/.akku/share/bootstrap.db

the package index from the distribution

~/.akku/share/index.db

the local package index

~/.akku/share/keys.d/*

trusted keys for the package index

~/.cache/akku/*

cached downloads

Akku.manifest

the package manifest

Akku.lock

instructions for installing dependencies

.akku/bin/

programs from packages; activate script

.akku/lib/

installed libraries from packages

.akku/ffi/

compiled libraries for use with an FFI

.akku/list

a list of files and whence they came

.akku/notices/

license notices from installed packages

.akku/src/

downloaded source code

AUTHOR

Written by Göran Weinholt.

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

HISTORY

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

COPYRIGHT

Copyright © 2018 Göran 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