# Developer Setup

If you want to make changes to CapyMOA, you should follow these steps to set up
an editable installation of CapyMOA, with development and documentation
dependencies.

1. **Dependencies**

   Follow the instructions above to install PyTorch, Java, and optionally a
   virtual environment.
2. **Pandoc**

   Ensure that you have [Pandoc](https://pandoc.org/) installed on your system.
   If it’s not installed, you can install it by running the following command on

   ### Ubuntu

   ```bash
   sudo apt-get install -y pandoc
   ```

   ### macOS

   ```bash
   sudo brew install pandoc
   ```

   ### Windows/Other

   Follow the instructions on the [Pandoc website](https://pandoc.org/installing.html).

   ### conda

   ```bash
   conda install -c conda-forge pandoc
   ```
3. **Clone the Repository**

   If you want to contribute to CapyMOA, you should clone the repository,
   install development dependencies, and install CapyMOA in editable mode.

   If you are intending to contribute to CapyMOA, consider making a
   [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
   of the repository and cloning your fork instead of the main
   repository. This way, you can push changes to your fork and create
   pull requests to the main repository.
   ```bash
   git clone https://github.com/adaptive-machine-learning/CapyMOA.git
   # or clone via the SSH protocol (often preferred if you use SSH keys for git):
   #   ``git clone with git@github.com:adaptive-machine-learning/CapyMOA.git``
   ```
4. **Install CapyMOA in Editable Mode**

   To install CapyMOA in editable mode with development and documentation
   dependencies, navigate to the root of the repository and run:

   ### uv (recommended)

   ```bash
   cd CapyMOA
   uv sync --extra dev --extra doc --extra torch-cpu
   ```

   `--extra torch-cpu` installs CPU-only PyTorch wheels, resolved
   automatically via the `pytorch-cpu` index configured in
   `pyproject.toml` – no manual `--index-url` step needed. If you
   have a GPU and want CUDA-enabled PyTorch instead, use
   `--extra torch` in place of `--extra torch-cpu` (the two are
   mutually exclusive).

   ### pip / conda

   ```bash
   cd CapyMOA
   pip install --editable ".[dev,doc,torch]"
   ```

   The `dev` extra does not include `torch` – add it explicitly (as
   above) to run the whole test suite. On Linux, install the CPU build of
   PyTorch first if you do not want the CUDA packages – see the PyTorch
   note in [Setup](index.md).
5. **Congratulations!**

   You have successfully installed CapyMOA in editable mode.

   A number of utility scripts are defined in `tasks.py` to perform common
   tasks. You can list all available tasks by running:

   ### uv

   ```bash
   uv run invoke --list
   ```

   ### pip / conda (activated venv)

   ```bash
   python -m invoke --list # or `invoke --list`
   ```

   ```text
   Available tasks:

     commit                                     Commit changes using conventional
                                                commits.
     format (fmt)                               Format the code using ruff.
     lint                                       Lint the code using ruff.
     refresh-moa                                Replace the moa.jar file with the
                                                appropriate version.
     build.clean                                Clean all build artifacts.
     build.clean-moa                            Remove the moa.jar file.
     build.clean-stubs                          Remove the Java stubs.
     build.download-moa                         Download moa.jar from the web.
     build.stubs                                Build Java stubs using stubgenj.
     clean.build                                Clean all build artifacts.
     clean.docs                                 Remove the built documentation.
     clean.nb                                   Remove generated notebook
                                                artifacts (`.ipynb` files,
                                                execution side-effects).
     docs.build (docs)                          Build the documentation using
                                                Sphinx.
     docs.clean                                 Remove the built documentation.
     docs.nb                                    Execute notebooks and bake their
                                                outputs into their `.ipynb` files.
     test.all (test)                            Run all the tests.
     test.coverage-clean (test.cov-clean)       Clean coverage data.
     test.coverage-combine (test.cov-combine)   Combine coverage data from
                                                different sources.
     test.coverage-report (test.cov-report)     Generate coverage report.
     test.doctest                               Run tests defined in docstrings
                                                using pytest.
     test.nb                                    Execute notebooks and bake their
                                                outputs into their `.ipynb` files.
     test.pytest                                Run the tests using pytest.
   ```

   Each of these tasks can be run in the terminal through `invoke <task>`.
   If you installed with `uv sync` (and have not separately activated
   `.venv`), prefix every invocation with `uv run` instead –
   `uv sync` does not put `.venv` on `PATH` the way activating it does.
   Running the task to build documentation would look like this:

   ### uv

   ```bash
   uv run invoke docs.build
   ```

   ### pip / conda (activated venv)

   ```bash
   invoke docs.build
   ```

   See the [Contributing](../contributing/index.md) guide for more information on how to
   contribute to CapyMOA, including how to test PyTorch-optional code in
   [Adding Tests](../contributing/tests.md).