Bikeshed Documentation

1. Installing

1.1. Using Bikeshed Without A Local Install

1.1.1. Via the Web

If you use Bikeshed infrequently, and are okay with requiring a network roundtrip every time you invoke Bikeshed, you probably want to use the Bikeshed API instead. In return, the API version is always up-to-date, so you don’t have to remember to update things yourself. See § 2 Invoking Bikeshed Without Installing for options.

Note: The remote API has several limitations; most notably, it can’t take multiple files. If you are using custom boilerplates, or include files, you’ll have to run Bikeshed yourself.

1.1.2. Via pipx

If you use Bikeshed infrequently, but have the prereqs for a local install (a recent Python 3, and pipx; see below), you can run an always-up-to-date Bikeshed locally as:

pipx run bikeshed update && pipx run bikeshed

# on subsequent invocations, just call:
pipx run bikeshed

This does not have the limitations of the web version; you can use all the features of Bikeshed, including custom boilerplates and include files, or alternate run modes like bikeshed watch.

Note: This actually creates a temporary local install, which automatically disappears after a few days. It does not add the bikeshed command to your PATH. However, it generally won’t require manual upgrading; so long as it’s been long enough for pipx to delete the cached version, it’ll always grab the newest version of Bikeshed.

1.2. Prereqs

Bikeshed is a Python program, and getting Python working well in modern systems has a few (pretty easy) steps. (These might already all work for you!)

1.2.1. python3

Bikeshed requires Python 3.12 or later. (It’s currently tested up to 3.14.)

To tell what version you have, run:

python3 --version

If it reports 3.12.0 or later, you’re fine.

If it’s earlier, you’ll need to update your local Python version. There are several ways to do so, but I recommend pyenv as a safe and easy method.

https://github.com/pyenv/pyenv#installation gives instructions for installing pyenv on various environments. It also links to the auto-installer, which can make things even easier. Windows users have slightly different instructions, but it links to a windows fork as well.

If you know your way around pyenv already, feel free to do what you’re used to here. Otherwise, it’s probably easiest to just set up 3.14.1 as your "default" Python:

pyenv versions

will list what versions exist, and then

pyenv global 3.14.1

will set 3.14.1 as your "global" version, used by default. (Substitute in whatever the name of the version you saw in versions was.)

1.2.2. pipx

Installing packages globally is usually a bad (and sometimes insecure!) idea. They should instead be isolated into "virtual environments". This used to be a little tricky to set up, but now pipx makes it very simple.

To install pipx, your system software distribution might already have it; for example, distributions using apt can run

sudo apt-get install pipx

If this is not the case for you, see pipx’s install instructions and do whatever it says.

1.3. Installing Bikeshed Itself

1.3.1. Installing For Normal Use

Assuming the prereqs (above) are satisfied, installation is trivial:

pipx install bikeshed

When this is completed, Bikeshed should be installed, and the bikeshed command should work in your shell.

Note: If this is your first time running pipx, you might get a message complaining about your PATH variable, and Bikeshed’s attempt to update its data files will fail. If so, follow pipx’s instructions, then run bikeshed update again.

After this, invoking Bikeshed is just:

cd ~/my-spec-folder
bikeshed

Remember to update Bikeshed regularly by running:

pipx upgrade bikeshed

See § 1.4 Updating Bikeshed for more details.

You can also manually refresh Bikeshed’s datafiles by running:

bikeshed update

But this will run automatically whenever you use Bikeshed if your data files are more than a few days old, so it usually shouldn’t be necessary.

1.3.1.1. OpenSSL warning on Macs

1.3.2. Installing Bikeshed for Development

If you’re installing Bikeshed so you can work on it, or want to ensure you have the bleeding-edge tip-of-tree version, the instructions are just a tiny bit more complex.

First, clone the Bikeshed repository:

git clone https://github.com/speced/bikeshed.git

Then navigate to that folder (by default, it’ll be a folder called "bikeshed" in the current folder you’re in) and run:

pip3 install -e .

This will spam your console with a bunch of install progress. When it successfully completes, the bikeshed module should be globally available for import in Python, and a bikeshed command should now work in your shell.

1.3.2.1. Installing With Pipenv

You probably don’t want to install all of Bikeshed’s dependencies globally, so I recommend using pipenv to install it into a virtual environment (similar to what pipx does for non-dev installs).

Follow the same instructions as above, but instead of running pip3 install, run:

pipenv install --dev -e .
pipenv run bikeshed update

This will not install a bikeshed command by default; instead, you run Bikeshed with pipenv run bikeshed. If you’d like bikeshed to work by itself, either start a pipenv shell with pipenv shell, or add an alias to your machine like:

bikeshed=pipenv run bikeshed

1.4. Updating Bikeshed

To update bikeshed to its latest version at any time, just run:

pipx upgrade bikeshed && bikeshed update

This’ll pull the latest version of Bikeshed, and ensure that you’re looking at the latest version of the data files, rather than whatever stale version is currently sitting in the repo.

Note: If you did an "editable" install up above, to update it you just run the install command again and invoke bikeshed update afterwards.

1.5. Building a Bikeshed docker image

Note: I don’t actually understand Docker or know how to use it, so this guide is based on one community member’s efforts. If something is wrong or outdated, uh, figure out how to fix it and tell me so I can fix the docs.

• If needed, download and install docker community engine

• Build the Bikeshed image from the project’s directory:

  docker build --tag=bikeshed:latest .
  

  The above command will cache Bikeshed’s datafiles in the Docker layer cache, in order to speed up rebuilds. If you want to be sure you get the latest datafiles, run bikeshed update in the container or add the --no-cache flag when building the image:

  docker build --tag=bikeshed:latest --no-cache .
  

• Optionally, deploy the Bikeshed image to a docker registry

  For example, on a unix system (for Windows, consider the Windows Subsystem for Linux):

  TAG=$(docker image inspect --format='{{.Id}}' bikeshed:latest)
  DATE=$(date '+%Y.%m.%d')
  

  Login to a docker registry.

  docker login
  

  Tag the image to be pushed as organization/artifact:version

  docker tag $TAG <organization>/bikeshed:$DATE
  

  Push the tagged image to the docker registry

  docker push <organization>/bikeshed:$DATE
  

1.5.1. Invoking Bikeshed using a docker image

Note: As stated up in § 1.5 Building a Bikeshed docker image, I don’t know how Docker works and this guide is based on a community member’s experience, so use at your own risk.

Typically, this requires login to the docker registry and pulling a Bikeshed image.

For some <organization> and some <date>:

docker login
docker pull <organization>/bikeshed:<date>

Regardless of host environment’s operating system, running Bikeshed from a docker image requires two things:

• mapping a host directory to a path in the docker image (e.g. /data)

• specifying the location of Bikeshed’s input and output relative to the path in the docker image (i.e., /data)

Example for a Unix host:

docker run --rm -v $(pwd):/data <organization>/bikeshed:<date> bikeshed spec /data/<some *.bs file> [/data/<some output file>]

Example for a Windows host:

docker run --rm --volume C:\mystuff\project1\:/data <organization>/bikeshed:<date> spec /data/Index.bs /data/out/Index.html

Note that the § 3.1 Global Options apply to running Bikeshed from a docker image. Since the Bikeshed docker image is read-only, it does not make sense to execute the Bikeshed update command from a docker image.