Name Date Size

..27-Apr.-20224 KiB

.circleci/H09-May-20224 KiB

.clang-formatH A D02-Aug.-2019550

.clang-tidyH A D02-Aug.-201994

.git-blame-ignore-revsH A D28-Mar.-2022629

.github/H17-Feb.-20214 KiB

.gitignoreH A D10-Apr.-20221.4 KiB

.gitmodulesH A D21-Jan.-2022196

.travis.ymlH A D21-Mar.-202110.4 KiB

.uncrustify.cfgH A D06-Feb.-20222.3 KiB

appcast-snapshots.xml.inH A D02-Aug.-2019943

appcast.xml.inH A D02-Aug.-2019927

cmake/Modules/H02-Aug.-20194 KiB

CMakeLists.txtH A D15-May-202238.4 KiB

CMakeSettings.jsonH A D02-Aug.-20192.1 KiB

color-schemes/H02-Aug.-20194 KiB

contrib/H30-Aug.-20204 KiB

COPYINGH A D02-Aug.-201918 KiB

doc/H14-Apr.-20224 KiB

dsa_pub.pemH A D02-Aug.-2019654

examples/H08-Sep.-20214 KiB

fonts/H02-Aug.-20194 KiB

fonts-osx/H02-Aug.-20194 KiB

Info.plistH A D29-Dec.-20212.9 KiB

Info.plist.inH A D29-Dec.-20212.7 KiB

libraries/MCAD/H02-Aug.-20194 KiB

locale/H06-Mar.-20224 KiB

openscad.appdata.xml.inH A D10-Apr.-20223.2 KiB

OpenSCAD.sdefH A D02-Aug.-2019378

org.openscad.OpenSCAD.xmlH A D02-Aug.-20192.4 KiB

patches/H24-Feb.-20224 KiB

README.mdH A D20-Mar.-202211.1 KiB

RELEASE_NOTES.mdH A D14-Apr.-202221.5 KiB

releases/H26-Oct.-20214 KiB

resources/H02-May-20224 KiB

scripts/H03-May-20224 KiB

shaders/H14-Aug.-20214 KiB

snap/H21-Apr.-20224 KiB

src/H03-May-202220 KiB

submodules/mimalloc/H21-Jan.-20224 KiB

templates/H19-Dec.-20214 KiB

tests/H29-Apr.-20224 KiB

valgrind.suppH A D02-Aug.-20191 KiB

winconsole/H24-Oct.-20214 KiB

xcode/H02-Aug.-20194 KiB

README.md

