Repository files navigation

OpenSCAD is a software for creating solid 3D CAD objects. It is free software andavailable for Linux/UNIX, MS Windows and macOS.

Unlike most free software for creating 3D models (such as the famousapplication Blender), OpenSCAD focuses on the CAD aspects rather than theartistic aspects of 3D modeling. Thus this might be the application you arelooking for when you are planning to create 3D models of machine parts butprobably not the tool for creating computer-animated movies.

OpenSCAD is not an interactive modeler. Instead it is more like a3D-compiler that reads a script file that describes the object and rendersthe 3D model from this script file (see examples below). This gives you, thedesigner, complete control over the modeling process and enables you to easilychange any step in the modeling process or make designs that are defined byconfigurable parameters.

OpenSCAD provides two main modeling techniques: First there is constructivesolid geometry (aka CSG) and second there is extrusion of 2D outlines. As the dataexchange format for these 2D outlines Autocad DXF files are used. Inaddition to 2D paths for extrusion it is also possible to read design parametersfrom DXF files. Besides DXF files OpenSCAD can read and create 3D models in theSTL and OFF file formats.

• Getting Started
• Documentation
  • Building OpenSCAD
    • Prerequisites
    • Getting the source code
    • Building for macOS
    • Building for Linux/BSD
    • Building for Linux/BSD on systems with older or missing dependencies
    • Building for Windows
    • Compilation

You can download the latest binaries of OpenSCAD athttps://www.openscad.org/downloads.html. Install binaries as you would any othersoftware.

When you open OpenSCAD, you'll see three frames within the window. Theleft frame is where you'll write code to model 3D objects. The rightframe is where you'll see the 3D rendering of your model.

Let's make a tree! Type the following code into the left frame:

cylinder(h = 30, r = 8);

Then render the 3D model by hitting F5. Now you can see a cylinder forthe trunk in our tree. Now let's add the bushy/leafy part of the treerepresented by a sphere. To do so, we will union a cylinder and asphere.

union() {  cylinder(h = 30, r = 8);  sphere(20);}

But, it's not quite right! The bushy/leafy are around the base of thetree. We need to move the sphere up the z-axis.

union() {  cylinder(h = 30, r = 8);  translate([0, 0, 40]) sphere(20);}

And that's it! You made your first 3D model! There are other primitiveshapes that you can combine with other set operations (union,intersection, difference) and transformations (rotate, scale,translate) to make complex models! Check out all the other languagefeatures in theOpenSCADManual.

