docs/building.md

   1 # Building and running the project
   2
   3 ## Basic build requirements
   4
   5 * [CMake](https://cmake.org) version 3.8 or higher
   6   * On Windows: Make sure to check option for "add CMake to system path".
   7   * On Linux: If you need to build from source, [don't forget the `--system-curl` flag](https://github.com/ruslo/hunter/issues/328#issuecomment-198672048)!
   8 * Appropriate C++ build tools for your system:
   9   * XCode tools on Mac
  10   * MinGW on Windows
  11   * You might already be set on Linux, but if not you'll need to figure this one out yourself. 😃
  12
  13 ## Getting the project running
  14
  15 Optional first step: [define a `HUNTER_ROOT` environment variable](../hunter_installs/README.md) (useful if you're running multiple Hunter projects on the same machine).
  16
  17 The following steps will depend on your IDE/environment:
  18 * [Command line](#command-line)
  19 * [CLion](#clion)
  20 * [Xcode](#xcode)
  21 * [Visual Studio](#visual-studio)
  22
  23 ### Command line
  24
  25 From the project directory:
  26
  27 1. Generate the project: `cmake -H. -B_builds`
  28 2. Compile and link: `cmake --build _builds`
  29 3. Enter the `bin/` directory: `cd bin/` (the working directory is important for program function)
  30 4. Run the program: `./proceduralworld`
  31
  32 #### Debug mode
  33
  34 If you want debug console output you can pass some extra flags during the generate and build steps:
  35 * Generate project: `cmake -H. -B_builds -DHUNTER_STATUS_DEBUG=ON -DCMAKE_BUILD_TYPE=Debug`
  36 * Build: `cmake --build _builds --config Debug`
  37
  38 ### CLion
  39
  40 CLion is a recommended IDE since it's built for handling CMake projects. However, it costs money. If you need a free 1-year student license you can get that [here](https://www.jetbrains.com/shop/eform/students).
  41
  42 #### Windows only: MinGW setup
  43
  44 1. Download and install MinGW ([click here to install](http://www.mingw.org/download/installer?)).
  45 2. When installation is done hit continue.
  46 3. Select `mingw32-base`, `mingw32-gcc-g++`, and `msys-base`.
  47 4. `Installation -> Apply Changes -> Apply` to download and install the relevant packages.
  48 5. When you see "All changes were applied successfully", hit close and exit the installation manager.
  49
  50 #### All platforms: building and running in CLion
  51
  52 1. On startup select "Open Project", and select the project directory.
  53 2. Once the project is opened, it should automatically build.
  54 4. *Possible Windows error:* if you see a message similar to, `For MinGW to work correctly C:\Program Files\OpenSSH\bin\sh.exe must NOT be in your PATH` go to `File -> Settings -> Appearance & Behavior -> Path Variables` and add `PATH` to the Ignored Variables, hit OK, and try again.
  55 5. Press the green play button to build and run the program.
  56
  57 ### Xcode
  58
  59 Before you open the project in Xcode, you'll need to generate project files using CMake.
  60
  61 #### CMake GUI
  62
  63 1. Browse and select the project directory both as "Where is the source code" and "Where to build the binaries".
  64 2. Hit "Configure".
  65 3. "Specify the generator for this project": select Xcode.
  66 4. Accept the other defaults and hit "Done".
  67 5. CMake will now download dependencies and set up some things, so you'll see some log output at the bottom of the screen for awhile.
  68 6. When that's finished you should see "Configuring done" and a bunch of keys and values (e.g. `CMAKE_CONFIGURATION_TYPES`) highlighted in red.
  69 7. Now hit "Generate", and after a few seconds you should see "Generating done".
  70
  71 #### Xcode
  72
  73 We're almost done, but we need to change a couple of settings first.
  74
  75 1. Your project directory should now have a file called `ProceduralWorld.xcodeproj`. Open it in Xcode.
  76 2. Once the project is open, change your running target from "ALL_BUILD" to "proceduralworld".
  77
  78 ![fdfd](img/set_target.png)
  79
  80 3. In the same menu, select "Edit Scheme...".
  81
  82 ![fdfd](img/edit_scheme.png)
  83
  84 4. Under the "Options" tab select "Use custom working directory" and choose the `bin/` directory under the main project directory (you may need to create this directory if this is your first time building).
  85
  86 ![dfdf](img/set_working_directory.png)
  87
  88 5. Hit the play button to build and run the program.
  89
  90 ### Visual Studio
  91
  92 *coming soon!*
  93
  94 We still need to document steps for getting this program running in Visual Studio, but steps similar to those for Xcode may work on Windows. If you have success with this, please submit a pull request!