OpenSCAD User Manual/Building on Linux/UNIX
- 1 Prebuilt binary packages
- 2 Building OpenSCAD yourself
- 3 Compiling the test suite
- 4 Troubleshooting
- 5 Tricks and tips
Prebuilt binary packages
As of 2013, prebuilt OpenSCAD packages are available on many recent Linux and BSD distributions, including Debian, Ubuntu, Fedora, Arch, and NetBSD. Check your system's package manager for details.
For Ubuntu systems you can also try chrysn's Ubuntu packages at his launchpad PPA, or you can just copy/paste the following onto the command line:
sudo add-apt-repository ppa:chrysn/openscad sudo apt-get update sudo apt-get install openscad
There is also a generic linux binary package at http://www.openscad.org that can be unpacked and run from within most linux systems. It is self contained and includes the required libraries.
Building OpenSCAD yourself
If you wish to build OpenSCAD for yourself, start by installing git on your system using your package manager. Git is often packaged under the name 'scmgit' or 'git-core'. Then, get the OpenSCAD source code
cd ~/ git clone https://github.com/openscad/openscad.git cd openscad
Then get the MCAD library, which is now included with OpenSCAD binary distributions
git submodule init git submodule update
Now download and install the dependency libraries and tools using your package manager. This includes Qt4, CGAL, GMP, cmake, MPFR, boost, OpenCSG, GLEW, Eigen2, GCC C++ Compiler, Bison, and Flex. OpenSCAD comes with a helper script that will try to fetch and install these automatically for you (note: you must have 'sudo' working for this script to work).
Now check the version numbers against the openscad/README.md file to see if the version numbers are high enough and that no packages were accidentally missed. OpenSCAD comes with another helper script to assist in this process.
(Note that this detects a 'lower bound' on GLEW, not the actual version you have)
If your system passes all checks, continue to the 'Building OpenSCAD' section below. If you are missing libraries, try to search your package manager to see if it might have them under different names. If your package manager has the package but it is just too old, then read the next section on building your own dependencies.
Building the dependencies yourself
On systems that lack updated dependency libraries or tools, you can download and build your own. As of 2013, OpenSCAD comes with scripts that can do this automatically, without interfering with any system libraries, and without requiring root access, by putting everything under $HOME/openscad_deps. (It however will not build X11, Qt4, gcc, bash or other basics).
First, set up the environment variables (if you don't use bash, replace "source" with a single ".")
Then, download and build.
If you only need CGAL or OpenCSG, you can just run ' ./scripts/uni-build-dependencies.sh cgal' or opencsg and it will only build a single library. The complete download and build process can take anywhere from half an hour to several hours, depending on your network connection speed and system speed. It is recommended to have at least 1.5 Gigabyte of free disk space to do the full dependency build. Each time you log into a new shell and wish to re-compile OpenSCAD you need to re-run the 'source scripts/setenv-unibuild.sh' script
After completion, re-check (while running under the same shell, with the same environment variables set) to see if it worked.
Build the OpenSCAD binary
Once you have either downloaded or built the dependencies, you can build OpenSCAD.
qmake # or qmake-qt4, depending on your distribution make
You can also install OpenSCAD to /usr/local/ if you wish. The 'openscad' binary will be put under /usr/local/bin, the libraries and examples will be under something like /usr/local/share/openscad possibly depending on your system. Note that if you have previously installed a binary linux package of openscad, you should take care to delete /usr/local/lib/openscad and /usr/local/share/openscad because they are not the same paths as what the standard qmake-built 'install' target uses.
sudo make install
Note: on Debian-based systems create a package and install OpenSCAD using:sudo checkinstall -D make install
If you prefer not to install you can run "
./openscad" directly whilst still in the ~/openscad directory.
Compiling the test suite
OpenSCAD comes with over 740 regression tests. To build and run them, it is recommended to first build the GUI version of OpenSCAD by following the steps above, including the downloading of MCAD. Then, from the same login, run these commands:
cd tests mkdir build && cd build cmake .. make ctest -C All
The file 'openscad/doc/testing.txt' has more information. Full test logs are under
tests/build/Testing/Temporary. A pretty-printed index.html web view of the tests can be found under a machine-specific subdirectory thereof and opened with a browser.
If you encounter any errors when building, please file an issue report at https://github.com/openscad/openscad/issues/ .
Errors about incompatible library versions
This may be caused by old libraries living in /usr/local/lib like boost, CGAL, OpenCSG, etc, (often left over from previous experiments with OpenSCAD). You are advised to remove them. To remove, for example, CGAL, run rm -rf /usr/local/include/CGAL && rm -rf /usr/local/lib/*CGAL*. Then erase $HOME/openscad_deps, remove your openscad source tree, and restart fresh. As of 2013 OpenSCAD's build process does not advise nor require anything to be installed in /usr/local/lib nor /usr/local/include.
Note that CGAL depends on Boost and OpenCSG depends on GLEW - interdependencies like this can really cause issues if there are stray libraries in unusual places.
Another source of confusion can come from running from within an 'unclean shell'. Make sure that you don't have LD_LIBRARY_PATH set to point to any old libraries in any strange places. Also don't mix a Mingw windows cross build with your linux build process - they use different environment variables and may conflict.
OpenCSG didn't automatically build
If for some reason the recommended build process above fails to work with OpenCSG, please file an issue on the OpenSCAD github. In the meantime, you can try building it yourself.
wget http://www.opencsg.org/OpenCSG-1.3.2.tar.gz sudo apt-get purge libopencsg-dev libopencsg1 # or your system's equivalent tar -xvf OpenCSG-1.3.2.tar.gz cd OpenCSG-1.3.2 # edit the Makefile and remove 'example' make sudo cp -d lib/lib* $HOME/openscad_deps/lib/ sudo cp include/opencsg.h $HOME/openscad_deps/include/
Note: on Debian-based systems (such as Ubuntu), you can add the 'install' target to the OpenCSG Makefile, and then use checkinstall to create a clean .deb package for install/removal/upgrade. Add this target to Makefile:install: # !! THESE LINES PREFIXED WITH ONE TAB, NOT SPACES !! cp -d lib/lib* /usr/local/lib/ cp include/opencsg.h /usr/local/include/ ldconfig
Then:sudo checkinstall -D make install
.. to create and install a clean package.
CGAL didn't automatically build
If this happens, you can try to compile CGAL yourself. It is recommended to install to $HOME/openscad_deps and otherwise follow the build process as outlined above.
Compiling is horribly slow and/or grinds the disk
It is recommended to have at least 1.2 Gbyte of RAM to compile OpenSCAD. There are a few workarounds in case you don't. The first is to use the experimental support for the Clang Compiler (described below) as Clang uses much less RAM than GCC. Another workaround is to edit the Makefile generated by qmake and search/replace the optimization flags (-O2) with -O1 or blank, and to remove any '-g' debug flags from the compiler line, as well as '-pipe'.
If you have plenty of RAM and just want to speed up the build, you can try a paralell multicore build with
Where 'x' is the number of cores you want to use. Remember you need x times the amount of RAM to avoid possible disk thrashing.
The reason the build is slow is because OpenSCAD uses template libraries like CGAL, Boost, and Eigen, which use large amounts of RAM to compile - especially CGAL. GCC may take up 1.5 Gigabytes of RAM on some systems during the build of certain CGAL modules. There is more information at StackOverflow.com.
The build instructions above are designed to work unchanged on FreeBSD and NetBSD. However the BSDs typically require special environment variables set up to build any QT project - you can set them up automatically by running
NetBSD 5.x, requires a patched version of CGAL. It is recommended to upgrade to NetBSD 6 instead as it has all dependencies available from pkgin. NetBSD also requires the X Sets to be installed when the system was created (or added later).
On OpenBSD it may fail to build after running out of RAM. OpenSCAD requires at least 1 Gigabyte to build with GCC. You may have need to be a user with 'staff' level access or otherwise alter required system parameters. The 'dependency build' sequence has also not been ported to OpenBSD so you will have to rely on the standard OpenBSD system package tools (in other words you have to have root).
Test suite problems
The test suite will try to automatically detect if you have an X11 DISPLAY environment variable set. If not, it will try to automatically start Xvfb or Xvnc (virtual X framebuffers) if they are available.
If you want to run these servers manually, you can attempt the following:
$ Xvfb :5 -screen 0 800x600x24 & $ DISPLAY=:5 ctest
$ xvfb-run --server-args='-screen 0 800x600x24' ctest
There are some cases where Xvfb/Xvnc won't work. Some older versions of Xvfb may fail and crash without warning. Sometimes Xvfb/Xvnc have been built without GLX (OpenGL) support and OpenSCAD won't be able to generate any images.
Image-based tests takes a long time, they fail, and the log says 'return -11'
Imagemagick may have crashed while comparing the expected images to the test-run generated (actual) images. You can try using the alternate ImageMagick comparison method by by erasing CMakeCache, and re-running cmake with
-DCOMPARATOR=ncc. This will enable the Normalized Cross Comparison method which is more stable, but possibly less accurate and may give false positives or negatives.
Testing images fails with 'morphology not found" for ImageMagick in the log
Your version of imagemagick is old. Upgrade imagemagick, or pass -DCOMPARATOR=old to cmake. The comparison will be of lowered reliability.
I moved the dependencies I built and now openscad won't run
It isn't advised to move them because the build is using RPATH hard coded into the openscad binary. You may try to workaround by setting the LD_LIBRARY_PATH environment variable to place yourpath/lib first in the list of paths it searches. If all else fails, you can re-run the entire dependency build process but export the BASEDIR environment variable to your desired location, before you run the script to set environment variables.
Tricks and tips
Reduce space of dependency build
After you have built the dependencies you can free up space by removing the $BASEDIR/src directory - where $BASEDIR defaults to $HOME/openscad_deps.
OpenSCAD's config file is kept in ~/.config/OpenSCAD/OpenSCAD.conf.
Setup environment to start developing OpenSCAD in Ubuntu 11.04
The following paragraph describes an easy way to setup a development environment for OpenSCAD in Ubuntu 11.04. After executing the following steps QT Creator can be used to graphically start developing/debugging OpenSCAD.
- Add required PPA repositories:
# sudo add-apt-repository ppa:chrysn/openscad
- Update and install required packages:
# sudo apt-get update # sudo apt-get install git build-essential qtcreator libglew1.5-dev libopencsg-dev libcgal-dev libeigen2-dev bison flex
- Get the OpenSCAD sources:
# mkdir ~/src # cd ~/src # git clone https://github.com/openscad/openscad.git
- Build OpenSCAD using the command line:
# cd ~/src/openscad # qmake # make
- Build OpenSCAD using QT Creator:
Just open the project file openscad.pro (CTRL+O) in QT Creator and hit the build all (CTRL+SHIFT+B) and run button (CTRL+R).
The Clang Compiler
There is experimental support for building with the Clang compiler under linux. Clang is faster, uses less RAM, and has different error messages than GCC. To use it, first of all you will need CGAL of at least version 4.0.2, as prior versions have a bug that makes clang unusable. Then, run this script before you build OpenSCAD.
source scripts/setenv-unibuild.sh clang
Clang support depends on your system's QT installation having a clang enabled qmake.conf file. For example, on Ubuntu, this is under /usr/share/qt4/mkspecs/unsupported/linux-clang/qmake.conf. BSD clang-building may require a good deal of fiddling and is untested, although eventually it is planned to move in this direction as the BSDs (not to mention OSX) are moving towards favoring clang as their main compiler.