Have a look at the OpenSCAD Homepage (https://www.openscad.org/documentation.html) for documentation.

To build OpenSCAD from source, follow the instructions for theplatform applicable to you below.

To build OpenSCAD, you need some libraries and tools. The versionnumbers in brackets specify the versions which have been used fordevelopment. Other versions may or may not work as well.

If you're using a newer version of Ubuntu, you can install theselibraries from aptitude. If you're using Mac, or an older Linux/BSD, thereare build scripts that download and compile the libraries from source.Follow the instructions for the platform you're compiling on below.

• A C++ compiler supporting C++17
• cmake (3.5 ->)
• Qt (5.12 ->)
• QScintilla2 (2.9 ->)
• CGAL (5.4 ->)
• GMP (5.x)
• MPFR (3.x)
• boost (1.61 ->)
• OpenCSG (1.4.2 ->)
• GLEW (1.5.4 ->)
• Eigen (3.x)
• glib2 (2.x)
• fontconfig (2.10 -> )
• freetype2 (2.4 -> )
• harfbuzz (0.9.19 -> )
• libzip (0.10.1 -> )
• Bison (2.4 -> )
• Flex (2.5.35 -> )
• pkg-config (0.26 -> )
• double-conversion (2.0.1 -> )

For the test suite, additional requirements are:

• Python3 (3.8 -> )

Install git (https://git-scm.com/) onto your system. Then run a clone:

git clone https://github.com/openscad/openscad.git

This will download the latest sources into a directory namedopenscad.

To pull the various submodules (incl. theMCAD library), do the following:

cd openscadgit submodule update --init --recursive

Prerequisites:

• Xcode
• automake, libtool, cmake, pkg-config, wget, meson, python-packaging (we recommend installing these using Homebrew)

Install Dependencies:

After building dependencies using one of the following options, follow the instructions in theCompilation section.

1. From source

   Run the script that sets up the environment variables:

    source scripts/setenv-macos.sh

   Then run the script to compile all the dependencies:

    ./scripts/macosx-build-dependencies.sh

2. Homebrew (assumesHomebrew is already installed)

    ./scripts/macosx-build-homebrew.sh

First, make sure that you have git installed (often packaged as 'git-core'or 'scmgit'). Once you've cloned this git repository, download and installthe dependency packages listed above using your system's packagemanager. A convenience script is provided that can help with thisprocess on some systems:

sudo ./scripts/uni-get-dependencies.sh

After installing dependencies, check their versions. You can run thisscript to help you:

./scripts/check-dependencies.sh

Take care that you don't have old local copies anywhere (/usr/local/).If all dependencies are present and of a high enough version, skip aheadto the Compilation instructions.

If some of your system dependency libraries are missing or old, then youcan download and build newer versions into$HOME/openscad_deps byfollowing this process. First, run the script that sets up theenvironment variables.

source ./scripts/setenv-unibuild.sh

Then run the script to compile all the prerequisite libraries above:

./scripts/uni-build-dependencies.sh

Note that huge dependencies like gcc, qt, or glib2 are not includedhere, only the smaller ones (boost, CGAL, opencsg, etc). After thebuild, again check dependencies.

./scripts/check-dependencies.sh

After that, follow the Compilation instructions below.

OpenSCAD for Windows is usually cross-compiled from Linux. If you wish toattempt an MSVC build on Windows, please see this site:https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Building_on_Windows

To cross-build, first make sure that you have all necessary dependenciesof the MXE project ( listed athttps://mxe.cc/#requirements ). Don't installMXE itself, the scripts below will do that for you under$HOME/openscad_deps/mxe

Then get your development tools installed to get GCC. Then after you'vecloned this git repository, start a new clean bash shell and run thescript that sets up the environment variables.

source ./scripts/setenv-mingw-xbuild.sh 64

Then run the script to download & compile all the prerequisite libraries above:

./scripts/mingw-x-build-dependencies.sh 64

Note that this process can take several hours, and tens of gigabytes ofdisk space, as it uses thehttps://mxe.cc system to cross-build manylibraries. After it is complete, build OpenSCAD and package it to aninstaller:

./scripts/release-common.sh mingw64

For a 32-bit Windows cross-build, replace 64 with 32 in the above instructions.

We support building OpenSCAD headless for WebAssembly w/ Emscripten, using a premade Docker image built inopenscad/openscad-wasm (which also has usage examples):

docker run --rm -it -v$PWD:/src:rw --platform=linux/amd64 openscad/wasm-base:latest \  emcmake cmake -B build -DEXPERIMENTAL=ON -DCMAKE_BUILD_TYPE=Release&& \docker run --rm -it -v$PWD:/src:rw --platform=linux/amd64 openscad/wasm-base:latest \  cmake --build build

This createsopenscad.wasm &openscad.js in thebuild/ folder.

openscad/openscad-playground uses the WASM build to provide a Web UI with a subset of features of OpenSCAD.

First, runcmake -B build -DEXPERIMENTAL=1 to generate a Makefile in thebuild folder.

Then runcmake --build build. Finally, on Linux you might runcmake --install build as root.

If you had problems compiling from source, raise a new issue in theissue tracker on the github page.

This site and it's subpages can also be helpful:https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Building_OpenSCAD_from_Sources

Once built, you can run tests withctest from thebuild directory.

Note: Bothcmake --build andctest accepts a-j N argument for distributing the load overN parallel processes.

• Installcircleci-cli (you'll need an API key)

  Note: we also use GitHub Workflows, but only to run tests on Windows (which we cross-build for in the Linux-based CircleCI workflows below). Also,act doesn't like our submodule setup anyway.

• Run the CI jobs

  # When "successful", these will fail to upload at the very end of the workflow.circlecilocal execute --job  openscad-mxe-64bitcirclecilocal execute --job  openscad-mxe-32bitcirclecilocal execute --job  openscad-appimage-64bit

  Note: openscad-macos can't be built locally.

• If/when GCC gets randomly killed, give docker more RAM (e.g. 4GB per concurrent image you plan to run)

• To debug the jobs more interactively, you can go the manual route (inspect .circleci/config.yml to get the actual docker image you need)

  docker run --entrypoint=/bin/bash -it openscad/mxe-x86_64-gui:latest

  Then once you get the console:

  git clone https://github.com/%your username%/openscad.git workspacecd workspacegit checkout %your branch%git submodule initgit submodule update# Then execute the commands from .circleci/config.yml:#    export NUMCPU=2#    ...#    ./scripts/release-common.sh -snapshot -mingw64 -v "$OPENSCAD_VERSION"