1# Using CMake for the Opus Project 2 3This guide provides instructions for using CMake to build the Opus project with various configuration options. CMake is a widely used build system generator that helps manage the build process across different platforms. 4 5Note: Please keep in mind that software documentation can sometimes go out of date as new versions are released. It is always recommended to refer to the official CMake documentation for the most up-to-date and accurate information. You can find the official CMake documentation at [cmake.org/documentation](https://cmake.org/documentation/). 6 7## Prerequisites 8 9Before proceeding, make sure you have the following prerequisites installed: 10 11- CMake 12- Git (optional, but recommended for version control integration) 13- Working C compiler 14 15## Build Instructions 16 17Follow the steps below to build the Opus project using CMake: 18 191. Clone the Opus repository using Git: 20 21 ```shell 22 git clone https://gitlab.xiph.org/xiph/opus 23 ``` 24 252. Create a build directory within the Opus repository: 26 27 ```shell 28 cd opus 29 mkdir build 30 cd build 31 ``` 32 333. Configure the build with CMake. You can set the desired configuration options using CMake's `-D` flag. Here are some available options: 34 35 - `OPUS_BUILD_SHARED_LIBRARY`: build shared library. 36 - `OPUS_BUILD_TESTING`: build tests. 37 - `OPUS_BUILD_PROGRAMS`: build programs. 38 - `OPUS_CUSTOM_MODES`, enable non-Opus modes, e.g. 44.1 kHz & 2^n frames. 39 40 For example, to enable the custom modes and build programs, use the following command: 41 42 ```shell 43 cmake .. -DOPUS_BUILD_PROGRAMS=ON -DOPUS_BUILD_TESTING=ON 44 ``` 45 464. Build the Opus project: 47 48 ```shell 49 cmake --build . 50 ``` 51 525. After a successful build, you can find the compiled Opus library and associated files in the build directory. 53 54## Testing with CTest 55 56Opus provides a comprehensive test suite to ensure the functionality and correctness of the project. You can execute the tests using CTest, a part of the CMake build system. CTest allows for automated testing and provides useful features for managing and evaluating the test results. 57 58To run the Opus tests using CTest, follow these steps: 59 601. Navigate to the build directory after configuring and building the project with CMake: 61 62 ```shell 63 cd build 64 ``` 65 662. Execute the tests using CTest: 67 68 ```shell 69 ctest 70 ``` 71 72Note: For Windows you need to specify which configuration to test 73 74```shell 75ctest -C Debug 76``` 77 78## Platform Support and Bug Reporting 79 80CMake aims to provide broad platform support, allowing the Opus project to be built and used on major operating systems and platforms. The supported platforms include: 81 82- Windows 83- macOS 84- Linux 85- Android 86- iOS 87 88CMake achieves platform support by generating platform-specific build files (e.g., Makefiles, Visual Studio projects) based on the target platform. This allows developers to build and configure the Opus project consistently across different operating systems and environments. 89 90While CMake strives to ensure compatibility and stability across platforms, bugs or issues may still arise in specific configurations. If you encounter any problems during the configuration process or while building the Opus project, we encourage you to file an issue in the [project's issue tracker](https://gitlab.xiph.org/xiph/opus/-/issues). 91 92When reporting an issue, please provide the following information to help us understand and reproduce the configuration problem effectively: 93 941. Detailed description of the issue, including any error messages or unexpected behavior observed. 952. Steps to reproduce the problem, including the CMake command and any specific configuration options used. 963. Operating system and version (e.g., Windows 10, macOS Big Sur, Ubuntu 20.04). 974. CMake version (e.g., CMake 3.21.1). 985. Any relevant information about the platform, toolchain, or dependencies used. 996. Additional context or details that might assist in troubleshooting the issue. 100 101By providing thorough information when reporting configuration issues, you contribute to improving the Opus project's compatibility and reliability across different platforms. 102 103We appreciate your help in identifying and addressing any configuration-related problems, ensuring a better experience for all users of the Opus project. 104 105## Platform Specific Examples 106 107Note: Examples can go out of date. Always refer to documentation for latest reference. 108 109### Cross compiling for Android 110 111```shell 112cmake .. -DCMAKE_TOOLCHAIN_FILE=${ANDROID_HOME}/ndk/25.2.9519653/build/cmake/android.toolchain.cmake -DANDROID_ABI=arm64-v8a 113``` 114 115For more information about cross compiling for android, you can refer to the [Cross compiling for Android documentation](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling-for-android). 116 117### Cross compiling for iOS 118 119```shell 120cmake .. -G "Unix Makefiles" -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_ARCHITECTURES=arm64 121``` 122 123For more information about cross compilation for iOS, you can refer to the [Cross compiling for iOS documentation](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling-for-ios-tvos-or-watchos). 124 125 126### Windows Visual Studio 127 128```shell 129cmake .. -G "Visual Studio 17 2022" -A x64 130``` 131 132For more information about the Visual Studio generator options and additional customization, you can refer to the [Visual Studio Generator documentation](https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2017%202022.html). 133