From ed771e3c8eb95744c9fc5b3c9eafef4f6b48c499 Mon Sep 17 00:00:00 2001 From: Sam Edwards Date: Sun, 12 Jan 2020 12:02:35 -0700 Subject: [PATCH] doc: Update CMake's README --- cmake/README.md | 74 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 50 insertions(+), 24 deletions(-) diff --git a/cmake/README.md b/cmake/README.md index 71c2ded070..e90246ccdb 100644 --- a/cmake/README.md +++ b/cmake/README.md @@ -1,31 +1,67 @@ Building with CMake ------------------- -The quickest way to build and install panda with CMake is to run: +On Windows and macOS, please ensure that you have the very latest version of +CMake installed; older versions may work, but if not, please upgrade to the +latest available version of CMake before requesting help. + +On systems that package CMake themselves (e.g. Linux distributions), we most +likely support the provided version of CMake as long as the system itself is +supported. + +CMake will also require that you already have your system's developer tools +installed. + +The quickest way to build and install Panda with CMake is to install any +third-party dependencies and then run: ```sh mkdir build && cd build cmake .. -make -[sudo] make install +cmake --build . --config Standard --parallel 4 +[sudo] cmake --build . --config Standard --target install ``` +Note that, if you are targeting 64-bit on Windows, it is necessary to supply +the `-A x64` option when first invoking `cmake` (as `cmake -A x64 ..`). + +CMake itself does not build Panda; rather, it generates project files for an +existing IDE or build tool. To select a build tool, pass the `-G` option when +first invoking CMake, (`cmake -G Ninja ..` is highly recommended on Linux). +Some of these (Xcode, Visual Studio) support targeting multiple configurations +(the `--config Standard`, above, selects the `Standard` configuration in those +cases). Other build tools (Ninja, Makefiles, ...) do not support multiple +configurations, and the `--config` option is ignored. To change the +configuration in these cases (from `Standard`, the default), it is necessary to +change the `CMAKE_BUILD_TYPE` variable as explained below. + +The configurations are: + +| Configuration | Explanation | +| -------------- | ------------------------------------------------------ | +| Standard | Default; build provided to users of SDK | +| Release | Distribution for end-users | +| MinSizeRel | Like Release, but optimized for size | +| RelWithDebInfo | Like Release, but include debug symbols | +| Debug | Do not optimize, enable optional debugging features | +| Coverage | Like Debug, but profile code coverage; developers only | + To configure CMake, it is recommended to use cmake-gui (`cmake-gui .`), -however it is also possible to configure it entirely through CMake's -command-line interface; see `man cmake` for more details. +or ccmake (`ccmake .`), however it is also possible to configure it entirely +through CMake's command-line interface; see `man cmake` for more details. In general, the config variable for a particular third party library is: ``` - HAVE_=True/False # Example: USE_JPEG + HAVE_=YES/NO # Example: USE_JPEG ``` Panda subpackage building is handled by: ``` - BUILD_=True/False # Example: BUILD_DTOOL, BUILD_PANDA + BUILD_=YES/NO # Example: BUILD_DTOOL, BUILD_PANDA ``` Other configuration settings use their historical names (same names as in-source): ``` # Examples PANDA_DISTRIBUTOR="MyDistributor" - LINMATH_ALIGN=On + LINMATH_ALIGN=YES # ... etc ... @@ -33,20 +69,10 @@ Other configuration settings use their historical names (same names as in-source For example, `makepanda.py --distributor X` becomes `cmake -DPANDA_DISTRIBUTOR=X` -All found third-party libraries are enabled by default. -Most config settings are set to a sensible default for typical -a PC/desktop Panda3D distribution. -Third-party libraries and other settings can be enabled or disabled -through configuration with the cmake gui or cli. +All found third-party libraries are enabled by default, and makepanda-style +tools packages are searched in the same path as makepanda (however this may be +overridden with the `THIRDPARTY_DIRECTORY` option). -Running Panda3D with `-DCMAKE_BUILD_TYPE=` and one of `Release`, `Debug`, -`MinSizeRel`, or `RelWithDebInfo` will cause some configuration settings -to change their defaults to more appropriate values. - -If cmake has already been generated, changing the build type will not cause -some of these values to change to their expected values, because the values -are cached so that they don't overwrite custom settings. - -To reset CMake's config to defaults, delete the CMakeCache.txt file, and rerun -CMake with the preferred build mode specified -(example: `cmake .. -DCMAKE_BUILD_TYPE=Debug`). +Most config settings are set to a sensible default for a typical PC/desktop +Panda3D distribution. Third-party libraries and other settings can be enabled +or disabled through configuration with the cmake GUI or CLI.