(Qi) | A simple, open, free Package Manager for Common Lisp

1. Qi - Package Manager for Common Lisp

1 Qi - Package Manager for Common Lisp

Qi is a package manager for Common Lisp. There are several goals, at the top of which are: pinned dependency versions, project local dependencies, a place where anyone can upload their library for others to use. A CLI, project scaffolding, and bringing the wonderful world of Common Lisp libraries to anyone with one command are the more long-term goals.

The State of Qi

Qi is a new project. There are still bugs. There are still missing features. It might not work sometimes. It has not been tested on multiple Lisp implementations (only SBCL). Pull-requests, issues, feedback are appreciated.

View the HTML version of this documentation here.

1.1 Dependencies

Qi has a few Common Lisp dependencies, but they are all bundled with the repository to allow Qi to bootstrap itself (see qi/dependencies for a full list).

1.2 Installation

Clone Qi anywhere:

git clone https://github.com/CodyReichert/qi.git

Load Qi when SBCL starts by adding these lines to your .sbclrc:

(load "path/to/qi")

To test if Qi is installed correctly, run the following the a REPL:

CL-USER> (qi:hello)

Notes:

See docs/TODO.org and bin/ for some work that can/should be done around this part.

1.3 Usage

1.3.1 Using Qi for a project

This section covers using Qi for a single project.

The only requirement to installing a systems dependencies with Qi, is a qi.yaml.

The qi.yaml specifies a projects dependencies. For an example of what this looks like, checkout out Qi's qi.yaml.

Two required pieces to the qi.yaml are name and packages. So a basic project would look like this:

name: my-project
packages:
  - name: alexandria
  - name: clack
    url: https://github.com/fukamachi/clack/archive/master.tar.gz
  - name: cl-pass
    url: https://github.com/eudoxia0/cl-pass.git

Above there are three types of packages: Manifest, tarball, and git.

Manifest: "Known" packages from the Qi manifest.
Tarball: An HTTP URL to tarball.
Git: A git repository. You can also specify a tag or hash.
Mercurial: A link to a mercurial repository.
Local: TODO, but you will be able to put a local path.

With the above qi.yaml in your project, you can run the following to install and load the systems:

* (load "myproject.asd")
* (qi:install :myproject)

You can also install project dependencies from the command-line:

qi --install-deps path/to/myproject.asd

Qi take's care of any transitive dependencies and will let you know of any that it could not install. In a case where Qi can not install some dependencies, add direct links to those packages in your qi.yaml.

1.3.2 Using Qi for global packages

You can also manage global packages with Qi. This is useful for downloading and install packages that you want to always have available. There's a simple interface, and two commands are the most useful:

install-global

* (qi:install-global :cl-project)

Running install-global installs the package into the global package directory (qi/dependencies). The installed package is made available in the current session.

* (qi:up :cl-project)

Running up loads a package that's in your global package directory and makes it available in the current session.

1.4 API

Qi's API is composed of a few commands, documented below:

1.4.1 Hello

Prints some information about Qi to standard-output. If this prints, Qi is installed correctly.

(qi:hello)

1.4.2 Install

Installs a system and it's dependencies. All dependencies are installed local to the system directory in .dependencies/.

For any dependencies that are not already available, Qi will try to download them from the Manifest. If all else fails, it will print to standard-output what packages could not be installed.

(qi:install :system)

1.4.3 Install Global

Installs a system to the global package directory. The system should be from the Manifest. The system is made available in the current session.

(qi:install-global :system &optional version)

To make a global system available at any time, you can use (qi:up :system)

1.4.4 Up

ASDF load's a system to be available in the current session.

(qi:up :system)

This is the equivalent of running (asdf:load-system :system)

1.4.5 Coming Soon

Not implemented (qi:new ...)

Generate a new project scaffold.

Not implemented (qi:setup ...)

Generate a qi.yaml for an existing project.

Not implemented (qi:update-manifest ...)

Update the Qi manifest to get access to new packages and updates.

Not implemented (qi:publish ...)

Publish a new package to the Qi Manifest

1.5 Manifest

The Qi Manifest is a list of known packages - which makes it easy to simply install packages by their name. Qi's Manifest was initially seeded by Quicklisp's projects which means that any project you can find in Quicklisp can be found in Qi.

1.5.1 Adding a package to the Qi Manifest

Any and all packages are welcome in the Qi Manifest. The only requirement is that it is a lisp project that is asdf-loadable.

To add a package to the manifest, submit a pull-request at https://github.com/CodyReichert/qi/, or send a patch file to codyreichert@gmail.com.

See docs/TODO.org for some work to be done in this area. Ideally, we have recipes/ that contains the information about each Qi package. That way a new recipe can be added and the Manifest can be updated.

1.6 CLI

The Qi CLI provides a few basic commands (more coming soon!). Make sure that qi/bin/ is in your path, or move qi/bin/qi into your path.

Run $ qi --help For info on the available commands:

λ qi -h
Qi - A simple, open, free package manager for Common Lisp.

Usage: qi [-h|--help] [-u|--upgrade] [-i|--install PACKAGE] [-d|--install-deps ASD-FILE] [Free-Args]

Available options:
  -h, --help                   Print this help menu.
  -u, --upgrade                Upgrade Qi (pull the latest from git)
  -i, --install PACKAGE        Install a package from Qi (global by default)
  -d, --install-deps ASD-FILE  Install dependencies locally for the specified system

Issues https://github.com/CodyReichert/qi

1.7 Contributing

PRs and Issues are extremely welcomed and will likely all be merged or addressed. See the docs/TODO.org for a list of tasks that I'd like to see done. Make a PR or start a conversation if there's anything you'd like to see.

With any PR - add your name to the Contributors section below.

1.8 Contributors

Cody Reichert (codyreichert@gmail.com)
Nicolas Lamirault (@nlamirault)
Alex Dunn (@dunn)

1.9 Copyright

1.10 License

BSD

Created: 2016-12-10 Sat 14:30

Validate

Table of Contents