Skip to content

Commit

Permalink
Re-apply lost updates in dev guides (Point72#202)
Browse files Browse the repository at this point in the history
* Re-apply updates to build csp from source

Signed-off-by: Pavithra Eswaramoorthy <pavithraes@outlook.com>

* Add note about DCO in the Contribute.md

Signed-off-by: Pavithra Eswaramoorthy <pavithraes@outlook.com>

* Add back install notes about perl-ipc & git

* Add back Using System Dependencies section

Signed-off-by: Pavithra Eswaramoorthy <pavithraes@outlook.com>

---------

Signed-off-by: Pavithra Eswaramoorthy <pavithraes@outlook.com>
  • Loading branch information
pavithraes authored Apr 23, 2024
1 parent 5c7e55f commit 4621584
Show file tree
Hide file tree
Showing 2 changed files with 51 additions and 33 deletions.
79 changes: 46 additions & 33 deletions docs/wiki/dev-guides/Build-CSP-from-Source.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ CSP is written in Python and C++ with Python and C++ build dependencies. While p
- [Clone](#clone)
- [Install build dependencies](#install-build-dependencies)
- [Build](#build)
- [A note about dependencies](#a-note-about-dependencies)
- [Building with a system package manager](#building-with-a-system-package-manager)
- [Clone](#clone-1)
- [Install build dependencies](#install-build-dependencies-1)
Expand All @@ -18,6 +19,7 @@ CSP is written in Python and C++ with Python and C++ build dependencies. While p
- [Install Python dependencies](#install-python-dependencies)
- [Build](#build-1)
- [Building on `aarch64` Linux](#building-on-aarch64-linux)
- [Using System Dependencies](#using-system-dependencies)
- [Lint and Autoformat](#lint-and-autoformat)
- [Testing](#testing)
- [Troubleshooting](#troubleshooting)
Expand Down Expand Up @@ -49,29 +51,16 @@ CSP has a few system-level dependencies which you can install from your machine

The easiest way to get started on a Linux machine is by installing the necessary dependencies in a self-contained conda environment.

Tweak this script to create a conda environment, install the build dependencies, build, and install a development version of CSP into the environment.
Tweak this script to create a conda environment, install the build dependencies, build, and install a development version of `csp` into the environment. Note that we use [micromamba](https://mamba.readthedocs.io/en/latest/index.html) in this example, but [Anaconda](https://www.anaconda.com/download), [Miniconda](https://docs.anaconda.com/free/miniconda/index.html), [Miniforge](https://github.com/conda-forge/miniforge), etc, should all work fine.

### Install conda

```bash
mkdir ~/github
cd ~/github
# download and install micromamba for Linux/Mac
"${SHELL}" <(curl -L micro.mamba.pm/install.sh)

# this downloads a Linux x86_64 build, change your architecture to match your development machine
# see https://conda-forge.org/miniforge/ for alternate download links

wget https://github.com/conda-forge/miniforge/releases/download/23.3.1-1/Mambaforge-23.3.1-1-Linux-x86_64.sh
chmod 755 Mambaforge-23.3.1-1-Linux-x86_64.sh
./Mambaforge-23.3.1-1-Linux-x86_64.sh -b -f -u -p csp_venv

. ~/github/csp_venv/etc/profile.d/conda.sh

# optionally, run this if you want to set up conda in your .bashrc
# conda init bash

conda config --add channels conda-forge
conda config --set channel_priority strict
conda activate base
# on windows powershell
# Invoke-Expression ((Invoke-WebRequest -Uri https://micro.mamba.pm/install.ps1).Content)
```

### Clone
Expand All @@ -88,31 +77,31 @@ git submodule update --init --recursive
# Note the operating system, change as needed
# Linux and MacOS should use the unix dev environment spec
micromamba create -n csp -f conda/dev-environment-unix.yml

# uncomment below if the build fails because git isn't new enough
#
# micromamba install -y -n csp git

# uncomment below if the build fails because perl-ipc-system is missing
# (this happens on some RHEL7 systems)
#
# micromamba install -y -n csp perl-ipc-system-simple

micromamba activate csp
```

### Build

```bash
make build

# on aarch64 linux, comment the above command and use this instead
# VCPKG_FORCE_SYSTEM_BINARIES=1 make build
make build-conda

# finally install into the csp_venv conda environment
# finally install into the csp conda environment
make develop
```

If you didn’t do `conda init bash` you’ll need to re-add conda to your shell environment and activate the `csp` environment to use it:
### A note about dependencies

```bash
. ~/github/csp_venv/etc/profile.d/conda.sh
conda activate csp

# make sure everything works
cd ~/github/csp
make test
```
In Conda, we pull our dependencies from the Conda environment by setting the environment variable `CSP_USE_VCPKG=0`. This will force the build to not pull dependencies from vcpkg. This may or may not work in other environments or with packages provided by other package managers or built from source, but there is too much variability for us to support alternative patterns.

## Building with a system package manager

Expand Down Expand Up @@ -187,6 +176,8 @@ Build the python project in the usual manner:
```bash
make build

# on aarch64 linux, comment the above command and use this instead
# VCPKG_FORCE_SYSTEM_BINARIES=1 make build
# or
# python setup.py build build_ext --inplace
```
Expand All @@ -199,6 +190,10 @@ On `aarch64` Linux the VCPKG_FORCE_SYSTEM_BINARIES environment variable must be
VCPKG_FORCE_SYSTEM_BINARIES=1 make build
```

## Using System Dependencies

By default, we pull and build dependencies with [vcpkg](https://vcpkg.io/en/). We only support non-vendored dependencies via Conda (see [A note about dependencies](#A-note-about-dependencies) above).

## Lint and Autoformat

CSP has listing and auto formatting.
Expand Down Expand Up @@ -231,7 +226,7 @@ make fix-cpp
make lint-py
# or
# python -m isort --check csp/ setup.py
# python -m ruff csp/ setup.py
# python -m ruff check csp/ setup.py
```

**Python Autoformatting**
Expand All @@ -243,6 +238,24 @@ make fix-py
# python -m ruff format csp/ setup.py
```

**Documentation Linting**

```bash
make lint-docs
# or
# python -m mdformat --check docs/wiki/ README.md examples/README.md
# python -m codespell_lib docs/wiki/ README.md examples/README.md
```

**Documentation Autoformatting**

```bash
make fix-docs
# or
# python -m mdformat docs/wiki/ README.md examples/README.md
# python -m codespell_lib --write docs/wiki/ README.md examples/README.md
```

## Testing

CSP has both Python and C++ tests. The bulk of the functionality is tested in Python, which can be run via `pytest`. First, install the Python development dependencies with
Expand Down
5 changes: 5 additions & 0 deletions docs/wiki/dev-guides/Contribute.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
Contributions are welcome on this project. We distribute under the terms of the [Apache 2.0 license](https://github.com/Point72/csp/blob/main/LICENSE).

> \[!NOTE\]
> CSP requires [Developer Certificate of Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) for all contributions.
> This is enforced by a [Probot GitHub App](https://probot.github.io/apps/dco/), which checks that commits are "signed".
> Read [instructions to configure commit signing](Local-Development-Setup#configure-commit-signing).
For **bug reports** or **small feature requests**, please open an issue on our [issues page](https://github.com/Point72/csp/issues).

For **questions** or to discuss **larger changes or features**, please use our [discussions page](https://github.com/Point72/csp/discussions).
Expand Down

0 comments on commit 4621584

Please sign in to comment.