Update dev instructions #2286

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft

paskino wants to merge 9 commits into TomographicImaging:master from paskino:update_dev_instructions

+113 −39

CHANGELOG.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -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)
@@ Expand Down @@

README.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -125,51 +125,37 @@ 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`

    #### Install Dependencies

    To create a conda environment with all the dependencies for building CIL run the following shell script:

    ```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

    ```

    We suggest creating a conda environment with all the dependencies for building CIL running the following shell script depending on operating system:

    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

    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.

    If not installing inside a conda environment, then the user might need to set the locations of optional libraries:

    @@ -188,7 +174,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

docs/source/developer_guide.rst

-Original file line number
+Diff line change
@@ Expand Up / @@ -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.
@@ Expand Down Expand Up / @@ -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="<path_to_ipp>" -Ccmake.define.OpenMP_ROOT="<path_to_openmp>"
+    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:
+. 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 `<path_to>\conda.bat activate <env_name>` to activate the conda environment, and then you can run the build command from there.
+. 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
     ------------------------------
@@ Expand Down @@

recipe/bld.bat

-Original file line number
+Diff line change
@@ Expand Up / @@ -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

recipe/build.sh

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -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

      echo "something else"

      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}

src/Core/cmake/FindIPP.cmake

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -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()

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update dev instructions #2286

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Update dev instructions #2286

Are you sure you want to change the base?

Update dev instructions #2286

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!