radiant/layouts: add a single-window layout
[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**  |**Yes**   |**Yes**  |_GCC or Clang_                                |
22 |Windows  |**Yes**  |**Yes**   |**Yes**  |_MSYS2/Mingw64 or Mingw32_                    |
23 |Wine     |-        |-         |**Yes**  |-                                             |
24 |macOS    |**Yes**  |**Yes**   |**Yes**  |_Homebrew, GCC or Clang and builtin GtkGLExt_ |
25
26 NetRadiant is known to build and run properly on Linux, FreeBSD and Windows using MSYS2, and build on macOS with Homebrew (some bugs are known though). Windows build is known to work well on wine, which can be used as a fallback on some system.
27
28 At this time library bundling is supported on Linux, FreeBSD, Windows/MSYS2, and macOS/Homebrew. Since bundling copies things from the host, a clean build environment has to be used in order to get a clean bundle. Linux and FreeBSD bundles do not ship GTK: users are expected to have a working GTK environment with GtkGLExt installed, usually installing GtkGLExt is enough to pull everything that is required.
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 by using the `git` command line 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 ### FreeBSD:
88
89 ```sh
90 pkg install cmake gtkglext pkgconf minizip webp coreutils gsed git subversion wget unzip
91 ```
92
93 If you plan to build a bundle, you also need to install `patchelf`
94
95
96 ### macOS:
97
98 Note: some dependencies of gtk+ seems to only be pulled with gtk+3, gtkglext seems to require libffi.
99
100 ```sh
101 brew install cmake glib libffi gtk+ gtk+3 pkgconfig minizip webp coreutils gnu-sed wget sassc
102 brew link --force gettext
103 ```
104
105
106 ## Submodules
107
108  * Crunch (optional, not built if submodule is not present)
109
110 If you have not used `--recursive` option at `git clone` time, you can fetch Crunch this way (run this within the `netradiant` repository):
111
112 ```sh
113 git submodule update --init --recursive
114 ```
115
116
117 ## Simple compilation
118
119 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.
120
121
122 ### Easy builder assistant
123
124 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:
125
126 ```sh
127 ./easy-builder
128 ```
129
130 If everything went right, you'll find your netradiant build in `install/` subdirectory.
131
132 If you need to build a debug build (to get help from a developer, for example), you can do it this way:
133
134 ```sh
135 ./easy-builder --debug
136 ```
137
138 By default, build tools and compilers are using the `build/` directory as workspace.
139
140 For supported system, bundling dependencies can be done this way:
141
142 ```sh
143 ./easy-builder -DBUNDLE_LIBRARIES=ON
144 ```
145
146 Note: always do bundling on a clean system without unrelated software installed.
147
148
149 ## Advanced compilation
150
151 ### Initial build
152
153 This project uses the usual CMake workflow:
154
155
156 #### Debug build
157
158 ```sh
159 cmake -G "Unix Makefiles" -S. -Bbuild -DCMAKE_BUILD_TYPE=Debug
160 cmake --build build -- -j$(nproc)
161 ```
162
163
164 #### Release build
165
166 ```sh
167 cmake -G "Unix Makefiles" -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
168 cmake --build build -- -j$(nproc)
169 ```
170
171 Note: macOS users need to build built-in GtkGLExt before building NetRadiant:
172
173 ```sh
174 cmake -G "Unix Makefiles" -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
175 cmake --build build -- -j$(nproc) builtins
176 cmake -G "Unix Makefiles" -S. -Bbuild
177 cmake --build build -- -j$(nproc)
178 ```
179
180
181 ### Subsequent builds
182
183 The initial build will download the gamepacks and build NetRadiant and tools. If you frequently recompile you can skip downloading the gamepacks:
184
185 ```sh
186 cmake --build build --target binaries -- -j$(nproc)
187 ```
188
189 You should still periodically update gamepacks:
190
191 ```sh
192 cmake --build build --target gamepacks
193 ```
194
195
196 ### Build and installation details
197
198 #### Compilation details
199
200 Options:
201
202 * `BUILD_RADIANT=OFF`  
203   Do not build NetRadiant (default: `ON`, build netradiant graphical editor);
204 * `BUILD_TOOLS=OFF`  
205   Do not build q3map2 and other tools (default: `ON`, build command line tools);
206 * `BUILD_DAEMONMAP=OFF`  
207   Do not build daemonmap tool (default: `ON` if submodule is there, buils daemonmap navigation mesh generator);
208 * `BUILD_CRUNCH=OFF`  
209   Disable crunch support (default: `ON` if submodule is there, enable crunch support);
210 * `RADIANT_ABOUTMSG="Custom build by $(whoami)"`  
211   A message shown in the about dialog (default: `Custom build`).
212
213 Targets:
214
215 * `binaries`            Compile all binaries;
216   - `netradiant`        Compile the netradiant editor;
217   - `modules`           Compile all modules (each module has its own target as well);
218   - `plugins`           Compile all plugins (each plugin has its own target as well);
219   - `tools`             Compile all tools (each tool has its own target as well);
220      * `quake2`         Compile all the Quake 2 tools: `q2map`, `qdata3`;
221      * `heretic2`       Compile all the Heretic2 tools: `q2map`, `h2data`;
222      * `quake3`         Compile all the Quake 3 tools:
223          - `q3map2`     Compile the Quake 3 map compiler;
224          - `q3data`     Compile the q3data tool;
225      * `unvanquished`   Compile all the Unvanquished tools: `daemonmap`, `q3map3`, `q4data`;
226          - `daemonmap`  Compile the daemonmap navigation mesh generator.
227
228 Type `make help` to get an exhaustive list of targets.
229
230
231 #### Download details
232
233 Options:
234
235 * `DOWNLOAD_GAMEPACKS=OFF`  
236   Do not automatically download the gamepack data on each compilation and do not install already downloaded game packs (default: `ON`);
237 * `GAMEPACKS_LICENSE_LIST=all`  
238   Download all gamepacks whatever their license (default: `free`, download free gamepacks, can be set to `none` to only filter by name);
239 * `GAMEPACKS_NAME_LIST="Xonotic Unvanquished"`  
240   Download gamepacks for the given games (default: `none`, do not select more gamepacks to download).
241
242 Target:
243
244 * `gamepacks` Downloads the game pack data.
245
246 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.
247
248
249 #### Installation details
250
251 Options:
252
253 * `BUNDLE_LIBRARIES=ON`  
254   Bundle libraries, only Linux, FreeBSD, macOS and MSYS2 are supported at this time (default: `OFF`);
255 * `FHS_INSTALL=ON` (available on POSIX systems)  
256   Install files following the Filesystem Hierarchy Standard (`bin`, `lib`, `share`, etc.)  
257   Also setup XDG mime and application support on Linux-like systems (default: `OFF`, install like in 1999);
258 * `CMAKE_INSTALL_PREFIX=/usr`  
259   Install system-wide on Posix systems, always set `FHS_INSTALL` to `ON` when doing this (default: `install/` directory within source tree).
260
261 Target:
262
263 * `install` Install files.
264
265
266 ## Additonnal information
267
268 ### About Crunch
269
270 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.