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 It's possible to build against GTK3 using the `-DGTK_TARGET=3` cmake option, but some problems may be encountered, see [GUI/GTK](https://gitlab.com/xonotic/netradiant/-/issues?label_name[]=GUI%2FGTK3) issues. GTK2 remains recommended for now.
  54
  55
  56 ### Ubuntu:
  57
  58 ```sh
  59 apt-get install --reinstall build-essential cmake \
  60     lib{x11,gtk2.0,gtkglext1,xml2,jpeg,webp,minizip}-dev \
  61     git subversion unzip wget
  62 ```
  63
  64 If you plan to build a bundle, you also need to install `uuid-runtime patchelf`
  65
  66 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`
  67
  68
  69 ### MSYS2:
  70
  71 Under MSYS2, the mingw shell must be used.
  72
  73 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):
  74
  75 ```sh
  76 export PATH="/mingw64/bin:${PATH}"
  77 ```
  78
  79 Install the dependencies this way:
  80
  81 ```sh
  82 pacman -S --needed base-devel git subversion unzip \
  83     mingw-w64-$(uname -m)-{ntldd-git,toolchain,cmake,make,gtk2,gtkglext,libwebp,minizip-git}
  84 ```
  85
  86 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.
  87
  88
  89 ### FreeBSD:
  90
  91 ```sh
  92 pkg install cmake gtkglext pkgconf minizip webp coreutils gsed git subversion wget unzip
  93 ```
  94
  95 If you plan to build a bundle, you also need to install `patchelf`
  96
  97
  98 ### macOS:
  99
 100 Note: some dependencies of gtk+ seems to only be pulled with gtk+3, gtkglext seems to require libffi.
 101
 102 ```sh
 103 brew install cmake glib gobject-introspection libffi gtk+ gtk+3 gtk-doc pkgconfig minizip webp coreutils gnu-sed wget sassc
 104 brew link --force gettext
 105 ```
 106
 107
 108 ## Submodules
 109
 110  * Crunch (optional, not built if submodule is not present)
 111
 112 If you have not used `--recursive` option at `git clone` time, you can fetch Crunch this way (run this within the `netradiant` repository):
 113
 114 ```sh
 115 git submodule update --init --recursive
 116 ```
 117
 118
 119 ## Simple compilation
 120
 121 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.
 122
 123
 124 ### Easy builder assistant
 125
 126 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:
 127
 128 ```sh
 129 ./easy-builder
 130 ```
 131
 132 If everything went right, you'll find your netradiant build in `install/` subdirectory.
 133
 134 If you need to build a debug build (to get help from a developer, for example), you can do it this way:
 135
 136 ```sh
 137 ./easy-builder --debug
 138 ```
 139
 140 By default, build tools and compilers are using the `build/` directory as workspace.
 141
 142 For supported system, bundling dependencies can be done this way:
 143
 144 ```sh
 145 ./easy-builder -DBUNDLE_LIBRARIES=ON
 146 ```
 147
 148 Note: Always do bundling on a clean and fresh system without unrelated software installed.
 149
 150
 151 ## Advanced compilation
 152
 153 ### Initial build
 154
 155 This project uses the usual CMake workflow:
 156
 157
 158 #### Debug build
 159
 160 ```sh
 161 cmake -G "Unix Makefiles" -S. -Bbuild -DCMAKE_BUILD_TYPE=Debug
 162 cmake --build build -- -j$(nproc)
 163 cmake --install build
 164 ```
 165
 166
 167 #### Release build
 168
 169 ```sh
 170 cmake -G "Unix Makefiles" -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
 171 cmake --build build -- -j$(nproc)
 172 cmake --install build
 173 ```
 174
 175 Note: macOS users need to build built-in GtkGLExt before building NetRadiant:
 176
 177 ```sh
 178 cmake -G "Unix Makefiles" -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
 179 cmake --build build -- -j$(nproc) builtins
 180 cmake -G "Unix Makefiles" -S. -Bbuild
 181 cmake --build build -- -j$(nproc)
 182 cmake --install build
 183 ```
 184
 185
 186 ### Subsequent builds
 187
 188 The initial build will download the gamepacks and build NetRadiant and tools. If you frequently recompile you can skip downloading the gamepacks:
 189
 190 ```sh
 191 cmake --build build --target binaries -- -j$(nproc)
 192 cmake --install build
 193 ```
 194
 195 You should still periodically update gamepacks:
 196
 197 ```sh
 198 cmake --build build --target gamepacks
 199 cmake --install build
 200 ```
 201
 202
 203 ### Build and installation details
 204
 205 #### Compilation details
 206
 207 Options:
 208
 209 * `BUILD_RADIANT=OFF`
 210   Do not build NetRadiant (default: `ON`, build netradiant graphical editor);
 211 * `BUILD_TOOLS=OFF`
 212   Do not build q3map2 and other tools (default: `ON`, build command line tools);
 213 * `BUILD_CRUNCH=OFF`
 214   Disable crunch support (default: `ON` if submodule is there, enable crunch support);
 215 * `RADIANT_ABOUTMSG="Custom build by $(whoami)"`
 216   A message shown in the about dialog (default: `Custom build`).
 217
 218 Targets:
 219
 220 * `binaries`            Compile all binaries;
 221   - `netradiant`        Compile the netradiant editor;
 222   - `modules`           Compile all modules (each module has its own target as well);
 223   - `plugins`           Compile all plugins (each plugin has its own target as well);
 224   - `tools`             Compile all tools (each tool has its own target as well);
 225      * `quake2`         Compile all the Quake 2 tools: `q2map`, `qdata3`;
 226      * `heretic2`       Compile all the Heretic2 tools: `q2map`, `h2data`;
 227      * `quake3`         Compile all the Quake 3 tools:
 228          - `q3map2`     Compile the Quake 3 map compiler;
 229          - `q3data`     Compile the q3data tool;
 230
 231 Type `make help` to get an exhaustive list of targets.
 232
 233
 234 #### Download details
 235
 236 Options:
 237
 238 * `DOWNLOAD_GAMEPACKS=OFF`
 239   Do not automatically download the gamepack data on each compilation and do not install already downloaded game packs (default: `ON`);
 240 * `GAMEPACKS_LICENSE_LIST=all`
 241   Download all gamepacks whatever their license (default: `free`, download free gamepacks, can be set to `none` to only filter by name);
 242 * `GAMEPACKS_NAME_LIST="Xonotic Unvanquished"`
 243   Download gamepacks for the given games (default: `none`, do not select more gamepacks to download).
 244
 245 Target:
 246
 247 * `gamepacks` Downloads the game pack data.
 248
 249 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.
 250
 251
 252 #### Installation details
 253
 254 Options:
 255
 256 * `BUNDLE_LIBRARIES=ON`
 257   Bundle libraries, only Linux, FreeBSD, macOS and MSYS2 are supported at this time (default: `OFF`);
 258 * `FHS_INSTALL=ON` (available on POSIX systems)
 259   Install files following the Filesystem Hierarchy Standard (`bin`, `lib`, `share`, etc.)
 260   Also setup XDG mime and application support on Linux-like systems (default: `OFF`, install like in 1999);
 261 * `CMAKE_INSTALL_PREFIX=/usr`
 262   Install system-wide on Posix systems, always set `FHS_INSTALL` to `ON` when doing this (default: `install/` directory within source tree).
 263
 264 Target:
 265
 266 * `install` Install files.
 267
 268 ```sh
 269 cmake --install build
 270 ```
 271
 272
 273 ## Additional information
 274
 275 ### About Crunch
 276
 277 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.