From def3d7f867c0cbbdfc537f7da7e80406f7d873b9 Mon Sep 17 00:00:00 2001 From: Brambor Date: Mon, 4 Mar 2024 13:58:10 +0100 Subject: [PATCH] docs on compiling: friendlier to first-time contributors --- doc/COMPILING/COMPILING-CMAKE.md | 2 +- doc/COMPILING/COMPILING-CYGWIN.md | 4 +++- doc/COMPILING/COMPILING-MSYS.md | 6 +++--- doc/COMPILING/COMPILING-VS-VCPKG.md | 10 ++++++---- doc/CONTRIBUTING.md | 2 ++ doc/USER_INTERFACE_AND_ACCESSIBILITY.md | 12 ++++++------ 6 files changed, 21 insertions(+), 15 deletions(-) diff --git a/doc/COMPILING/COMPILING-CMAKE.md b/doc/COMPILING/COMPILING-CMAKE.md index ff8b969bb4885..c1cbf6c00576f 100644 --- a/doc/COMPILING/COMPILING-CMAKE.md +++ b/doc/COMPILING/COMPILING-CMAKE.md @@ -117,7 +117,7 @@ $ cmake-gui .. ## CMake Build for MSYS2 (MinGW) -1. Follow `COMPILING-MSYS.md` +1. Follow [`COMPILING-MSYS.md`](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/COMPILING/COMPILING-MSYS.md) 2. Run ``` diff --git a/doc/COMPILING/COMPILING-CYGWIN.md b/doc/COMPILING/COMPILING-CYGWIN.md index 62b91b79ef8c1..483f33b5e5f08 100644 --- a/doc/COMPILING/COMPILING-CYGWIN.md +++ b/doc/COMPILING/COMPILING-CYGWIN.md @@ -57,6 +57,8 @@ You will see messages saying packages are already installed, as well as Cygwin i **Note:** This will download the entire CDDA repository and all of its history (3GB). If you're just testing, you should probably add `--depth=1` (~350MB). +**Note:** If you want to contribute to CDDA, see [example git workflow](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/CONTRIBUTING.md#example-workflow). + ```bash cd /cygdrive/c/dev git clone https://github.com/CleverRaven/Cataclysm-DDA.git @@ -71,7 +73,7 @@ make CCACHE=1 RELEASE=1 CYGWIN=1 DYNAMIC_LINKING=1 SDL=1 TILES=1 SOUND=1 LOCALIZ You will receive warnings about unterminated character constants; they do not impact the compilation as far as this writer is aware. -**Note**: This will compile release version with Sound and Tiles support and all localization languages, skipping checks and tests and using ccache for faster build. You can use other switches, but `Cygwin=1`, `DYNAMIC_LINKING=1` and probably `RELEASE=1` are required to compile without issues. +This will compile release version with Sound and Tiles support and all localization languages, skipping checks and tests and using ccache for faster build. You can use other switches, but `Cygwin=1`, `DYNAMIC_LINKING=1` and probably `RELEASE=1` are required to compile without issues. ## Running: diff --git a/doc/COMPILING/COMPILING-MSYS.md b/doc/COMPILING/COMPILING-MSYS.md index 5a64c7acdfdfd..a70c653f71428 100644 --- a/doc/COMPILING/COMPILING-MSYS.md +++ b/doc/COMPILING/COMPILING-MSYS.md @@ -74,7 +74,7 @@ git clone https://github.com/CleverRaven/Cataclysm-DDA.git ./Cataclysm-DDA **Note:** This will download the entire CDDA repository and all of its history (3GB). If you're just testing, you should probably add `--depth=1` (~350MB). -**Note:** See `COMPILING-CMAKE.md` section `CMake Build for MSYS2 (MinGW)` for using the CMake build system. +**Note:** If you want to contribute to CDDA, see [example git workflow](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/CONTRIBUTING.md#example-workflow). 2. Compile with following command line: @@ -85,9 +85,9 @@ make -j$((`nproc`+0)) CCACHE=1 RELEASE=1 MSYS2=1 DYNAMIC_LINKING=1 SDL=1 TILES=1 You will receive warnings about unterminated character constants; they do not impact the compilation as far as this writer is aware. -**Note**: This will compile a release version with Sound and Tiles support and all localization languages, skipping checks and tests, and using ccache for build acceleration. You can use other switches, but `MSYS2=1`, `DYNAMIC_LINKING=1` and probably `RELEASE=1` are required to compile without issues. +This will compile a release version with Sound and Tiles support and all localization languages, skipping checks and tests, and using ccache for build acceleration. You can use other switches, but `MSYS2=1`, `DYNAMIC_LINKING=1` and probably `RELEASE=1` are required to compile without issues. -See `COMPILING-CMAKE.md` section `CMake Build for MSYS2 (MinGW)` for using the CMake build system. +**Note:** See `COMPILING-CMAKE.md` section [`CMake Build for MSYS2 (MinGW)`](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/COMPILING/COMPILING-CMAKE.md#cmake-build-for-msys2-mingw) for using the CMake build system. ## Running: diff --git a/doc/COMPILING/COMPILING-VS-VCPKG.md b/doc/COMPILING/COMPILING-VS-VCPKG.md index fd6a5f532650f..617f554fa43ca 100644 --- a/doc/COMPILING/COMPILING-VS-VCPKG.md +++ b/doc/COMPILING/COMPILING-VS-VCPKG.md @@ -35,7 +35,7 @@ cd vcpkg .\vcpkg integrate install ``` In a Git Bash shell, the commands are almost the same except the filesystem path separator is `/` instead of `\`. -``` +```cmd # cd to the appropriate folder first git clone https://github.com/Microsoft/vcpkg.git cd vcpkg @@ -47,13 +47,15 @@ cd vcpkg 1. Clone Cataclysm-DDA repository with following command line: -**Note:** This will download the entire CDDA repository; about three gigs of data. If you're just testing you should probably add `--depth=1`. - ```cmd git clone https://github.com/CleverRaven/Cataclysm-DDA.git cd Cataclysm-DDA ``` +**Note:** This will download the entire CDDA repository; about three gigs of data. If you're just testing you should probably add `--depth=1`. + +**Note:** If you want to contribute to CDDA, see [example git workflow](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/CONTRIBUTING.md#example-workflow). + 2. Open the provided solution (`msvc-full-features\Cataclysm-vcpkg-static.sln`) in `Visual Studio`. 3. Open the `Build > Configuration Manager` menu and adjust `Active solution configuration` and `Active solution platform` to match your intended target. @@ -63,7 +65,7 @@ cd Cataclysm-DDA 4. Start the build process by selecting either `Build > Build Solution` or `Build > Build > 1 Cataclysm-vcpkg-static`. The process may take a long period of time, so you'd better prepare a cup of coffee and some books in front of your computer :) The first build of each architecture will also download and install dependencies through vcpkg, which can take an especially long time. -5. If you need localization support, execute the bash script `lang/compile_mo.sh` inside Git Bash GUI just like on a UNIX-like system. This will compile the language files that were not automatically compiled in step 2 above. +5. If you need localization support, execute the bash script `lang/compile_mo.sh` inside Git Bash GUI just like on a UNIX-like system. This will compile the language files that were not automatically compiled in step 3 above. Even if you do not need languages other than English, you may still want to execute `lang/compile_mo.sh` to compile the language files if you're planning to run the unit tests, since those rely on the language files existing. diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 37e18197a4520..c1e1e011b0f17 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -139,6 +139,8 @@ Helpful pages: 1. [Fork](https://github.com/CleverRaven/Cataclysm-DDA/fork) this repository here on GitHub. +**Note:** Fork is different from branch, branches are covered [later](#make-your-changes). + 2. Clone your fork locally. ```bash diff --git a/doc/USER_INTERFACE_AND_ACCESSIBILITY.md b/doc/USER_INTERFACE_AND_ACCESSIBILITY.md index 521700e8ea4da..687ae9941cff2 100644 --- a/doc/USER_INTERFACE_AND_ACCESSIBILITY.md +++ b/doc/USER_INTERFACE_AND_ACCESSIBILITY.md @@ -3,13 +3,13 @@ Cataclysm: Dark Days Ahead uses ncurses, or in the case of the tiles build, an ncurses port, for user interface. Window management is achieved by `ui_adaptor`, which requires a resizing callback and a redrawing callback for each UI to handle -resizing and redrawing. A migration effort is underway for user interface code +resizing and redrawing. A migration effort is underway for user interface code to be moved to ImGui, which uses SDL on the tiled build, and ncurses on non-tiled Linux builds. Some good examples of the usage of `ui_adaptor` can be found within the following files: -- `string_input_popup` in `string_input_popup.cpp`, specifically in +- `string_input_popup` in `string_input_popup.cpp`, specifically in `string_input_popup::query_string()` - `Messages::dialog` in `messages.cpp` @@ -18,17 +18,17 @@ Details on how to use `ui_adaptor` can be found within `ui_manager.h`. New user interfaces should be coded using ImGui. ImGui-backed windows are created using `cataimgui::window` as a base, see `cata_imgui.h/cpp`. `cataimgui::window` still uses `ui_adaptor` but it is handled internally. `cataimgui::window` handles -creating the ImGui window itself, but any widgets (i.e. text boxes, tables, input -fields) must be created using the correct function under the `ImGui` namespace. +creating the ImGui window itself, but any widgets (i.e. text boxes, tables, input +fields) must be created using the correct function under the `ImGui` namespace. Examples of creating any ImGui widget can be found in `src/third-party/imgui_demo.cpp` Good examples of implementating an ImGui-based UI in cataclysm: - `query_popup` and `static_popup` in `popup.h/cpp`, specifically `query_popup_impl` which is a private implementation class used by the aforementioned classes. -- `keybindings_ui` in `input.cpp`, which is a private implementation class used +- `keybindings_ui` in `input.cpp`, which is a private implementation class used by `input_context::display_menu()`. -## SDL version requirement of the tiles build +## SDL version requirement of the tiles build Some functions used by this project require SDL 2.0.6, and the actual version requirement might be higher. While using a newer version is optional, new versions add