q3map2/light_bounce: prevent infinite loop on obscure bias compute
[xonotic/netradiant.git] / README.md
1 NetRadiant
2 ==========
3
4 [![NetRadiant logo](setup/data/tools/bitmaps/splash.png)](https://netradiant.gitlab.io)
5
6 The open source, cross platform level editor for id Tech-derivated games, heir of GtkRadiant.
7
8 Learn more on NetRadiant website: [netradiant.gitlab.io](https://netradiant.gitlab.io).
9
10
11 ## Download NetRadiant
12
13 Prebuilt binaries can be found on the [Download page](https://netradiant.gitlab.io/page/download/).
14
15
16 ## Compatibility matrix
17
18 |System   |Build    |Bundle    |Run      |Build requirements                            |
19 |---------|---------|----------|---------|----------------------------------------------|
20 |Linux    |**Yes**  |**Yes**   |**Yes**  |_GCC or Clang_                                |
21 |FreeBSD  |**Yes**  |_not yet_ |**Yes**  |_GCC or Clang_                                |
22 |Windows  |**Yes**  |**Yes**   |**Yes**  |_MSYS2/Mingw64 or Mingw32_                    |
23 |Wine     |-        |-         |**Yes**  |-                                             |
24 |macOS    |**Yes**  |_not yet_ |_mostly_ |_Homebrew, GCC or Clang and patched GtkGLExt_ |
25
26 NetRadiant is known to build and run properly on Linux, FreeBSD and Windows using MSYS2. NetRadiant is known to build on macOS using Homebrew, but can't display things properly without a modified GtkGLExt which is yet to be upstreamed, and issues are known. Windows build is known to work well on wine, which can be used as a fallback on macOS.
27
28 At this time library bundling is only supported on Windows/MSYS2 and Linux. Since bundling copies things from the host, a clean build environment has to be used in order to get a clean bundle. Linux bundle does not ship GTK (users are expected to have a working GTK environment with GtkGlExt installed).
29
30
31 ## Getting the sources
32
33 Source browser, issues and more can be found on the gitlab project: [gitlab.com/xonotic/netradiant](https://gitlab.com/xonotic/netradiant)
34
35 The latest source is available from the git repository: `https://gitlab.com/xonotic/netradiant.git`
36
37 The `git` client can be obtained from your distribution repository or from the Git website: [git-scm.org](http://git-scm.org)
38
39 A copy of the source tree can be obtained using the command line `git` client this way:
40
41 ```sh
42 git clone --recursive https://gitlab.com/xonotic/netradiant.git
43 cd netradiant
44 ```
45
46
47 ## Dependencies
48
49 * OpenGL, LibXml2, GTK2, GtkGLExt, LibJpeg, LibPng, LibWebp, Minizip, ZLib.
50
51 To fetch default game packages you'll need Git, Subversion, Wget and `unzip`.
52
53
54 ### Ubuntu:
55
56 ```sh
57 apt-get install --reinstall build-essential cmake \
58     lib{x11,gtk2.0,gtkglext1,xml2,jpeg,webp,minizip}-dev \
59     git subversion unzip wget
60 ```
61
62 If you plan to build a bundle, you also need to install `uuid-runtime patchelf`
63
64 This is enough to build NetRadiant but you may also install those extra packages to get proper GTK2 graphical and sound themes: `gnome-themes-extra gtk2-engines-murrine libcanberra-gtk-module`
65
66
67 ### MSYS2:
68
69 Under MSYS2, the mingw shell must be used.
70
71 If you use MSYS2 over SSH, add `mingw64` to the path this way (given you compile for 64 bit Windows, replace with `mingw32` if you target 32 bit Windows instead): 
72
73 ```sh
74 export PATH="/mingw64/bin:${PATH}"
75 ```
76
77 Install the dependencies this way:
78
79 ```sh
80 pacman -S --needed base-devel git \
81     mingw-w64-$(uname -m)-{ntldd-git,subversion,unzip,toolchain,cmake,make,gtk2,gtkglext,libwebp,minizip-git}
82 ```
83
84 Explicitely use `mingw-w64-x86_64-` or `mingw-w64-i686-` prefix instead of `mingw-w64-$(uname -m)` if you need to target a non-default architecture.
85
86
87 ### macOS:
88
89 ```sh
90 brew install cmake gtkglext pkgconfig minizip webp coreutils gnu-sed wget
91 brew link --force gettext
92 ```
93
94
95 ## Submodules
96
97  * Crunch (optional, not built if submodule is not present)
98
99 If you have not used `--recursive` option at `git clone` time, you can fetch Crunch this way (run this within the `netradiant` repository):
100
101 ```sh
102 git submodule update --init --recursive
103 ```
104
105
106 ## Simple compilation
107
108 It is required to first download the sources using `git` (do not use tarballs) and to have dependencies installed, see [Getting the sources](#getting-the-sources) and [Dependencies](#dependencies) above.
109
110 ### Easy builder assistant
111
112 If you have standard needs and use well-known platform and operating system, you may try the provided `easy-builder` script which may be enough for you, you can run it this way:
113
114 ```sh
115 ./easy-builder
116 ```
117
118 If everything went right, you'll find your netradiant build in `install/` subdirectory.
119
120 If you need to build a debug build (to get help from a developer, for example), you can do it this way:
121
122 ```sh
123 ./easy-builder --debug
124 ```
125
126 By default, build tools and compilers are using the `build/` directory as workspace.
127
128
129 ## Advanced compilation
130
131 ### Initial build
132
133 This project uses the usual CMake workflow:
134
135
136 #### Debug build
137
138 ```sh
139 cmake -G "Unix Makefiles" -S. -Bbuild -DCMAKE_BUILD_TYPE=Debug
140 cmake --build build -- -j$(nproc)
141 ```
142
143
144 #### Release build
145
146 ```sh
147 cmake -G "Unix Makefiles" -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
148 cmake --build build -- -j$(nproc)
149 ```
150
151 ### Subsequent builds
152
153 The initial build will download the gamepacks and build NetRadiant and tools. If you frequently recompile you can skip downloading the gamepacks:
154
155 ```sh
156 cmake --build build --target binaries -- -j$(nproc)
157 ```
158
159 You should still periodically update gamepacks:
160
161 ```sh
162 cmake --build build --target gamepacks
163 ```
164
165
166 ### Build and installation details
167
168 #### Compilation details
169
170 Options:
171
172 * `BUILD_RADIANT=OFF`  
173   Do not build NetRadiant (default: `ON`, build netradiant graphical editor);
174 * `BUILD_TOOLS=OFF`  
175   Do not build q3map2 and other tools (default: `ON`, build command line tools);
176 * `BUILD_DAEMONMAP=OFF`  
177   Do not build daemonmap tool (default: `ON` if submodule is there, buils daemonmap navigation mesh generator);
178 * `BUILD_CRUNCH=OFF`  
179   Disable crunch support (default: `ON` if submodule is there, enable crunch support);
180 * `RADIANT_ABOUTMSG="Custom build by $(whoami)"`  
181   A message shown in the about dialog (default: `Custom build`).
182
183 Targets:
184
185 * `binaries`            Compile all binaries;
186   - `netradiant`        Compile the netradiant editor;
187   - `modules`           Compile all modules (each module has its own target as well);
188   - `plugins`           Compile all plugins (each plugin has its own target as well);
189   - `tools`             Compile all tools (each tool has its own target as well);
190      * `quake2`         Compile all the Quake 2 tools: `q2map`, `qdata3`;
191      * `heretic2`       Compile all the Heretic2 tools: `q2map`, `h2data`;
192      * `quake3`         Compile all the Quake 3 tools:
193          - `q3map2`     Compile the Quake 3 map compiler;
194          - `q3data`     Compile the q3data tool;
195      * `unvanquished`   Compile all the Unvanquished tool: `daemonmap`, `q3map3`, `q4data`;
196          - `daemonmap`  Compile the daemonmap navigation mesh generator.
197
198 Type `make help` to get an exhaustive list of targets.
199
200
201 #### Download details
202
203 Options:
204
205 * `DOWNLOAD_GAMEPACKS=OFF`  
206   Do not automatically download the gamepack data on each compilation and do not install game packs already downloaded (default: `ON`);
207 * `GAMEPACKS_LICENSE_LIST=all`  
208   Download all gamepacks whatever the license (default: `free`, download free gamepacks, can be set to `none` to only filter by name);
209 * `GAMEPACKS_NAME_LIST="Xonotic Unvanquished"`  
210   Download gamepacks for the given games (default: `none`, do not select more gamepacks to download).
211
212 Target:
213
214 * `gamepacks` Downloads the game pack data.
215
216 Run `./gamepacks-manager -h` to know about available licenses and other available games. Both lists are merged, for example setting `GAMEPACKS_LICENSE_LIST=GPL` and `GAMEPACKS_NAME_LIST=Q3` will install both GPL gamepacks and the proprietary Quake 3 gamepack.
217
218
219 #### Installation details
220
221 Options:
222
223 * `BUNDLE_LIBRARIES=ON`  
224   Bundle libraries, only MSYS2 and Linux are supported at this time (default: `OFF`);
225 * `FHS_INSTALL=ON` (available on POSIX systems)  
226   Install files following the Filesystem Hierarchy Standard (`bin`, `lib`, `share`, etc.)  
227   Also setup XDG mime and application support on Linux-like systems (default: `OFF`, install like in 1999);
228 * `CMAKE_INSTALL_PREFIX=/usr`  
229   Install system-wide on Posix systems, always set `FHS_INSTALL` to `ON` when doing this (default: `install/` directory within source tree).
230
231 Target:
232
233 * `install` Install files.
234
235
236 ## Additonnal information
237
238 ### About Crunch
239
240 The crnlib used to decode `.crn` files is the one from [Dæmon](http://github.com/DaemonEngine/Daemon) which is the one by [Unity](https://github.com/Unity-Technologies/crunch/tree/unity) made cross-platform and slightly improved. Since Unity brokes compatibility with [BinomialLLC's legacy tree](https://github.com/BinomialLLC/crunch) it's required to use either the `crunch` tool from Dæmon or the one from Unity to compress textures that have to be read by radiant or q3map2.