further notes: add pip install -e . suggestion.

Additional issues: tox-conda is not compatible with tox 4, hit it in #2723 . I ended up adding an explicit 'tox>=3.27,<4' to the conda dev env instructions to get the right version.

(and I think python -m pip install tox will install tox 4? Or does it pick tox 3, which tox-conda restricts?)

this is an obvious thought, in retrospect, but: why don't we create a developer.yml conda environment file that people can use?

(this can be put into the CI as well)

this is an obvious thought, in retrospect, but: why don't we create a developer.yml conda environment file that people can use?

(this can be put into the CI as well)

Or pixi, I started a prototype branch in https://github.com/sourmash-bio/sourmash/compare/lirber/pixi and it works really well for setting up the dev env!

should also add instructions for plugins -

for working on a plugin, per @mr-eyes on slack -

• first git clone, checkout a new branch, then pip install -e .
• then edit the code and run locally until you get the expected results.
• Finally push and create a PR.

notes here: https://hackmd.io/4DwRHfSvQbioykT-vrfyfA?view

install sourmash for development purposes using conda

Create a conda environment with basic requirements:

mamba create -y -n sourmash-dev python=3.10 pip \
    cxx-compiler make rust

Clone sourmash repo

Get a copy of the sourmash repository:

git clone https://github.com/dib-lab/sourmash.git
cd sourmash

Activate conda repo and install

First activate the conda environment:

conda activate sourmash-dev

and then install sourmash:

python -m pip install -e ".[all]"

The -e option to pip install installs sourmash in "developer" mode, such that the installed package is simply a link to the current directory. Directing pip to install ".[all]" results in pip installing the package in the current directory (the . argument) with all of the documentation and test packages ([all]) as specified in pyproject.toml.

Run tests

You can now run all the Python tests like so:

python -m pytest 

Develop!

At this point you can change code, and then run the sourmash command yourself, and/or run tests.

If you change any sourmash Rust code, it is safest to run make first to (re)compile the Rust extension code, and then run the tests. (You don't need to run make if you're just changing Python code.)

make
python -m pytest

Once you've run make, you can run sourmash in that conda environment and it will run the version of sourmash in the git working directory.

Additional information

Running subsets of tests

You can run specific subsets of tests using pytest -k. For example, this:

python -m pytest -k sbt

will run any test that has sbt in the name.

Building documentation

You can build the docs like so:

cd doc
make

and then the built docs will be in _build/html/.

Changing/creating new branches

As long as you're in the directory that you installed, you can change branches and/or create new branches, and the sourmash command will run the code on the branch.

So, for example,

git switch branch_from_github

will change to the branch_from_github, and then git commit and git push will make commits and send those commits back to github.

These notes worked for me, with the addition of following this to test out a specific branch.

I like how the PyPA packaging guide has tabs for different options when listing commands, which might solve the confusion with our current docs (linear implies "you need to run them all").

Code: https://github.com/pypa/packaging.python.org/blob/83223a00484ddda6e516028ce97710adcc683f80/source/tutorials/installing-packages.rst
(it is RST blocks, but we can use them in markdown thru MyST)

bumping this -- what else is required for #2811?

our current mamba-based developer install doesn't work for macs

mamba create -n sourmash_dev 'tox>=3.27,<4' tox-conda rust git compilers pandoc libstdcxx-ng

Could not solve for environment specs
The following package could not be installed
└─ libstdcxx-ng   does not exist (perhaps a typo or a missing channel).