--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://catboost.ai/docs/en/concepts/development-and-contributions.md - href: en/concepts/development-and-contributions.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt --- > **Documentation Index:** Fetch the complete configuration index at https://catboost.ai/docs/en/llms.txt # Development and contributions ## [Build from source](https://catboost.ai/docs/en/concepts/build-from-source.md) {#build-from-source} ## Run tests {#run-tests} {% note warning %} CatBoost uses [CMake](https://cmake.org/)-based build process since [this commit](https://github.com/catboost/catboost/commit/c5c642ca0b8e093336d0229ac4b14c78db3915bb). Previously `Ya Make` (Yandex's build system) had been used. {% endnote %} ### CMake-based build tests - C/C++ libraries. C/C++ libraries contain tests for them in `ut` subdirectories in the source tree. For library in `x/y/z` the corresponding test code will be in `x/y/z/ut` and the target name will be `x-y-z-ut`. So, in order to run the test [run CMake](https://catboost.ai/docs/en/concepts/build-from-source.md#build-cmake) and then build the corresponding `x-y-z-ut` target. Building this target will produce an executable `${CMAKE_BUILD_DIR}/x/y/z/x-y-z-ut`. Run this executable to execute all the tests. - R package 1. Install additional R packages that are required to run tests: - `caret` - `dplyr` - `jsonlite` - `testthat` 1. Open the `R-package` directory from the local copy of the CatBoost repository. 1. Run the following command: ``` R CMD check . ``` To run tests using the devtools package: 1. Install [devtools](https://github.com/hadley/devtools). 1. Run the following command from the R session: ``` devtools::test() ``` - CLI 1. Install [pytest](https://pytest.org/), [pandas](https://pypi.org/project/pandas/) and [catboost](https://pypi.org/project/catboost/) (used for reading column description files using `catboost.utils.read_cd`) packages for the python interpreter you intend to use. Optionally install [pytest-xdist](https://pytest-xdist.readthedocs.io/en/stable/) and [pytest-randomly](https://github.com/pytest-dev/pytest-randomly) to run tests in parallel (it will be faster). {% cut "Previous requirements" %} Before revision [37a15c4](https://github.com/catboost/catboost/commit/37a15c44f323645b844abb983f2c3ecd0953554a), it was necessary to additionally install [testpath](https://pypi.org/project/testpath/) package. {% endcut %} 1. [Build](build-from-source#build-cmake) the CLI binary (target `catboost` for Ninja or another build tool) and a supplementary tool that is used to compare results generated as tests output with the canonical ones (target `limited_precision_dsv_diff` for Ninja or another build tool). 1. Set the following environment variables: - `CMAKE_BINARY_DIR` to the root for the build directory that has been generated by `CMake` and where the aformentioned targets have been built. - `TEST_OUTPUT_DIR` to the root for the directory where tests temporary data will be generated. - `PORT_SYNC_PATH` to the path to the directory that will be used for network ports allocation syncronization. The directory will be created if not exists. - `HAVE_CUDA` - set to `1` if you want to run tests on GPU with `CUDA`, set to `0` otherwise. {% cut "Previous requirements" %} Before revision [a087975](https://github.com/catboost/catboost/commit/a087975944e63779e060502beba21d6203615446), it was necessary to additionally set `CMAKE_SOURCE_DIR` to the root of the local copy of the CatBoost repository. {% endcut %} 1. Open the `catboost/pytest` directory from the local copy of the CatBoost repository. 1. Run `python -m pytest` or (if you use `pytest-xdist`) `python -m pytest -n ` or `python -m pytest -n auto` (in the `auto` case the number of parallel workers will be equal to the total count of detected CPU cores). - Python package Tests will check `catboost` module for the `python` interpreter you run them with, so if you want to test `catboost` python package built from source [build and install it first](../installation/python-installation-method-build-from-source#installation). 1. Install [pytest](https://pytest.org/), [pandas](https://pypi.org/project/pandas/), [ipywidgets](https://pypi.org/project/ipywidgets/), [scikit-learn](https://pypi.org/project/scikit-learn/) and [polars](https://pypi.org/project/polars/) packages for the python interpreter you intend to use. Optionally install [pytest-xdist](https://pytest-xdist.readthedocs.io/en/stable/) and [pytest-randomly](https://github.com/pytest-dev/pytest-randomly) to run tests in parallel (it will be faster). {% cut "Previous requirements" %} Before revision [9017641](https://github.com/catboost/catboost/commit/9017641d98bf4fc687277926e35c542320405d2f), `polars` package had not been used. Before revision [34606a6](https://github.com/catboost/catboost/commit/34606a6804dcb6bcd803188a97a0998fc3478a92) the supported `scikit-learn` versions were < 1.8.x. Before revision [37a15c4](https://github.com/catboost/catboost/commit/37a15c44f323645b844abb983f2c3ecd0953554a), it was necessary to additionally install [testpath](https://pypi.org/project/testpath/) package. {% endcut %} 1. [Build](build-from-source#build-cmake) supplementary tools that are used to compare results generated as tests output with the canonical ones (targets `limited_precision_dsv_diff`, `limited_precision_json_diff`, `model_comparator` for Ninja or another build tool). 1. Set the following environment variables: - `CMAKE_BINARY_DIR` to the root for the build directory that has been generated by `CMake` and where the aformentioned targets have been built. - `TEST_OUTPUT_DIR` to the root for the directory where tests temporary data will be generated. - `PORT_SYNC_PATH` to the path to the directory that will be used for network ports allocation syncronization. The directory will be created if not exists. {% cut "Previous requirements" %} Before revision [a087975](https://github.com/catboost/catboost/commit/a087975944e63779e060502beba21d6203615446), it was necessary to additionally set `CMAKE_SOURCE_DIR` to the root of the local copy of the CatBoost repository. {% endcut %} 1. Open the `catboost/python-package/ut/medium` directory from the local copy of the CatBoost repository. 1. Run `python -m pytest` or (if you use `pytest-xdist`) `python -m pytest -n ` or `python -m pytest -n auto` (in the `auto` case the number of parallel workers will be equal to the total count of detected CPU cores). {% note warning %} Tests on GPU with `CUDA` will be run if and only if GPU with CUDA drivers installed is present. {% endnote %} - JVM applier Open the `catboost/jvm-packages/catboost4j-prediction` directory from the local copy of the CatBoost repository. Run standard `mvn test` command. To run tests on GPU as well add `-DtestOnGPU=1` command line flag. - CatBoost for Apache Spark See [building CatBoost for Apache Spark from source](https://catboost.ai/docs/en/installation/spark-installation-build-from-source-maven.md). Use standard `mvn test` command. ### YaMake-based build tests {% note warning %} The following documentation describes running tests using Ya Make which is applicable only for versions prior to [this commit](https://github.com/catboost/catboost/commit/c5c642ca0b8e093336d0229ac4b14c78db3915bb). {% endnote %} CatBoost provides tests that check the compliance of the canonical data with the resulting data. The required steps for running these tests depend on the implementation. {% list tabs %} - Command-line version 1. Execute common tests: 1. Open the `catboost/pytest` directory from the local copy of the CatBoost repository. 1. Run the following command: ```bash ../../ya make -t -A [-Z] ``` `-Z` — Optional key to replace the canonical files if the code breaks tests intentionally. 1. Execute tests for the GPU implementation: 1. Open the `catboost/pytest/cuda_tests` directory from the local copy of the CatBoost repository. 1. Run the following command: ```bash ../../../ya make -DCUDA_ROOT= -t -A [-Z] ``` - `path_to_CUDA_SDK` is the path to directory where CUDA SDK is installed. For example, the typical installation directory for Linux is `/usr/local/cuda-X.Y`, where X.Y is the installed CUDA SDK version. - `-Z` — Optional key to replace the canonical files if the code breaks tests intentionally. Use the VCS diff tool to analyze the differences. - Python package 1. Execute common tests: 1. Open the `catboost/python-package/ut/medium` directory from the local copy of the CatBoost repository. 1. Run the following command: ```no-highlight ../../../../ya make -t -A [-Z] ``` `-Z` — Optional key to replace the canonical files if the code breaks tests intentionally. 1. Execute tests for the GPU implementation: 1. Open the `catboost/python-package/ut/medium/gpu` directory from the local copy of the CatBoost repository. 1. Run the following command: ``` ../../../../../ya make -DCUDA_ROOT= -t -A [-Z] ``` - `path_to_CUDA_SDK` is the path to directory where CUDA SDK is installed. For example, the typical installation directory for Linux is `/usr/local/cuda-X.Y`, where X.Y is the installed CUDA SDK version. - `-Z` — Optional key to replace the canonical files if the code breaks tests intentionally. Use the VCS diff tool to analyze the differences. - R package 1. Install additional R packages that are required to run tests: - `caret` - `dplyr` - `jsonlite` - `testthat` 1. Open the `R-package` directory from the local copy of the CatBoost repository. 1. Run the following command: ``` R CMD check . ``` To run tests using the devtools package: 1. Install [devtools](https://github.com/hadley/devtools). 1. Run the following command from the R session: ``` devtools::test() ``` {% endlist %} ## Microsoft Visual Studio solution {#compiling-in-windows} {% note warning %} Ready Microsoft Visual Studio solution had been provided until [this commit](https://github.com/catboost/catboost/commit/cd63b6c7313a28bcb40cd0674d73e356ad633de4). For versions after this commit it is recommended [to generate Microsoft Visual Studio solution using the corresponding CMake generator](https://catboost.ai/docs/en/installation/build-native-artifacts.md#build-cmake-conan-ninja). {% endnote %} A solution for Visual Studio is available in the CatBoost repository: ``` catboost/msvs/arcadia.sln ``` ## Coding conventions {#coding-convention} The following coding conventions must be followed in order to successfully contribute to the CatBoost project: - [C++ style guide](https://github.com/catboost/catboost/blob/master/CPP_STYLE_GUIDE.md) - [pep8](https://www.python.org/dev/peps/pep-0008/) for Python ## Versioning conventions {#versioning-conventions} Do not change the package version when submitting pull requests. Yandex uses an internal repository for this purpose. ## License By contributing to this project, you agree that your contributions will be licensed under [the Apache 2.0 license](https://github.com/catboost/catboost/blob/master/LICENSE).