Lisp-Stat Development Container

An OCI container image for Common Lisp and Lisp-Stat development
Learn more at lisp-stat.dev »
Report Bug · Request Feature

Table of Contents

1. About the Project
   • Built With
2. Getting Started
   • Run Locally with Docker
   • Run in a devcontainer
   • Run on the Cloud
3. Developer Workflow
4. Building an Image
5. Resources
6. Contributing
7. License
8. Contact

About the Project

This repository provides a ready-to-use, containerized development environment for Common Lisp and Lisp-Stat. It is ideal for:

• Evaluating Lisp-Stat without local installation.
• Quickly starting new Lisp-Stat projects in consistent, reproducible environments.
• Contributing to Lisp-Stat and its ecosystem.

It is suited for both experimenters/learners and contributors.

Built With

• SBCL (Steel Bank Common Lisp)
• Quicklisp
• Lisp-Stat
• devcontainer Features
• OpenBLAS
• Docker
• VS Code Devcontainers

---

Getting Started

A prebuilt image is published at:

ghcr.io/lisp-stat/ls-dev:latest

You can use this image locally with Docker, in a Devcontainer, or in the Cloud (e.g. Codespaces).

Supported runtimes:

• Docker (Linux/Mac/Windows)
• Podman
• containerd, Lima, Rancher Desktop, Colima
• VS Code Dev Containers
• GitHub Codespaces

---

Run Locally with Docker

Quick Experimentation

1. Pull the latest image:

   docker pull ghcr.io/lisp-stat/ls-dev:latest

2. Start an interactive Lisp-Stat REPL:

   docker run --rm -it --user vscode -w /home/vscode ghcr.io/lisp-stat/ls-dev:latest /bin/bash -c "ls-init.sh --mode developer && ls-repl"

   This will start a script that will ask you how to proceed:

   [ls-init.sh] SHELL: /bin/bash                  
   [ls-init.sh] Bash version: 5.2.21(1)-release   
   [ls-init.sh] Args: --mode developer            
   [ls-init.sh] TTY: /dev/pts/0                   
   HOME=/home/vscode                              
   PWD=/home/vscode                               
   SHLVL=2                                        
   TERM=xterm                                     
   Select setup mode:                             
   1) Experimenter (default, upstream only)       
   2) Contributor (fork and relink)               
   #?

Choose your option and the script will configure and compile the source and start a Lisp-Stat REPL. From here you can experiment with Lisp-Stat or Common-Lisp (Lisp-Stat is a superset of Common Lisp). If in future you wish to use only Common-Lisp, modify your ~/.sbclrc file to remove the loading of .ls-init.sh.

When you start ls-repl, the ~/.ls-init.lisp file configures lisp-stat to load a few data sets, like mtcars, and also configures an instance of ls-server on port 20202 by default. Data frames and plots that you create will show up in this web interface, and you can edit the data-frames from there in an excel like interface. You must have port forwarding configured for your container, after which you can open http://localhost:20202.

Editing Code

Emacs and slime are also configured in this container. This is the typical lisp coding environment. To edit with emacs:

1. Start your container with a shell:

docker run --rm -it --user vscode -w /home/vscode ghcr.io/lisp-stat/ls-dev:latest bash

2. Run ls-init.sh to obtain the source if you have not already done so
3. From within the container, run emacs
4. From emacs, run M-x slime (the 'M' stands for the 'Meta' key, and is often Alt in PC style keyboards)

---

Setting Up a Persistent Development Workspace

To persist source code and settings between container restarts, use Docker volumes or bind mounts. This is essential if you want to do any code editing, save your work, or contribute changes.

Option A: Named Docker Volume (Recommended)

1. Create or reuse a named volume for Lisp-Stat developer workspace:

   docker volume create lisp-stat-workspace

2. Start the container with persistent workspace:

   docker run --rm -it \
     --user vscode \
     -v lisp-stat-workspace:/workspaces/ls-dev \
     ghcr.io/lisp-stat/ls-dev:latest bash

Option B: Host Directory Mount

1. Create a directory on your host for Lisp-Stat projects:

   mkdir -p ~/lisp-stat-workspace

2. Start the container mounting this directory:

   docker run --rm -it \
     --user vscode \
     -v ~/lisp-stat-workspace:/workspaces/ls-dev \
     ghcr.io/lisp-stat/ls-dev:latest bash

---

(Optional) Pre-configure the Container with ls-init.sh

The included ls-init.sh script sets up your developer workspace. You should run this INSIDE the container after starting it with a persistent workspace as above. See the Developer Workflow for details.

---

Run in a Devcontainer

If you use Visual Studio Code or similar tools that support devcontainers, you can use the image directly.

1. Create a devcontainer.json file in your project's root directory:

   {
     "name": "My Lisp-Stat Project",
     "image": "ghcr.io/lisp-stat/ls-dev:latest",
     "mounts": [
       "source=lisp-stat-workspace,target=/workspaces/ls-dev,type=volume"
     ]
   }

2. Open the folder in VS Code and "Reopen in Container" when prompted.

You can also use the devcontainercli as a docker replacement for working with these images. This is our recommendation.

