Documentation for BOLTS 0.4 (development version)

stable dev

How to use a development checkout

This assumes that you have obtained a git checkout by cloning either the official BOLTS git or a fork. You need to have python, pyYAML and optionally FreeCAD and OpenSCAD installed. This tutorial makes heavy use of the commandline.

There are several tasks that are so common in BOLTS development that they have been put into a script called This tutorial describes how to use this script to perform these tasks. Some information about the available subcommands and options is available by typing

./ --help

Exporting backends

After making some changes, one might want to rebuild the output of a backend, so that one can inspect it. This can be done using the export subcommand. The results of this operation can be found in the respective subdirectory of the output directory.

For example to regenerate the OpenSCAD distribution one uses

./ export openscad

To build a OpenSCAD library that is restricted to content compatible with a certain license, one can supply an additional argument:

./ export openscad --license lgpl2.1+

Running automatic checks

BOLTS can run some automatic checks and detect a few common errors, problems and inconsistencies.

To do so, execute

./ check

A report is displayed with all the problems found and a short explanation.

Listing tasks

BOLTS can also look for missing bits and pieces and other small jobs that make BOLTS more complete or consistent.

To show a list of such tasks use

./ tasks

If there are tasks available, they are displayed together with a short explanation.

Helper for Connector drawings

The utility script also helps with the creation of images to document connectors for OpenSCAD parts. For details see [the corresponding doc page]({{ doc(openscad,connectors}).

Testing CAD applications

Manual inspection and automatic checks are good, but some errors can only be found when working in the CAD application. The utility script allows to fire up instances of OpenSCAD or FreeCAD with all necessary paths setup such that one can test freshly exported distributions.

This is done with the test subcommand. To test for FreeCAD type

./ export freecad
./ test freecad

This exports a FreeCAD distribution and starts an instance of FreeCAD with the module search paths set up correctly. You can now start BOLTS by typing

import BOLTS

into the FreeCAD Python console and then test your changes.

To test for OpenSCAD type

./ export openscad
./ test openscad

This exports a OpenSCAD distribution and starts an instance of OpenSCAD so that it finds the exported distribution. You can now include BOLTS by entering

include <BOLTS.scad>;

in the editor. It should now be possible to invoke BOLTS modules to test whether everything works.

Creating releases

The utility script also automates the process of preparing archives of released versions of BOLTS, by using the release subcommand. This is usually only used by the maintainer.

Testing the website

If you have made changes that have an impact on the website, you might want to check out if everything looks fine. You can do that with

./ test website

This serves the website as a web application at

Exporting the website

The static HTML files for the website are generated by a backend, so similar to the other backends

./ export website

kicks off this process and generates the result in output/website.