qi

qi copied to clipboard

• Qi - Package Manager for Common Lisp

Qi is a package manager for Common Lisp.

** 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 [[http://codyreichert.github.io/qi/][here]].

** Dependencies

• [[http://pyyaml.org/wiki/LibYAML][libyaml]]
• [[https://www.openssl.org][OpenSSL]]

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

** Installation

1. Clone Qi anywhere:

   #+BEGIN_SRC sh git clone https://github.com/CodyReichert/qi.git #+END_SRC

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

   #+BEGIN_SRC lisp (load "path/to/qi") #+END_SRC

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

#+BEGIN_SRC lisp CL-USER> (qi:hello) #+END_SRC

See [[https://github.com/CodyReichert/qi/blob/master/docs/TODO.org][docs/TODO.org]] and =bin/= for some work that can/should be done around this part.

** Usage

*** 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 [[https://github.com/codyreichert/qi][Qi's qi.yaml]].

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

#+BEGIN_SRC yaml
  name: my-project
  packages:
    - name: zlib
      branch: import-1.1.1

    - name: clack
      url: https://github.com/fukamachi/clack/archive/master.tar.gz

    - name: postmodern
      url: https://github.com/marijnh/Postmodern.git
      tag: v1.19
#+END_SRC

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

• Manifest: "Known" packages from the [[https://github.com/CodyReichert/qi-manifest/blob/master/manifest.lisp][Qi manifest]].
• Tarball: An HTTP URL to tarball.
• Git: A git repository.
• Mercurial: A link to a mercurial repository.

For manifest and git packages, you can optionally specify a tag, revision, or branch.

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

#+BEGIN_SRC lisp * (load "myproject.asd") * (qi:install :myproject) #+END_SRC

=qi:install= will also load the dependencies into the system for you, using ASDF. If you don't want Qi as a runtime dependency of your application, you can alternatively add something like this to your =.asd= file:

#+BEGIN_SRC lisp (asdf:initialize-source-registry `(:source-registry :ignore-inherited-configuration (:tree (:here ".dependencies/packages/")))) #+END_SRC

In addition to =qi:install=, you can also install project dependencies from the command-line:

#+BEGIN_SRC sh qi --install path/to/qi.yaml # the path is unnecessary if qi.yaml is in the working directory #+END_SRC

Qi takes 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=.

*** 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

#+BEGIN_SRC lisp * (qi:install-global :cl-project) #+END_SRC

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

**** up

#+BEGIN_SRC lisp * (qi:up :cl-project) #+END_SRC

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

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

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

#+BEGIN_SRC lisp (qi:hello) #+END_SRC

*** Install Installs a system and it's dependencies. All dependencies are installed local to the project's =.dependencies/= directory.

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

#+BEGIN_SRC lisp (qi:install :system) #+END_SRC

*** Install Global Installs a system to the global package directory =share/qi/packages=. The system should be from the Manifest. The system is made available in the current session.

#+BEGIN_SRC lisp (qi:install-global :system &optional version) #+END_SRC

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

*** Up Have ASDF load a system to be available in the current session.

#+BEGIN_SRC lisp (qi:up :system) #+END_SRC

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

*** 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:publish ...)=

Publish a new package to the Qi Manifest

** Manifest The [[https://github.com/CodyReichert/qi-manifest/blob/master/manifest.lisp][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 [[https://github.com/quicklisp/quicklisp-projects/][Quicklisp's projects]] which means that any project you can find in Quicklisp can be found in Qi.

*** 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-manifest, or send a patch file to
[email protected].

See [[https://github.com/CodyReichert/qi/blob/master/docs/TODO.org][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.

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

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

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

Usage: qi [-h|--help] [-u|--upgrade] [-m|--update-manifest] [-i|--install] [Free-Args]

Available options: -h, --help Print this help menu. -u, --upgrade Upgrade Qi (pull the latest from git) -m, --update-manifest Update the Qi manifest -i, --install Install packages, named on the command-line or specified in qi.yaml If named on the command-line, packages will be installed globally into the Qi shared packages directory.

                            If specified in a qi.yaml file, packages will be
                            installed into the local project's .dependencies
                            directory.

Issues https://github.com/CodyReichert/qi #+END_SRC

** Contributing PRs and Issues are extremely welcomed and will likely all be merged or addressed. See the [[https://github.com/CodyReichert/qi/blob/master/docs/TODO.org][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.

If you can, add new tests to cover the changes you make! You can run tests locally with Roswell (=run-prove=) or with =make t=:

#+BEGIN_SRC sh bin/qi -i prove make t #+END_SRC

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

** Contributors

• Cody Reichert ([email protected])
• Nicolas Lamirault (@nlamirault)
• Alex Dunn (@dunn)

** Copyright Copyright (c) 2015 Cody Reichert ([email protected])

** License BSD