From 2b8382ad95ff5c3afa7b31023f407eb1557f375f Mon Sep 17 00:00:00 2001 From: Aayush Fadia Date: Sun, 4 May 2025 23:24:39 -0400 Subject: [PATCH 1/2] Added wiki entry content - build software from source. --- wiki/programming/build-from-source.md | 226 ++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 wiki/programming/build-from-source.md diff --git a/wiki/programming/build-from-source.md b/wiki/programming/build-from-source.md new file mode 100644 index 00000000..977b1a2c --- /dev/null +++ b/wiki/programming/build-from-source.md @@ -0,0 +1,226 @@ +--- +# Jekyll 'Front Matter' goes here. Most are set by default, and should NOT be +# overwritten except in special circumstances. +# You should set the date the article was last updated like this: +date: 2020-05-04 # YYYY-MM-DD +# This will be displayed at the bottom of the article +# You should set the article's title: +title: Building software from source +# The 'title' is automatically displayed at the top of the page +# and used in other parts of the site. +--- + +This tutorial describes how to configure and build libraries from source for your unique system. +This is often necessary when your software requirements are not met by the packages available in the repositories of +your distribution (the version of the package you want is not available from `apt` for your version of Ubuntu, for +example). +This tutorial will cover the process for customizing and building packages from source as you need them. +Along the way, common pitfalls and how to avoid them will be discussed. +You will also discover how to avoid polluting your system environment to avoid conflicts between the packages you build +and the ones installed by your package manager. + +## Why build your packages from source? + +There are several reasons you might want to build packages from source, a few of these are listed below: + +- The package (+ version) you want is not available from your system package manager. +- You need a customized build of the package (building OpenCV with CUDA support for example). +- For optimized builds that fully utilize all the features your hardware has to offer. + +## Process outline and key pieces + +To build software from source code, these are the broad steps that must be followed: + +- Obtain the source code: Usually `git clone` and `git checkout` and then apply patches if necessary. +- Get dependencies: Use your system package manager or build the packages that this package depends on so they are + available to this package. +- Configure the build: Use `cmake` to set options for the build, including which features to compile with and the path + where the package must be installed. +- Build and install the package: Use `cmake` to build and install the package. +- Linking against the built package: Set environment/cmake variables so that other packages can find the package + that you just built. + +This tutorial will use the popular computer-vision library OpenCV as a guiding example due to its popularity and +complexity, which will concretely demonstrate all steps. + +## Step 0: Prerequisites + +To build software, the system needs to have the following installed: + +- [CMake](https://cmake.org/) +- [Ninja](https://ninja-build.org/) as a preferred build tool. +- A C/C++ compiler, linker, and standard libraries/headers (usually preinstalled). + +This collection is called the "toolchain". +On Ubuntu all of this can be installed with: + +```bash +sudo apt install build-essential +``` + +## Step 1: Getting the source code + +### Which version do I require + +If this package is being compiled to satisfy the dependency of other software that you need, you should check which +exact version that dependent package needs. This can be done by analyzing the CMakeLists.txt file of the dependent ( +final) package, and finding a line resembling: + +```cmake +find_package(OpenCV 4 ...) +``` + +This tells you that this package requires OpenCV 4 (Any 4.x.y version works). + +Get source code for this version. + +### Cloning source code + +Get the source code on your computer into a well-organized folder (in a separate directory, that directory is alongside +directories that contain source-code for other packages). + +Instructions should be present on the package website. Usually, this involves: + +- `git clone` the package. +- `git checkout` to the release that is desired, e.g. `git checkout 4.11.0` to get that version of OpenCV, obtained from + the GitHub releases page. + +Here you would modify the source code (such as apply any quick fixes/patches as required). + +**Also follow any prescribed instructions as the package demands** + +To build OpenCV with the contrib feature set, we must also download and extract some more content. Follow instructions +listed on the website. + +## Step 2: Get dependencies + +This library will depend on other software. Get that software, usually from your package manager, by running a command +similar to (on ubuntu): + +```bash +sudo apt install lib--dev +``` + +For example, to get the "png" dependency to allow OpenCV to read png images, just run: + +```bash +sudo apt install libpng-dev +``` + +You can proceed to the next step, and install these as CMake will complain that it did not find a dependency. + +## Step 3: Configure the build + +This is the crucial step. Here, you decide how the package needs to be compiled, this includes: + +- Which features you need: In OpenCV, for example, which image formats (png, jpg, etc.) you want to support + reading/writing to? +- Do you want OpenCV to support CUDA? +- Do you want to build support for Python? +- Disable/enable features (GUI support, for example). + +### Setting the environment + +Be in the environment under which you will run this package. + +Concretely, this means: If you want OpenCV to be built in a particular Python virtual environment, in your terminal, +source this Python Environment. + +Also set `CMAKE_PREFIX_PATH` (explained later) to allow CMake to find other packages. + +### Set Options + +Now, create a well-organized build directory, where build time intermediates will be stored (these are temporary files +emitted and +consumed by the compiler and linker on the way to making the final binaries and libraries). + +Change into the build directory and configure the package as follows: + +```bash +cmake -S -DCMAKE_INSTALL_PREFIX= -DOPENCV_EXTRA_MODULES_PATH=../../src/OpenCV/opencv_contrib-4.x/modules -DWITH_TIFF=ON -DCMAKE_BUILD_TYPE=Release +``` + +Let's break down this command: + +- `-S` is where the source code to be compiled it. This directory must contain the `CMakeLists.txt` file. +- `-D