OpenSCAD User Manual/Using OpenSCAD in a command line environment

OpenSCAD can not only be used as a GUI, but also handles command line arguments. Its usage line says:

openscad [ -o output_file [ -d deps_file ] ] \
         [ -m make_command ] [ -D var=val [..] ] filename

The usage on OpenSCAD version 2011.09.30 is

openscad [ { -s stl_file | -o off_file | -x dxf_file } [ -d deps_file ] ]\
         [ -m make_command ] [ -D var=val [..] ] filename

Export options

When called with the -o option, OpenSCAD will not start the GUI, but execute the given file and export the to the output_file in a format depending on the extension (.stl / .off / .dxf, .csg).

Some versions use -s/-d/-o to determine the output file format instead check with "openscad --help".

If the option -d is given in addition to an export command, all files accessed while building the mesh are written in the argument of -d in the syntax of a Makefile.

Constants

In order to pre-define variables, use the -D option. It can be given repeatedly. Each occurrence of -D must be followed by an assignment. Unlike normal OpenSCAD assignments, these assignments don't define variables, but constants, which can not be changed inside the program, and can thus be used to overwrite values defined in the program at export time.

The right hand sides can be arbitrary OpenSCAD expressions, including mathematical operations and strings. Be aware that strings have to be enclosed in quotes, which have to be escaped from the shell. To render a model that takes a quality parameter with the value "production", one has to run

openscad -o my_model_production.stl -D 'quality="production"' my_model.scad

Command to build required files

In a complex build process, some files required by an OpenSCAD file might be currently missing, but can be generated, for example if they are defined in a Makefile. If OpenSCAD is given the option -m make, it will start make file the first time it tries to access a missing file.

Makefile example

The -d and -m options only make sense together. (-m without -d would not consider modified dependencies when building exports, -d without -m would require the files to be already built for the first run that generates the dependencies.)

Here is an example of a basic Makefile that creates an .stl file from an .scad file of the same name:

# explicit wildcard expansion suppresses errors when no files are found
include $(wildcard *.deps)

%.stl: %.scad
        openscad -m make -o $@ -d $@.deps $<

When make my_example.stl is run for the first time, it finds no .deps files, and will just depend on my_example.scad; since my_example.stl is not yet preset, it will be created unconditionally. If OpenSCAD finds missing files, it will call make to build them, and it will list all used files in my_example.stl.deps.

When make my_example.stl is called subsequently, it will find and include my_example.stl.deps and check if any of the files listed there, including my_example.scad, changed since my_example.stl was built, based on their time stamps. Only if that is the case, it will build my_example.stl again.

Automatic targets

When building similar .stl files from a single .scad file, there is a way to automate that too:

# match "module foobar() { // `make` me"
TARGETS=$(shell sed '/^module [a-z0-9_-]*().*make..\?me.*$$/!d;s/module //;s/().*/.stl/' base.scad)

all: ${TARGETS}

# auto-generated .scad files with .deps make make re-build always. keeping the
# scad files solves this problem. (explanations are welcome.)
.SECONDARY: $(shell echo "${TARGETS}" | sed 's/\.stl/.scad/g')

# explicit wildcard expansion suppresses errors when no files are found
include $(wildcard *.deps)

%.scad:
        echo -n 'use <base.scad>\n$*();' > $@

%.stl: %.scad
        openscad -m make -o $@ -d $@.deps $<

All objects that are supposed to be exported automatically have to be defined in base.scad in an own module with their future file name (without the ".stl"), and have a comment like "// make me" in the line of the module definition. The "TARGETS=" line picks these out of the base file and creates the file names. These will be built when make all (or make, for short) is called.

As the convention from the last example is to create the .stl files from .scad files of the same base name, for each of these files, an .scad file has to be generated. This is done in the "%.scad:" paragraph; my_example.scad will be a very simple OpenSCAD file:

use <base.scad>
my_example();

The ".SECONDARY" line is there to keep make from deleting the generated .scad files. If it deleted it, it would not be able to automatically determine which files need no rebuild any more; please post ideas about what exactly goes wrong there (or how to fix it better) on the talk page!