From 250cb03d1186aa1ace438d02eb4c3b7d0236590a Mon Sep 17 00:00:00 2001 From: Edoardo Pasca <14138589+paskino@users.noreply.github.com> Date: Mon, 2 Feb 2026 11:12:06 +0000 Subject: [PATCH 1/8] update readme --- README.md | 33 +++++++++++---------------------- 1 file changed, 11 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 9a9149b86..e30c48efa 100644 --- a/README.md +++ b/README.md @@ -138,30 +138,17 @@ git submodule update --init --recursive #### Install Dependencies -To create a conda environment with all the dependencies for building CIL run the following shell script: +We suggest creating a conda environment with all the dependencies for building CIL running the following shell script depending on operating system: -```sh -bash ./scripts/create_local_env_for_cil_development.sh -``` - -Or with the CIL build and test dependencies: - -```sh -bash ./scripts/create_local_env_for_cil_development.sh -t -``` - -And then install CIL in to this environment using `pip`. +| OS | Command | Status | +|----|----|----| +| Linux | `conda env create -f https://tomographicimaging.github.io/scripts/env/cil_development.yml`| Tested | +| Windows | `conda env create -f https://tomographicimaging.github.io/scripts/env/cil_development.yml`| Tested | +| MacOS (ARM) | `conda env create -f https://tomographicimaging.github.io/scripts/env/cil_development_osx.yml`| Experimental | -Alternatively, one can use the `scripts/requirements-test.yml` to create a conda environment with all the -appropriate dependencies, using the following command: +> [!NOTE] +> Currently only Linux and Windows are tested and supported. The support on MacOS (ARM) is experimental and certain features are not available/working, such as FFT filtering for FDK. -```sh -conda env create -f ./scripts/requirements-test.yml -``` -or, on windows: -```sh -conda env create -f ./scripts/requirements-test-windows.yml -``` #### Build CIL @@ -170,6 +157,8 @@ A C++ compiler is required to build the source code. Let's suppose that the user ```sh pip install --no-deps . ``` +> [!NOTE] +> You need to have a **working compiler** on your system, such as Visual Studio on Windows, GCC on Linux and XCode on MacOS. If not installing inside a conda environment, then the user might need to set the locations of optional libraries: @@ -188,7 +177,7 @@ docker build . -t ghcr.io/tomographicimaging/cil ### Testing -One installed, CIL functionality can be tested using the following command: +Once installed, CIL functionality can be tested using the following command: ```sh export TESTS_FORCE_GPU=1 # optional, makes GPU test failures noisy From 42af67907e35c1ab1b2171465179f3ffd290fdac Mon Sep 17 00:00:00 2001 From: Edoardo Pasca <14138589+paskino@users.noreply.github.com> Date: Mon, 2 Feb 2026 12:09:23 +0000 Subject: [PATCH 2/8] updated clone and build command data is not installed by the pip command so it is not useful to clone the repo recursively --- README.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index e30c48efa..db6100323 100644 --- a/README.md +++ b/README.md @@ -125,13 +125,7 @@ Jupyter Notebooks usage examples without any local installation are provided in In case of development it is useful to be able to build the software directly. You should clone this repository as ```sh -git clone --recurse-submodule git@github.com:TomographicImaging/CIL -``` - -The use of `--recurse-submodule` is necessary if the user wants the examples data to be fetched (they are needed by the unit tests). We have moved such data, previously hosted in this repo at `Wrappers/Python/data` to the [CIL-data](https://github.com/TomographicImaging/CIL-Data) repository and linked it to this one as submodule. If the data is not available it can be fetched in an already cloned repository as - -```sh -git submodule update --init --recursive +git clone git@github.com:TomographicImaging/CIL ``` ### Building with `pip` @@ -154,9 +148,12 @@ We suggest creating a conda environment with all the dependencies for building C A C++ compiler is required to build the source code. Let's suppose that the user is in the source directory, then the following commands should work: -```sh -pip install --no-deps . -``` + +| OS | Build Command | +|----|----| +| Linux | `pip install --no-deps . -Ccmake.define.IPP_ROOT=$CONDA_PREFIX`| +| Windows | `pip install --no-deps . -Ccmake.define.IPP_ROOT=%CONDA_PREFIX%| + > [!NOTE] > You need to have a **working compiler** on your system, such as Visual Studio on Windows, GCC on Linux and XCode on MacOS. From 3c1b6425e56c855e37ed52b691ebfeaff0adf684 Mon Sep 17 00:00:00 2001 From: Edoardo Pasca <14138589+paskino@users.noreply.github.com> Date: Mon, 2 Feb 2026 12:30:04 +0000 Subject: [PATCH 3/8] update pip command to find IPP --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index db6100323..f3452008e 100644 --- a/README.md +++ b/README.md @@ -152,7 +152,7 @@ A C++ compiler is required to build the source code. Let's suppose that the user | OS | Build Command | |----|----| | Linux | `pip install --no-deps . -Ccmake.define.IPP_ROOT=$CONDA_PREFIX`| -| Windows | `pip install --no-deps . -Ccmake.define.IPP_ROOT=%CONDA_PREFIX%| +| Windows | `pip install --no-deps . -Ccmake.define.IPP_ROOT=%CONDA_PREFIX%`| > [!NOTE] > You need to have a **working compiler** on your system, such as Visual Studio on Windows, GCC on Linux and XCode on MacOS. From 482a640cb4511ccc672d2d54d8fd7ca2f871eb44 Mon Sep 17 00:00:00 2001 From: Edoardo Pasca <14138589+paskino@users.noreply.github.com> Date: Mon, 2 Feb 2026 13:44:41 +0000 Subject: [PATCH 4/8] fix recipe to find IPP --- recipe/bld.bat | 2 +- recipe/build.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/recipe/bld.bat b/recipe/bld.bat index 97fb90517..06b65a1dc 100644 --- a/recipe/bld.bat +++ b/recipe/bld.bat @@ -4,5 +4,5 @@ set SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CIL=%PKG_VERSION% if not "%GIT_DESCRIBE_NUMBER%"=="0" ( set SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CIL=%PKG_VERSION%.dev%GIT_DESCRIBE_NUMBER%+%GIT_DESCRIBE_HASH% ) -pip install . --no-deps +pip install . --no-deps -Ccmake.define.IPP_ROOT=%CONDA_PREFIX% if errorlevel 1 exit 1 diff --git a/recipe/build.sh b/recipe/build.sh index 872bff219..1266a3cd7 100755 --- a/recipe/build.sh +++ b/recipe/build.sh @@ -6,7 +6,7 @@ if test $(python -c "from __future__ import print_function; import platform; pri echo "Darwin" extra_args="$extra_args -DOPENMP_LIBRARIES=${CONDA_PREFIX}/lib -DOPENMP_INCLUDES=${CONDA_PREFIX}/include" else - echo "something else" + extra_args="$extra_args -DIPP_ROOT=${CONDA_PREFIX}" fi export SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CIL="${PKG_VERSION}" From d37a15701e01713cb7a80cb12b8317f2b1aafdfd Mon Sep 17 00:00:00 2001 From: Edoardo Pasca <14138589+paskino@users.noreply.github.com> Date: Mon, 2 Feb 2026 16:15:58 +0000 Subject: [PATCH 5/8] update pip command --- recipe/build.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/recipe/build.sh b/recipe/build.sh index 1266a3cd7..f81c5a975 100755 --- a/recipe/build.sh +++ b/recipe/build.sh @@ -6,11 +6,11 @@ if test $(python -c "from __future__ import print_function; import platform; pri echo "Darwin" extra_args="$extra_args -DOPENMP_LIBRARIES=${CONDA_PREFIX}/lib -DOPENMP_INCLUDES=${CONDA_PREFIX}/include" else - extra_args="$extra_args -DIPP_ROOT=${CONDA_PREFIX}" + echo "Not Darwin" fi export SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CIL="${PKG_VERSION}" if test "${GIT_DESCRIBE_NUMBER}" != "0"; then export SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CIL="${PKG_VERSION}.dev${GIT_DESCRIBE_NUMBER}+${GIT_DESCRIBE_HASH}" fi -pip install . --no-deps -Ccmake.args="${extra_args}" +pip install . --no-deps -Ccmake.args="${extra_args}" -Ccmake.define.IPP_ROOT=${CONDA_PREFIX} From 758f315748655e7006d2ac44a801c8bcd88a1dcd Mon Sep 17 00:00:00 2001 From: Edoardo Pasca <14138589+paskino@users.noreply.github.com> Date: Fri, 6 Feb 2026 09:35:55 +0000 Subject: [PATCH 6/8] add search CMake search path for WIN32 IPP --- src/Core/cmake/FindIPP.cmake | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/Core/cmake/FindIPP.cmake b/src/Core/cmake/FindIPP.cmake index b5c402d20..b0c289c6e 100644 --- a/src/Core/cmake/FindIPP.cmake +++ b/src/Core/cmake/FindIPP.cmake @@ -10,16 +10,18 @@ elseif(NOT WIN32) set(IPP_PRE "lib") set(IPP_POST ".so") endif() -find_library(IPP_CORE ${IPP_PRE}ippcore${IPP_POST} PATHS ${IPP_ROOT_DIR}) -find_library(IPP_S ${IPP_PRE}ipps${IPP_POST} PATHS ${IPP_ROOT_DIR}) -find_library(IPP_VM ${IPP_PRE}ippvm${IPP_POST} PATHS ${IPP_ROOT_DIR}) -find_library(IPP_I ${IPP_PRE}ippi${IPP_POST} PATHS ${IPP_ROOT_DIR}) +find_library(IPP_CORE ${IPP_PRE}ippcore${IPP_POST} PATHS ${IPP_ROOT_DIR} ${IPP_ROOT_DIR}/Library/lib) +find_library(IPP_S ${IPP_PRE}ipps${IPP_POST} PATHS ${IPP_ROOT_DIR} ${IPP_ROOT_DIR}/Library/lib) +find_library(IPP_VM ${IPP_PRE}ippvm${IPP_POST} PATHS ${IPP_ROOT_DIR} ${IPP_ROOT_DIR}/Library/lib) +find_library(IPP_I ${IPP_PRE}ippi${IPP_POST} PATHS ${IPP_ROOT_DIR} ${IPP_ROOT_DIR}/Library/lib) if(IPP_INCLUDE_DIR AND IPP_CORE AND IPP_S AND IPP_VM AND IPP_I) message(STATUS "IPP found in: ${IPP_ROOT_DIR}") set(IPP_FOUND TRUE) set(IPP_INCLUDE_DIRS "${IPP_INCLUDE_DIR}") set(IPP_LIBRARIES "${IPP_CORE};${IPP_S};${IPP_VM};${IPP_I}") + message(STATUS "IPP libraries: ${IPP_LIBRARIES}") + message(STATUS "IPP include dirs: ${IPP_INCLUDE_DIRS}") else() message(STATUS "IPP not found") endif() From 6a098d59bef9b93b7bbd3435ceff5045658f3388 Mon Sep 17 00:00:00 2001 From: Edoardo Pasca <14138589+paskino@users.noreply.github.com> Date: Fri, 6 Feb 2026 10:28:54 +0000 Subject: [PATCH 7/8] added instructions on developer guide --- docs/source/developer_guide.rst | 85 +++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/docs/source/developer_guide.rst b/docs/source/developer_guide.rst index 0c65dae4d..b9a70356b 100644 --- a/docs/source/developer_guide.rst +++ b/docs/source/developer_guide.rst @@ -16,6 +16,9 @@ Developers' Guide ***************** + + + CIL is an Object Orientated software. It has evolved during the years and it currently does not fully adhere to the following conventions. New additions must comply with the following. @@ -109,6 +112,88 @@ Rendered .. automethod:: cil.recon.FBP.FBP.run +Building CIL from source code +----------------------------- + +Getting the code +^^^^^^^^^^^^^^^^ + +In case of local development and testing it is useful to be able to build the software directly. +You should first clone this repository as + +.. code:: sh + + git clone git@github.com:TomographicImaging/CIL + +Building with ``pip`` +^^^^^^^^^^^^^^^^^^^^^ + +Install Dependencies +"""""""""""""""""" + +We suggest creating a conda environment with all the dependencies for building CIL running the following shell script depending on operating system: + +.. list-table:: + :header-rows: 1 + :widths: 20 65 15 + + * - OS + - Command + - Status + * - Linux + - ``conda env create -f https://tomographicimaging.github.io/scripts/env/cil_development.yml`` + - Tested + * - Windows + - ``conda env create -f https://tomographicimaging.github.io/scripts/env/cil_development.yml`` + - Tested + * - MacOS (ARM) + - ``conda env create -f https://tomographicimaging.github.io/scripts/env/cil_development_osx.yml`` + - Experimental + +.. note:: + Currently only Linux and Windows are tested and supported. The support on MacOS (ARM) is experimental and certain features are not available and not working, such as FFT filtering for FDK. + +Build CIL +"""""""" + +A C++ compiler is required to build the source code. Let's suppose that the user is in the source directory, then the following commands should work: + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - OS + - Build Command + * - Linux + - ``pip install --no-deps . -Ccmake.define.IPP_ROOT=$CONDA_PREFIX`` + * - Windows + - ``pip install --no-deps . -Ccmake.define.IPP_ROOT=%CONDA_PREFIX%`` + +.. note:: + You need to have a **working compiler** on your system, such as Visual Studio on Windows, GCC on Linux and XCode on MacOS. + + + +If not installing inside a conda environment, then the user might need to set the locations of optional libraries: + +.. code:: sh + + pip install . -Ccmake.define.IPP_ROOT="" -Ccmake.define.OpenMP_ROOT="" + +Notes for Windows users +"""""""""""""""" + +Install Visual Studio Community (or higher) and select the **Desktop development with C++** workload. + +If you are developing on Windows with conda, you need to have access to both the Visual Studio compiler and the conda environment. + +You can achieve this in two ways: +1. by opening a "Developer Command Prompt for Visual Studio" and activating the conda environment from there. This requires you +to know the path to the `conda.bat` file, which is typically located in the `condabin` subdirectory of your conda installation. +Once located you need to run `\conda.bat activate ` to activate the conda environment, and then you can run the build command from there. +2. by opening the conda prompt and running the `vcvarsall.bat x64` file from the Visual Studio installation (with `x64` argument). +This requires you to know the path to the `vcvarsall.bat` file, +which is typically located in the `VC/Auxiliary/Build` subdirectory of your Visual Studio installation. Building documentation locally ------------------------------ From e597d5360b848f599e86c9f0c88dd3c46e2aa5ff Mon Sep 17 00:00:00 2001 From: Edoardo Pasca <14138589+paskino@users.noreply.github.com> Date: Fri, 6 Feb 2026 16:33:31 +0000 Subject: [PATCH 8/8] updated changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 81227615c..b92196343 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ - improve `tqdm` notebook support (#2241) - Documentation: - Render the user showcase notebooks in the documentation (#2189) + - Update on build instructions in README and developer guide for all OS - Enhancements: - Add prefix argument to TIFFStackReader to load a subset of TIFF files in a folder (#2239)