1[![GitHub (master)](https://img.shields.io/github/checks-status/openscad/openscad/master.svg?logo=github&label=build&logoColor=black&colorA=f9d72c&style=plastic)](https://github.com/openscad/openscad/actions)
2[![CircleCI (master)](https://img.shields.io/circleci/project/github/openscad/openscad/master.svg?logo=circleci&logoColor=black&colorA=f9d72c&style=plastic)](https://circleci.com/gh/openscad/openscad/tree/master)
3[![Coverity Scan](https://img.shields.io/coverity/scan/2510.svg?colorA=f9d72c&logoColor=black&style=plastic)](https://scan.coverity.com/projects/2510)
4
5[![Visit our IRC channel](https://kiwiirc.com/buttons/irc.libera.chat/openscad.png)](https://kiwiirc.com/client/irc.libera.chat/#openscad)
6
7# What is OpenSCAD?
8<p><a href="https://opencollective.com/openscad/donate"><img align="right" src="https://opencollective.com/openscad/donate/button@2x.png?color=white" width="200"/></a>
9
10OpenSCAD is a software for creating solid 3D CAD objects. It is free software and
11available for Linux/UNIX, MS Windows and macOS.</p>
12
13Unlike most free software for creating 3D models (such as the famous
14application Blender), OpenSCAD focuses on the CAD aspects rather than the 
15artistic aspects of 3D modeling. Thus this might be the application you are
16looking for when you are planning to create 3D models of machine parts but
17probably not the tool for creating computer-animated movies.
18
19OpenSCAD is not an interactive modeler. Instead it is more like a
203D-compiler that reads a script file that describes the object and renders
21the 3D model from this script file (see examples below). This gives you, the
22designer, complete control over the modeling process and enables you to easily
23change any step in the modeling process or make designs that are defined by
24configurable parameters.
25
26OpenSCAD provides two main modeling techniques: First there is constructive
27solid geometry (aka CSG) and second there is extrusion of 2D outlines. As the data
28exchange format for these 2D outlines Autocad DXF files are used. In
29addition to 2D paths for extrusion it is also possible to read design parameters
30from DXF files. Besides DXF files OpenSCAD can read and create 3D models in the
31STL and OFF file formats.
32
33# Contents
34
35- [Getting Started](#getting-started)
36- [Documentation](#documentation)
37    - [Building OpenSCAD](#building-openscad)
38        - [Prerequisites](#prerequisites)
39        - [Getting the source code](#getting-the-source-code)
40        - [Building for macOS](#building-for-macos)
41        - [Building for Linux/BSD](#building-for-linuxbsd)
42        - [Building for Linux/BSD on systems with older or missing dependencies](#building-for-linuxbsd-on-systems-with-older-or-missing-dependencies)
43        - [Building for Windows](#building-for-windows)
44        - [Compilation](#compilation)
45
46# Getting started
47
48You can download the latest binaries of OpenSCAD at
49<https://www.openscad.org/downloads.html>. Install binaries as you would any other
50software.
51
52When you open OpenSCAD, you'll see three frames within the window. The
53left frame is where you'll write code to model 3D objects. The right
54frame is where you'll see the 3D rendering of your model.
55
56Let's make a tree! Type the following code into the left frame:
57
58    cylinder(h = 30, r = 8);
59
60Then render the 3D model by hitting F5. Now you can see a cylinder for
61the trunk in our tree. Now let's add the bushy/leafy part of the tree
62represented by a sphere. To do so, we will union a cylinder and a
63sphere.
64
65    union() {
66      cylinder(h = 30, r = 8);
67      sphere(20);
68    }
69
70But, it's not quite right! The bushy/leafy are around the base of the
71tree. We need to move the sphere up the z-axis.
72
73    union() {
74      cylinder(h = 30, r = 8);
75      translate([0, 0, 40]) sphere(20);
76    }
77
78And that's it! You made your first 3D model! There are other primitive
79shapes that you can combine with other set operations (union,
80intersection, difference) and transformations (rotate, scale,
81translate) to make complex models! Check out all the other language
82features in the [OpenSCAD
83Manual](https://en.wikibooks.org/wiki/OpenSCAD_User_Manual).
84
85# Documentation
86
87Have a look at the OpenSCAD Homepage (https://www.openscad.org/documentation.html) for documentation.
88
89## Building OpenSCAD
90
91To build OpenSCAD from source, follow the instructions for the
92platform applicable to you below.
93
94### Prerequisites
95
96To build OpenSCAD, you need some libraries and tools. The version
97numbers in brackets specify the versions which have been used for
98development. Other versions may or may not work as well.
99
100If you're using a newer version of Ubuntu, you can install these 
101libraries from aptitude. If you're using Mac, or an older Linux/BSD, there 
102are build scripts that download and compile the libraries from source. 
103Follow the instructions for the platform you're compiling on below.
104
105* A C++ compiler supporting C++17
106* [cmake (3.5 ->)](https://cmake.org/)
107* [Qt (5.4 ->)](https://qt.io/)
108* [QScintilla2 (2.9 ->)](https://riverbankcomputing.com/software/qscintilla/)
109* [CGAL (5.4 ->)](https://www.cgal.org/)
110 * [GMP (5.x)](https://gmplib.org/)
111 * [MPFR (3.x)](https://www.mpfr.org/)
112* [boost (1.56 ->)](https://www.boost.org/)
113* [OpenCSG (1.4.2 ->)](http://www.opencsg.org/)
114* [GLEW (1.5.4 ->)](http://glew.sourceforge.net/)
115* [Eigen (3.x)](https://eigen.tuxfamily.org/)
116* [glib2 (2.x)](https://developer.gnome.org/glib/)
117* [fontconfig (2.10 -> )](https://fontconfig.org/)
118* [freetype2 (2.4 -> )](https://freetype.org/)
119* [harfbuzz (0.9.19 -> )](https://www.freedesktop.org/wiki/Software/HarfBuzz/)
120* [libzip (0.10.1 -> )](https://libzip.org/)
121* [Bison (2.4 -> )](https://www.gnu.org/software/bison/)
122* [Flex (2.5.35 -> )](http://flex.sourceforge.net/)
123* [pkg-config (0.26 -> )](https://www.freedesktop.org/wiki/Software/pkg-config/)
124* [double-conversion (2.0.1 -> )](https://github.com/google/double-conversion/)
125
126### Getting the source code
127
128Install git (https://git-scm.com/) onto your system. Then run a clone:
129
130    git clone https://github.com/openscad/openscad.git
131
132This will download the latest sources into a directory named `openscad`.
133
134To pull the MCAD library (https://github.com/openscad/MCAD), do the following:
135
136    cd openscad
137    git submodule update --init
138
139### Building for macOS
140
141Prerequisites:
142
143* Xcode
144* automake, libtool, cmake, pkg-config, wget (we recommend installing these using Homebrew)
145
146Install Dependencies:
147
148After building dependencies using one of the following options, follow the instructions in the *Compilation* section.
149
1501. **From source**
151
152    Run the script that sets up the environment variables:
153
154        source scripts/setenv-macos.sh
155
156    Then run the script to compile all the dependencies:
157
158        ./scripts/macosx-build-dependencies.sh
159
1601. **Homebrew** (assumes [Homebrew](https://brew.sh/) is already installed)
161
162        ./scripts/macosx-build-homebrew.sh
163
164### Building for Linux/BSD
165
166First, make sure that you have git installed (often packaged as 'git-core' 
167or 'scmgit'). Once you've cloned this git repository, download and install 
168the dependency packages listed above using your system's package 
169manager. A convenience script is provided that can help with this 
170process on some systems:
171
172    sudo ./scripts/uni-get-dependencies.sh
173
174After installing dependencies, check their versions. You can run this 
175script to help you:
176
177    ./scripts/check-dependencies.sh
178
179Take care that you don't have old local copies anywhere (`/usr/local/`). 
180If all dependencies are present and of a high enough version, skip ahead 
181to the Compilation instructions. 
182
183### Building for Linux/BSD on systems with older or missing dependencies
184
185If some of your system dependency libraries are missing or old, then you 
186can download and build newer versions into `$HOME/openscad_deps` by 
187following this process. First, run the script that sets up the 
188environment variables. 
189
190    source ./scripts/setenv-unibuild.sh
191
192Then run the script to compile all the prerequisite libraries above:
193
194    ./scripts/uni-build-dependencies.sh
195
196Note that huge dependencies like gcc, qt, or glib2 are not included 
197here, only the smaller ones (boost, CGAL, opencsg, etc). After the 
198build, again check dependencies.
199
200    ./scripts/check-dependencies.sh
201
202After that, follow the Compilation instructions below.
203
204### Building for Windows
205
206OpenSCAD for Windows is usually cross-compiled from Linux. If you wish to
207attempt an MSVC build on Windows, please see this site:
208https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Building_on_Windows
209
210To cross-build, first make sure that you have all necessary dependencies 
211of the MXE project ( listed at https://mxe.cc/#requirements ). Don't install
212MXE itself, the scripts below will do that for you under `$HOME/openscad_deps/mxe`
213
214Then get your development tools installed to get GCC. Then after you've 
215cloned this git repository, start a new clean bash shell and run the 
216script that sets up the environment variables.
217
218    source ./scripts/setenv-mingw-xbuild.sh 64
219
220Then run the script to download & compile all the prerequisite libraries above:
221
222    ./scripts/mingw-x-build-dependencies.sh 64
223
224Note that this process can take several hours, and tens of gigabytes of 
225disk space, as it uses the [https://mxe.cc](https://mxe.cc) system to cross-build many
226libraries. After it is complete, build OpenSCAD and package it to an 
227installer:
228
229    ./scripts/release-common.sh mingw64
230
231For a 32-bit Windows cross-build, replace 64 with 32 in the above instructions. 
232
233### Compilation
234
235First, run `mkdir build && cd build && cmake .. -DEXPERIMENTAL=1` to generate a Makefile.
236
237Then run `make -j`. Finally, on Linux you might run `make install` as root.
238
239If you had problems compiling from source, raise a new issue in the
240[issue tracker on the github page](https://github.com/openscad/openscad/issues).
241
242This site and it's subpages can also be helpful:
243https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Building_OpenSCAD_from_Sources
244
245Once built, you can run tests with `cd build/tests && ctest -j`.
246
247### Running CI workflows locally
248
249*   Install [circleci-cli](https://circleci.com/docs/2.0/local-cli/) (you'll need an API key)
250
251    *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](https://github.com/nektos/act) doesn't like our submodule setup anyway.
252
253*   Run the CI jobs
254
255	```bash
256	# When "successful", these will fail to upload at the very end of the workflow.
257	circleci local execute --job  openscad-mxe-64bit
258	circleci local execute --job  openscad-mxe-32bit
259	circleci local execute --job  openscad-appimage-64bit
260	```
261
262	*Note*: openscad-macos can't be built locally.
263
264*   If/when GCC gets randomly killed, give docker more RAM (e.g. 4GB per concurrent image you plan to run)
265
266*   To debug the jobs more interactively, you can go the manual route (inspect .circleci/config.yml to get the actual docker image you need)
267
268	```bash
269	docker run --entrypoint=/bin/bash -it openscad/mxe-x86_64-gui:latest
270	```
271
272	Then once you get the console:
273	
274	```bash
275	git clone https://github.com/%your username%/openscad.git workspace
276	cd workspace
277	git checkout %your branch%
278	git submodule init
279	git submodule update
280
281	# Then execute the commands from .circleci/config.yml:
282	#    export NUMCPU=2
283	#    ...
284	#    ./scripts/release-common.sh -snapshot -mingw64 -v "$OPENSCAD_VERSION"
285	```
286