The qlot Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The qlot Reference Manual

This is the qlot Reference Manual, version 0.9.0, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:27:16 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Qlot

Build Status

Qlot (pronounced kyü-'lät, like culotte) is a project-local library installer using Quicklisp facility. This aims to be like Bundler of Ruby or Carton of Perl.

Warning: This software is still BETA quality. The APIs will be likely to change.

Usage

# "qlfile" of "myapp"
git clack https://github.com/fukamachi/clack.git
github datafly fukamachi/datafly :branch v0.7.x
ql log4cl 2014-03-17
$ cd /path/to/myapp

# Installing libraries project-locally.
$ qlot install

# Updating depending libraries of a project.
$ qlot update

# Execute a command with a project-local Quicklisp
$ qlot exec ros -S . run
$ qlot exec clackup app.lisp

What Qlot is trying to solve

We have Quicklisp, the central library registry. It made installation of libraries damn easy.

However, what only you can specify is the month of distribution. Which means you have to use all libraries of the same moment and you cannot use a newer/older version of a library for your project.

"local-projects/" or ASDF configurations may be a solution to this problem, but there are a couple of problems.

  1. They are not project-local. If you have multiple projects that use the different version of the same library, it would be a problem.

  2. They are difficult to fix the version or to update them. If your project need to work on other than your machine, for instance on other people's machine or on servers, the version of depending libraries should be the same.

This is what Qlot is trying to solve.

Installation

via Roswell

It also can be installed with Roswell.

$ ros install qlot

# Install the latest version from GitHub
$ ros install fukamachi/qlot

It's almost the same as using Quicklisp, except it also introduces a shell command "qlot".

$ which qlot
/Users/nitro_idiot/.roswell/bin/qlot
$ qlot
Usage: qlot [install | update | bundle | exec shell-args..]

Tutorial

Adding "qlfile"

Put a file "qlfile" at the root of your project directory.

See qlfile syntax section to know how to write it.

Installation of libraries

You can install libraries into the project directory via:

$ qlot install

It creates quicklisp/ directory in the project directory and a file qlfile.lock.

qlfile.lock is similar to qlfile except the library versions are qualified. This will ensure that other developers or your deployment environment use exactly the same versions of libraries you just installed.

Make sure you add qlfile and qlfile.lock to your version controlled repository and make the quicklisp/ directory ignored.

$ echo quicklisp/ >> .gitignore
$ git add qlfile qlfile.lock
$ git commit -m 'Start using Qlot.'

Updating the project-local quicklisp

You can update the content of quicklisp/ directory via:

$ qlot update

It will also overwrite qlfile.lock.

Bundling libraries

You can bundle all depending libraries into bundle-libs/ via:

$ qlot bundle
$ git add bundle-libs/
$ git commit -m 'Bundle dependencies.'

Commands

install

qlot install will install Quicklisp and libraries that declared in qlfile project-locally. qlfile.lock will be used with precedence if it exists.

$ qlot install
$ qlot install /path/to/myapp/qlfile

update

qlot update will update the project-local quicklisp/ directory using qlfile.

$ qlot update

bundle

qlot bundle will bundle dependencies into bundle-libs/ by using ql:bundle-systems.

$ qlot bundle

qlfile syntax

"qlfile" is a collection of Quicklisp dist declarations. Each line of that represents a dist.

<source> <project name> [arg1, arg2..]

Currently, <source> must be one of ql, http, git or github.

ql

ql <project name> <version>
ql <project name> :latest
ql :all <version>

ql source will download libraries from Quicklisp official dist, but you can specify the version.

If you want to use Clack in Quicklisp dist of January 13, 2014, qlfile would be like this.

ql clack 2014-01-13

ql source also allows :all as <dist name> and :latest as the version.

ql :all 2014-01-13
ql clack :latest

http

http <project name> <url> [<file md5>]

http source will download a tarball.

http yason http://netzhansa.com/yason.tar.gz

git

git <project name> <repos url>
git <project name> <repos url> :ref <commit ref>
git <project name> <repos url> :branch <branch name>
git <project name> <repos url> :tag <tag name>

git source will download libraries from a public git repository.

git clack https://github.com/fukamachi/clack.git

You can also specify :ref, :branch or :tag.

git clack https://github.com/fukamachi/clack.git :branch develop
git datafly https://github.com/fukamachi/datafly.git :tag v0.7.4
git cl-dbi https://github.com/fukamachi/cl-dbi.git :ref 54928984e5756e92ba298aae51de8b95a6b0cf4b

Retrieving from private repository

Qlot doesn't authenticate itself, but retrieving from private repository can be done via git's SSH key authentication. Which means, if the current user can git clone, Qlot also would be possible to do it.

git myapp git@github.com:somewrite-adtech/myapp

github

github <project name> <repos>
github <project name> <repos> :ref <commit ref>
github <project name> <repos> :branch <branch name>
github <project name> <repos> :tag <tag name>

github source is similar to git, but it is specifically for GitHub. As it uses GitHub API and tarballs GitHub serves, it doesn't require "git" command.

github datafly fukamachi/datafly
github datafly fukamachi/datafly :branch develop

Priorities of distributions

If multiple distributions provide the same library, lower one would take priority over higher ones.

Working with SLIME

SLIME is the most popular development environment in Common Lisp. However, its REPL always loads the global Quicklisp, not the project-local one.

Here's quick steps to start project-local REPL with SLIME:

  1. Add the following function to init.el.
(defun slime-qlot-exec (directory)
  (interactive (list (read-directory-name "Project directory: ")))
  (slime-start :program "qlot"
               :program-args '("exec" "ros" "-S" "." "run")
               :directory directory
               :name 'qlot
               :env (list (concat "PATH="
                                  (mapconcat 'identity exec-path ":"))
                          (concat "QUICKLISP_HOME="
                                  (file-name-as-directory directory) "quicklisp/"))))
  1. Relaunch the Emacs.
  2. Invoke M-x slime-qlot-exec RET /path/to/project/.

Author

Copyright

Copyright (c) 2014 Eitaro Fukamachi (e.arrows@gmail.com)

License

Licensed under the MIT License


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Next: , Previous: , Up: Systems   [Contents][Index]

2.1 qlot

Author

Eitaro Fukamachi

License

MIT

Description

A project-local library installer

Version

0.9.0

Dependency

qlot/main (system)

Source

qlot.asd (file)


Next: , Previous: , Up: Systems   [Contents][Index]

2.2 qlot/main

Dependency

qlot/util (system)

Source

qlot.asd (file)

Component

lisp.lisp (file)


Previous: , Up: Systems   [Contents][Index]

2.3 qlot/util

Source

qlot.asd (file)

Component

lisp.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 qlot.asd

Location

qlot.asd

Systems

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 qlot/main/lisp.lisp

Parent

qlot/main (system)

Location

main.lisp

Packages

qlot

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.3 qlot/util/lisp.lisp

Parent

qlot/util (system)

Location

util.lisp

Packages

qlot/util

Exported Definitions
Internal Definitions

merge-hash-tables (function)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 qlot

Source

lisp.lisp (file)

Nickname

qlot/main

Use List

common-lisp

Exported Definitions
Internal Definitions

Previous: , Up: Packages   [Contents][Index]

4.2 qlot/util

Source

lisp.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

merge-hash-tables (function)


Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *system-quicklisp-home*
Package

qlot/util

Source

lisp.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: with-in-directory DIR &body BODY
Package

qlot/util

Source

lisp.lisp (file)

Macro: with-local-quicklisp (QLHOME &key SYSTEMS CENTRAL-REGISTRY) &body BODY
Package

qlot/util

Source

lisp.lisp (file)

Macro: with-package-functions PACKAGE-DESIGNATOR FUNCTIONS &body BODY
Package

qlot/util

Source

lisp.lisp (file)

Macro: with-quicklisp-home QLHOME &body BODY
Package

qlot/util

Source

lisp.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: all-required-systems SYSTEMS
Package

qlot/util

Source

lisp.lisp (file)

Function: bundle &optional PROJECT-DIR
Package

qlot

Source

lisp.lisp (file)

Function: call-in-local-quicklisp FN QLHOME &key SYSTEMS CENTRAL-REGISTRY
Package

qlot/util

Source

lisp.lisp (file)

Function: find-qlfile DIRECTORY &key ERRORP USE-LOCK
Package

qlot/util

Source

lisp.lisp (file)

Function: generate-random-string ()
Package

qlot/util

Source

lisp.lisp (file)

Function: install &rest ARGS

Install Quicklisp and libraries that declared in qlfile project-locally. qlfile.lock will be used with precedence if it exists.

Package

qlot

Source

lisp.lisp (file)

Function: install-quicklisp &optional PATH

Install Quicklisp in the given PATH.
If PATH isn’t specified, this installs it to ’./quicklisp/’.

Package

qlot

Source

lisp.lisp (file)

Function: pathname-in-directory-p PATH DIRECTORY
Package

qlot/util

Source

lisp.lisp (file)

Function: project-systems PROJECT-DIR
Package

qlot/util

Source

lisp.lisp (file)

Function: quickload SYSTEMS &rest ARGS &key VERBOSE PROMPT EXPLAIN &allow-other-keys

Load SYSTEMS in the each project-local ‘quicklisp/‘.

Package

qlot

Source

lisp.lisp (file)

Function: sbcl-contrib-p NAME
Package

qlot/util

Source

lisp.lisp (file)

Function: update &rest ARGS

Update the project-local ’quicklisp/’ directory using qlfile.

Package

qlot

Source

lisp.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: ensure-qlot-install ()
Package

qlot

Source

lisp.lisp (file)

Function: merge-hash-tables FROM-TABLE TO-TABLE

Add all entries from FROM-TABLE to TO-TABLE, overwriting existing entries with the same key.

Package

qlot/util

Source

lisp.lisp (file)

Function: systems-dependencies SYSTEMS QLHOME
Package

qlot

Source

lisp.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   Q  
Index Entry  Section

F
File, Lisp, qlot.asd: The qlot<dot>asd file
File, Lisp, qlot/main/lisp.lisp: The qlot/main/lisp<dot>lisp file
File, Lisp, qlot/util/lisp.lisp: The qlot/util/lisp<dot>lisp file

L
Lisp File, qlot.asd: The qlot<dot>asd file
Lisp File, qlot/main/lisp.lisp: The qlot/main/lisp<dot>lisp file
Lisp File, qlot/util/lisp.lisp: The qlot/util/lisp<dot>lisp file

Q
qlot.asd: The qlot<dot>asd file
qlot/main/lisp.lisp: The qlot/main/lisp<dot>lisp file
qlot/util/lisp.lisp: The qlot/util/lisp<dot>lisp file

Jump to:   F   L   Q  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   B   C   E   F   G   I   M   P   Q   S   U   W  
Index Entry  Section

A
all-required-systems: Exported functions

B
bundle: Exported functions

C
call-in-local-quicklisp: Exported functions

E
ensure-qlot-install: Internal functions

F
find-qlfile: Exported functions
Function, all-required-systems: Exported functions
Function, bundle: Exported functions
Function, call-in-local-quicklisp: Exported functions
Function, ensure-qlot-install: Internal functions
Function, find-qlfile: Exported functions
Function, generate-random-string: Exported functions
Function, install: Exported functions
Function, install-quicklisp: Exported functions
Function, merge-hash-tables: Internal functions
Function, pathname-in-directory-p: Exported functions
Function, project-systems: Exported functions
Function, quickload: Exported functions
Function, sbcl-contrib-p: Exported functions
Function, systems-dependencies: Internal functions
Function, update: Exported functions

G
generate-random-string: Exported functions

I
install: Exported functions
install-quicklisp: Exported functions

M
Macro, with-in-directory: Exported macros
Macro, with-local-quicklisp: Exported macros
Macro, with-package-functions: Exported macros
Macro, with-quicklisp-home: Exported macros
merge-hash-tables: Internal functions

P
pathname-in-directory-p: Exported functions
project-systems: Exported functions

Q
quickload: Exported functions

S
sbcl-contrib-p: Exported functions
systems-dependencies: Internal functions

U
update: Exported functions

W
with-in-directory: Exported macros
with-local-quicklisp: Exported macros
with-package-functions: Exported macros
with-quicklisp-home: Exported macros

Jump to:   A   B   C   E   F   G   I   M   P   Q   S   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*system-quicklisp-home*: Exported special variables

S
Special Variable, *system-quicklisp-home*: Exported special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   Q   S  
Index Entry  Section

P
Package, qlot: The qlot package
Package, qlot/util: The qlot/util package

Q
qlot: The qlot system
qlot: The qlot package
qlot/main: The qlot/main system
qlot/util: The qlot/util system
qlot/util: The qlot/util package

S
System, qlot: The qlot system
System, qlot/main: The qlot/main system
System, qlot/util: The qlot/util system

Jump to:   P   Q   S