1# Cmake contributions 2 3Contributions to the cmake build configurations are welcome. Please 4use case sensitivity that matches modern (i.e. cmake version 2.6 and above) 5conventions of using lower-case for commands, and upper-case for 6variables. 7 8## How to build 9 10As cmake doesn't support command like `cmake clean`, it's recommended to perform an "out of source build". 11To do this, you can create a new directory and build in it: 12```sh 13cd build/cmake 14mkdir builddir 15cd builddir 16cmake .. 17make 18``` 19Then you can clean all cmake caches by simply delete the new directory: 20```sh 21rm -rf build/cmake/builddir 22``` 23 24And of course, you can directly build in build/cmake: 25```sh 26cd build/cmake 27cmake 28make 29``` 30 31To show cmake build options, you can: 32```sh 33cd build/cmake/builddir 34cmake -LH .. 35``` 36 37Bool options can be set to `ON/OFF` with `-D[option]=[ON/OFF]`. You can configure cmake options like this: 38```sh 39cd build/cmake/builddir 40cmake -DZSTD_BUILD_TESTS=ON -DZSTD_LEGACY_SUPPORT=OFF .. 41make 42``` 43 44**Apple Frameworks** 45It's generally recommended to have CMake with versions higher than 3.14 for [iOS-derived platforms](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#id27). 46```sh 47cmake -S. -B build-cmake -DZSTD_FRAMEWORK=ON -DCMAKE_SYSTEM_NAME=iOS 48``` 49Or you can utilize [iOS-CMake](https://github.com/leetal/ios-cmake) toolchain for CMake versions lower than 3.14 50```sh 51cmake -B build -G Xcode -DCMAKE_TOOLCHAIN_FILE=<Path To ios.toolchain.cmake> -DPLATFORM=OS64 -DZSTD_FRAMEWORK=ON 52``` 53 54### how to use it with CMake FetchContent 55 56For all options available, you can see it on <https://github.com/facebook/zstd/blob/dev/build/cmake/lib/CMakeLists.txt> 57```cmake 58include(FetchContent) 59 60set(ZSTD_BUILD_STATIC ON) 61set(ZSTD_BUILD_SHARED OFF) 62 63FetchContent_Declare( 64 zstd 65 URL "https://github.com/facebook/zstd/releases/download/v1.5.5/zstd-1.5.5.tar.gz" 66 DOWNLOAD_EXTRACT_TIMESTAMP TRUE 67 SOURCE_SUBDIR build/cmake 68) 69 70FetchContent_MakeAvailable(zstd) 71 72target_link_libraries( 73 ${PROJECT_NAME} 74 PRIVATE 75 libzstd_static 76) 77 78# On windows and macos this is needed 79target_include_directories( 80 ${PROJECT_NAME} 81 PRIVATE 82 ${zstd_SOURCE_DIR}/lib 83) 84``` 85 86### referring 87[Looking for a 'cmake clean' command to clear up CMake output](https://stackoverflow.com/questions/9680420/looking-for-a-cmake-clean-command-to-clear-up-cmake-output) 88 89## CMake Style Recommendations 90 91### Indent all code correctly, i.e. the body of 92 93 * if/else/endif 94 * foreach/endforeach 95 * while/endwhile 96 * macro/endmacro 97 * function/endfunction 98 99Use spaces for indenting, 2, 3 or 4 spaces preferably. Use the same amount of 100spaces for indenting as is used in the rest of the file. Do not use tabs. 101 102### Upper/lower casing 103 104Most important: use consistent upper- or lowercasing within one file ! 105 106In general, the all-lowercase style is preferred. 107 108So, this is recommended: 109 110``` 111add_executable(foo foo.c) 112``` 113 114These forms are discouraged 115 116``` 117ADD_EXECUTABLE(bar bar.c) 118Add_Executable(hello hello.c) 119aDd_ExEcUtAbLe(blub blub.c) 120``` 121 122### End commands 123To make the code easier to read, use empty commands for endforeach(), endif(), 124endfunction(), endmacro() and endwhile(). Also, use empty else() commands. 125 126For example, do this: 127 128``` 129if(FOOVAR) 130 some_command(...) 131else() 132 another_command(...) 133endif() 134``` 135 136and not this: 137 138``` 139if(BARVAR) 140 some_other_command(...) 141endif(BARVAR) 142``` 143 144### Other resources for best practices 145 146https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html#modules 147