Run on the Cloud (GitHub Codespaces)

1. Go to your repository on GitHub.
2. Click on the Code button and choose "Open with Codespaces".
3. Use the devcontainer.json example above for the fastest start.
4. Wait for the Codespace to initialize and you can begin using VS Code in the browser.

---

Developer Workflow

This section focuses on helping new developers onboard, regardless of familiarity with Common Lisp, Docker, or GitHub. All essential setup is automated by the ls-init.sh script included in the image.

There are two main modes:

• Experimenter: Want to try out/dev or learn? Get read-only access to all Lisp-Stat software with no need to set up GitHub.
• Contributor: Want to contribute and submit pull requests? Fork, clone, and set up your workspace for development and PRs on GitHub.

1. Open Your Container

Start the container using one of the methods above:

• Docker (with a persistent volume or directory, see "Run Locally")
• VS Code Devcontainer
• Codespaces

For all modes, commands below should be run inside the container shell as the vscode user.

---

2. Set Up Your Development Environment with ls-init.sh

About ls-init.sh

ls-init.sh sets up your Lisp-Stat workspace in two ways:

• Experimenter mode (default): Clones official Lisp-Stat repositories to a workspace directory (e.g., /workspaces/ls-dev), making them available read-only. Safe, fast, and ideal for exploring or learning.
• Contributor mode: Forks the official repositories to your GitHub account and clones your forks to your workspace (e.g., /workspaces/ls-dev) so you can commit and push changes, submit PRs, and track upstream changes.

Prerequisites (for Contributor mode only)

• You must have GitHub CLI (gh) installed in the container (preinstalled in image).
• You must be authenticated to GitHub:

  gh auth login
  

---

Experimenter Workflow: Fastest Start without GitHub

1. (Inside container) Run ls-init.sh in experimenter mode (default):

   /usr/local/bin/ls-init.sh

   Or, explicitly:

   /ls-init.sh --mode experimenter

   • This clones the latest official Lisp-Stat repositories to /workspaces/lisp-stat-upstream (or $HOME/lisp-stat-upstream), then symlinks them into:

     • /workspaces/ls-dev (your workspace mount for editor access)
     • ~/quicklisp/local-projects (so SBCL/Quicklisp can discover them)

   • You can immediately open and work with all Lisp-Stat source code.

   • Code is read-only with respect to pushing changes upstream or submitting PRs.

To update to the latest upstream after a while:

ls-init.sh --mode experimenter --refresh

This fetches and updates all repos to their newest state.

---

Contributor Workflow: Fork, Edit, and Submit Pull Requests

1. Authenticate to GitHub (if not already):

   gh auth login

2. Run ls-init.sh in contributor mode:

   ls-init.sh --mode contributor

   • This does all experimenter steps BUT

     • Forks each Lisp-Stat repo to your GitHub account (using the gh command).
     • Clones your forks to /workspaces/ls-dev (the persistent workspace).
     • Adds the official Lisp-Stat repo as upstream so you can stay up-to-date.
     • Symlinks all your clones into ~/quicklisp/local-projects (so Lisp can load your forks by default).

   • Now, any edits you make are in your own GitHub fork. You can commit, push, and create pull requests directly.

---

Workflow Quick Reference Table

Mode	Workspace source	Pushing changes	PRs?	Suitable for
Experimenter	Official repos (read-only)	No	No	Exploration, learning
Contributor	Your GitHub forks (w/upstream)	Yes	Yes	Active development, contributing

To switch modes later:
You can always re-run ls-init.sh in contributor mode later to become a contributor.

---

What Gets Set Up

• /workspaces/ls-dev/<repo>: Your working tree (fork or upstream clone)
• ~/quicklisp/local-projects/<repo>: Symlink to above (for SBCL/Quicklisp)
• For contributors: origin remote is your fork, upstream is the official repo.

---

Example: Full Contributing Process (Step-by-Step)

1. Start the container with a persistent workspace.

2. Inside the container:

   gh auth login         # if needed
   ls-init.sh --mode contributor

3. Make and commit code changes:

   cd /workspaces/ls-dev/data-frame
   git checkout -b my-cool-feature
   # ...edit/code/test...
   git add .
   git commit -m "Add my cool feature"
   git push origin my-cool-feature

4. Open a pull request on GitHub as usual.

5. To update your fork with latest from upstream:

   git fetch upstream
   git merge upstream/master
   git push origin master

---

Building an Image

To customize or rebuild the image yourself, you need the devcontainer CLI:

npm install -g @devcontainers/cli
devcontainer build --workspace-folder . --image-name my-ls-dev:latest

To push to a registry:

devcontainer build --workspace-folder . --image-name ghcr.io/youruser/ls-dev:latest --push

Standard docker build is not supported (due to devcontainer features composition).

---

Resources

• Lisp-Stat Documentation
• devcontainer features source
• cl-jupyter-image

---

Contributing

Contributions are welcome—see CONTRIBUTING for guidelines.

---

License

Distributed under the MS-PL License. See LICENSE for details.

---

Contact

Project Link: https://github.com/Lisp-Stat/ls-dev-image