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**  |**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 only supported on Linux, 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 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 glib gtk+ 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
 111 ### Easy builder assistant
 112
 113 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:
 114
 115 ```sh
 116 ./easy-builder
 117 ```
 118
 119 If everything went right, you'll find your netradiant build in `install/` subdirectory.
 120
 121 If you need to build a debug build (to get help from a developer, for example), you can do it this way:
 122
 123 ```sh
 124 ./easy-builder --debug
 125 ```
 126
 127 By default, build tools and compilers are using the `build/` directory as workspace.
 128
 129 For supported system, bundling dependencies can be done this way:
 130
 131 ```sh
 132 ./easy-builder -DBUNDLE_LIBRARIES=ON
 133 ```
 134
 135 Note: always do bundling on clean system without unrelated software installed.
 136
 137
 138 ## Advanced compilation
 139
 140 ### Initial build
 141
 142 This project uses the usual CMake workflow:
 143
 144
 145 #### Debug build
 146
 147 ```sh
 148 cmake -G "Unix Makefiles" -S. -Bbuild -DCMAKE_BUILD_TYPE=Debug
 149 cmake --build build -- -j$(nproc)
 150 ```
 151
 152
 153 #### Release build
 154
 155 ```sh
 156 cmake -G "Unix Makefiles" -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
 157 cmake --build build -- -j$(nproc)
 158 ```
 159
 160 Note: macOS users need to build built-in GtkGLExt before building NetRadiant:
 161
 162 ```sh
 163 cmake -G "Unix Makefiles" -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
 164 cmake --build build -- -j$(nproc) builtins
 165 cmake -G "Unix Makefiles" -S. -Bbuild
 166 cmake --build build -- -j$(nproc)
 167 ```
 168
 169
 170 ### Subsequent builds
 171
 172 The initial build will download the gamepacks and build NetRadiant and tools. If you frequently recompile you can skip downloading the gamepacks:
 173
 174 ```sh
 175 cmake --build build --target binaries -- -j$(nproc)
 176 ```
 177
 178 You should still periodically update gamepacks:
 179
 180 ```sh
 181 cmake --build build --target gamepacks
 182 ```
 183
 184
 185 ### Build and installation details
 186
 187 #### Compilation details
 188
 189 Options:
 190
 191 * `BUILD_RADIANT=OFF`
 192   Do not build NetRadiant (default: `ON`, build netradiant graphical editor);
 193 * `BUILD_TOOLS=OFF`
 194   Do not build q3map2 and other tools (default: `ON`, build command line tools);
 195 * `BUILD_DAEMONMAP=OFF`
 196   Do not build daemonmap tool (default: `ON` if submodule is there, buils daemonmap navigation mesh generator);
 197 * `BUILD_CRUNCH=OFF`
 198   Disable crunch support (default: `ON` if submodule is there, enable crunch support);
 199 * `RADIANT_ABOUTMSG="Custom build by $(whoami)"`
 200   A message shown in the about dialog (default: `Custom build`).
 201
 202 Targets:
 203
 204 * `binaries`            Compile all binaries;
 205   - `netradiant`        Compile the netradiant editor;
 206   - `modules`           Compile all modules (each module has its own target as well);
 207   - `plugins`           Compile all plugins (each plugin has its own target as well);
 208   - `tools`             Compile all tools (each tool has its own target as well);
 209      * `quake2`         Compile all the Quake 2 tools: `q2map`, `qdata3`;
 210      * `heretic2`       Compile all the Heretic2 tools: `q2map`, `h2data`;
 211      * `quake3`         Compile all the Quake 3 tools:
 212          - `q3map2`     Compile the Quake 3 map compiler;
 213          - `q3data`     Compile the q3data tool;
 214      * `unvanquished`   Compile all the Unvanquished tool: `daemonmap`, `q3map3`, `q4data`;
 215          - `daemonmap`  Compile the daemonmap navigation mesh generator.
 216
 217 Type `make help` to get an exhaustive list of targets.
 218
 219
 220 #### Download details
 221
 222 Options:
 223
 224 * `DOWNLOAD_GAMEPACKS=OFF`
 225   Do not automatically download the gamepack data on each compilation and do not install game packs already downloaded (default: `ON`);
 226 * `GAMEPACKS_LICENSE_LIST=all`
 227   Download all gamepacks whatever the license (default: `free`, download free gamepacks, can be set to `none` to only filter by name);
 228 * `GAMEPACKS_NAME_LIST="Xonotic Unvanquished"`
 229   Download gamepacks for the given games (default: `none`, do not select more gamepacks to download).
 230
 231 Target:
 232
 233 * `gamepacks` Downloads the game pack data.
 234
 235 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.
 236
 237
 238 #### Installation details
 239
 240 Options:
 241
 242 * `BUNDLE_LIBRARIES=ON`
 243   Bundle libraries, only MSYS2 and Linux are supported at this time (default: `OFF`);
 244 * `FHS_INSTALL=ON` (available on POSIX systems)
 245   Install files following the Filesystem Hierarchy Standard (`bin`, `lib`, `share`, etc.)
 246   Also setup XDG mime and application support on Linux-like systems (default: `OFF`, install like in 1999);
 247 * `CMAKE_INSTALL_PREFIX=/usr`
 248   Install system-wide on Posix systems, always set `FHS_INSTALL` to `ON` when doing this (default: `install/` directory within source tree).
 249
 250 Target:
 251
 252 * `install` Install files.
 253
 254
 255 ## Additonnal information
 256
 257 ### About Crunch
 258
 259 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.