From 25256136549cd4b7f3c7fadc5f72be418f5bc720 Mon Sep 17 00:00:00 2001 From: Thomas Debesse Date: Tue, 23 Jul 2019 07:16:57 +0200 Subject: [PATCH] readme: lots of improvements - compatibility matrix - Ubuntu build requirements - a lot of rewrites --- README.md | 194 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 107 insertions(+), 87 deletions(-) diff --git a/README.md b/README.md index ebeccebc..dfcbcb04 100644 --- a/README.md +++ b/README.md @@ -3,188 +3,208 @@ NetRadiant ![NetRadiant logo](setup/data/tools/bitmaps/splash.png) -The open source, cross platform level editor for id Tech-derivated games (Radiant fork). +The open source, cross platform level editor for id Tech-derivated games (has lineage from GtkRadiant). -# Getting the sources +## Compatibility -The latest source is available from the git repository: +|System |Build |Bundle |Run |Build requirements | +|---------|---------|---------|---------|---------------------------| +|Linux |**Yes** |**Yes** |**Yes** |_GCC or LLVM/clang_ | +|FreeBSD |**Yes** |_not yet_|**Yes** |_GCC_ | +|Windows |**Yes** |**Yes** |**Yes** |_MSYS2/Mingw64 or Mingw32_ | +|Wine |- |- |**Yes** |- | +|macOS |**Yes** |_not yet_|_mostly_ |_GCC and patched GtkGLext_ | -https://gitlab.com/xonotic/netradiant.git +NetRadiant is known to build and run properly on Linux, FreeBSD and Windows using MSYS2. NetRadiant is known to build on macOS, 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 that system. At this time library bundling is only supported on Windows/MSYS2 and Linux. Linux bundles do not ship GTK (users are espected to have a working GTK with GtkGlExt environment). -The git client can be obtained from the Git website: -http://git-scm.org +## Getting the sources -To get a copy of the source using the command line git client: +Source browser, issues and more can be found on the gitlab project: https://gitlab.com/xonotic/netradiant/ -``` +The latest source is available from the git repository: `https://gitlab.com/xonotic/netradiant.git` + +The `git` client can be obtained from the Git website: http://git-scm.org + +A copy of the source tree can be fetched using the command line `git` client this way: + +```sh git clone --recursive https://gitlab.com/xonotic/netradiant.git cd netradiant ``` -See also https://gitlab.com/xonotic/netradiant/ for a source browser, issues and more. -# Dependencies +## Dependencies + +* OpenGL, LibXml2, GTK2, GtkGLExt, LibJpeg, LibPng, LibWebp, Minizip, ZLib. + +To fetch default game packages you'll need Git, Subversion and `unzip`. + +### Ubuntu: + +```sh +apt-get install --reinstall build-essential cmake lib{x11,gtk2.0,gtkglext1,xml2,jpeg,webp,minizip}-dev git subversion unzip wget +``` -* OpenGL -* LibXml2 -* GTK2 -* GtkGLExt -* LibJpeg -* LibPng -* LibWebp -* Minizip -* ZLib +If you plan to build a bundle, you also need to install `uuid-runtime patchelf` -To fetch default game packages you'll need Git and to fetch some optional ones you'll need Subversion. +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` -## MSYS2 +### MSYS2: Under MSYS2, the mingw shell must be used. -If you use MSYS2 over SSH, add `mingw64` to the path this way (given you compile for 64 bit Windows): +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): -``` +```sh export PATH="/mingw64/bin:${PATH}"` ``` Install the dependencies this way: - -``` -pacman -S --needed base-devel mingw-w64-$(uname -m)-{ntldd-git,toolchain,cmake,make,gtk2,gtkglext,libwebp,minizip-git} git +```sh +pacman -S --needed base-devel mingw-w64-$(uname -m)-{ntldd-git,subversion,unzip,toolchain,cmake,make,gtk2,gtkglext,libwebp,minizip-git} git ``` -Explicitely use `mingw-w64-x86_64-` or `mingw-w64-i686-` prefix if you need to target a non-default architecture. +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. -You may have to install `subversion` and `unzip` to fetch or extract some non-default game packages. +### macOS: -## macOS: - -``` +```sh brew install gcc cmake gtkglext pkgconfig minizip webp coreutils gnu-sed brew link --force gettext ``` -# Submodules + +## Submodules * Crunch (optional, disabled by default, only supported with CMake build) If you have not used `--recursive` option at `git clone` time, you can fetch Crunch this way (run it within the `netradiant` repository): - -``` +```sh git submodule update --init --recursive ``` -# Compiling -## Initial build +## Compiling + +### Initial build This project uses the usual CMake workflow: -### Debug -``` -cmake -G "Unix Makefiles" -H. -Bbuild -DCMAKE_BUILD_TYPE=Debug && cmake --build build -- -j$(nproc) +#### Debug build + +```sh +cmake -G "Unix Makefiles" -H. -Bbuild -DCMAKE_BUILD_TYPE=Debug +cmake --build build -- -j$(nproc) ``` -### Release -``` -cmake -G "Unix Makefiles" -H. -Bbuild -DCMAKE_BUILD_TYPE=Release && cmake --build build -- -j$(nproc) +#### Release build + +```sh +cmake -G "Unix Makefiles" -H. -Bbuild -DCMAKE_BUILD_TYPE=Release +cmake --build build -- -j$(nproc) ``` On macOS you have to add this to the first cmake call: -``` +```sh -DCMAKE_C_COMPILER=/usr/local/bin/gcc-9 -DCMAKE_CXX_COMPILER=/usr/local/bin/g++-9 ``` On FreeBSD you have to add this to the first cmake call: -``` +```sh -DCMAKE_C_COMPILER=/usr/local/bin/gcc8 -DCMAKE_CXX_COMPILER=/usr/local/bin/g++8 ``` -## Subsequent builds + +### Subsequent builds The initial build will download the gamepacks and build NetRadiant and tools. If you frequently recompile you can skip downloading the gamepacks: -``` +```sh cmake --build build --target binaries -- -j$(nproc) ``` You should still periodically update gamepacks: -``` +```sh cmake --build build --target gamepacks ``` -## Build and installation details -### Compilation details +### Build and installation details + +#### Compilation details -options: +Options: -* `BUNDLE_LIBRARIES=ON` - Bundle libraries (only MSYS2 is supported at this time) * `BUILD_RADIANT=OFF` - Do not build NetRadiant (default: `ON`, build netradiant graphical editor) + Do not build NetRadiant (default: `ON`, build netradiant graphical editor); * `BUILD_TOOLS=OFF` - Do not build q3map2 and other tools (default: `ON`, build command line tools) + Do not build q3map2 and other tools (default: `ON`, build command line tools); * `BUILD_CRUNCH=ON` - Enable crunch support (default: `OFF`, disable crunch support) -* `RADIANT_ABOUTMSG="Custom build"` - A message shown in the about dialog - -targets: - -* `binaries` Compiles all binaries - - `netradiant` Compiles the netradiant editor - - `modules` Compiles all modules (each module has its own target as well) - - `plugins` Compiles all plugins (each plugin has its own target as well) - - `tools` Compiles all tools (each tool has its own target as well) - * `quake2` Compiles all the Quake2 tools: `q2map`, `qdata3` - * `heretic2` Compiles all the Heretic2 tools: `q2map`, `h2data` - * `quake3` Compiles all the Quake3 tools: - - `q3map2` Compiles the quake3 map compiler - - `q3data` Compiles the q3data tool + Enable crunch support (default: `OFF`, disable crunch support); +* `RADIANT_ABOUTMSG="Custom build by $(whoami)"` + A message shown in the about dialog (default: `Custom build`). + +Targets: + +* `binaries` Compiles all binaries; + - `netradiant` Compiles the netradiant editor; + - `modules` Compiles all modules (each module has its own target as well); + - `plugins` Compiles all plugins (each plugin has its own target as well); + - `tools` Compiles all tools (each tool has its own target as well); + * `quake2` Compiles all the Quake 2 tools: `q2map`, `qdata3`; + * `heretic2` Compiles all the Heretic2 tools: `q2map`, `h2data`; + * `quake3` Compiles all the Quake 3 tools: + - `q3map2` Compiles the quake3 map compiler; + - `q3data` Compiles the q3data tool. Type `make help` to get an exhaustive list of targets. -### Download details +#### Download details -options: +Options: * `DOWNLOAD_GAMEPACKS=OFF` - Do not automatically download the gamepack data on each compilation and do not install game packs already downloaded (default: `ON`) + Do not automatically download the gamepack data on each compilation and do not install game packs already downloaded (default: `ON`); * `GAMEPACKS_LICENSE_LIST=all` - Download all gamepacks whatever the license (default: `free`, download free gamepacks, can be set to `none` to only filter by name) + Download all gamepacks whatever the license (default: `free`, download free gamepacks, can be set to `none` to only filter by name); * `GAMEPACKS_NAME_LIST="Xonotic Unvanquished"` - Download gamepacks for the given games (default: `none`, do not select more gamepacks to download) + Download gamepacks for the given games (default: `none`, do not select more gamepacks to download). -target: +Target: -* `gamepacks` Downloads the game pack data +* `gamepacks` Downloads the game pack data. -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 proprietary Quake 3 one. +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. -### Installation details -options: +#### Installation details -* `FHS_INSTALL=ON` - Available for POSIX systems: install files following the Filesystem Hierarchy Standard (bin, lib, share, etc.), also setup XDG mime and application support on Linux-like systems (default: `OFF`, install like in 1999) +Options: + +* `BUNDLE_LIBRARIES=ON` + Bundle libraries, only MSYS2 is supported at this time (default: `OFF`); +* `FHS_INSTALL=ON` (available on POSIX systems) + Install files following the Filesystem Hierarchy Standard (`bin`, `lib`, `share`, etc.) + Also setup XDG mime and application support on Linux-like systems (default: `OFF`, install like in 1999); * `CMAKE_INSTALL_PREFIX=/usr` - Install system-wide on Posix systems, always set `FHS_INSTALL` to `ON` when doing this (default: install in `install/` directory within source tree) + Install system-wide on Posix systems, always set `FHS_INSTALL` to `ON` when doing this (default: `install/` directory within source tree). + +Target: + +* `install` Install files. -target: -* `install` - Install files +## Additonnal notes -## Note about Crunch +### About Crunch 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. -- 2.39.2