Bikeshed Documentation

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.