README.md

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