Skip to content

Commit a623b0e

Browse files
darsnackdarsnack
committed
add public facing environment and update installation instructions.
1 parent a18bc58 commit a623b0e

6 files changed

Lines changed: 8743 additions & 10 deletions

File tree

‎.github/workflows/publish-cheese3d-annotator.yaml‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ jobs:
1111
name: pypi
1212
permissions:
1313
id-token: write
14-
contents: read
14+
contents: write
1515
steps:
1616
- uses: actions/checkout@v4
1717
- name: Validate version matches tag
@@ -31,3 +31,26 @@ jobs:
3131
environments: default
3232
- name: Publish to PyPi
3333
run: pixi run publish-ci cheese3d-annotator
34+
- name: Refresh env lockfile and push
35+
run: |
36+
TAG_VERSION="${GITHUB_REF#refs/tags/cheese3d-annotator/v}"
37+
git config user.name "github-actions[bot]"
38+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
39+
git fetch origin main
40+
git checkout main
41+
for i in $(seq 1 10); do
42+
(cd public-env && pixi update --quiet cheese3d-annotator) || true
43+
if grep -q "cheese3d_annotator-${TAG_VERSION}-" public-env/pixi.lock; then
44+
echo "env lockfile now pins cheese3d-annotator ${TAG_VERSION}"
45+
break
46+
fi
47+
echo "cheese3d-annotator ${TAG_VERSION} not visible on PyPi yet, retrying in 30s..."
48+
sleep 30
49+
done
50+
if git diff --quiet public-env/pixi.lock; then
51+
echo "public-env/pixi.lock unchanged, nothing to commit"
52+
exit 0
53+
fi
54+
git add public-env/pixi.lock
55+
git commit -m "public-env: refresh lockfile for cheese3d-annotator v${TAG_VERSION}"
56+
git push origin main

‎.github/workflows/publish-cheese3d.yaml‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ jobs:
1111
name: pypi
1212
permissions:
1313
id-token: write
14-
contents: read
14+
contents: write
1515
steps:
1616
- uses: actions/checkout@v4
1717
- name: Validate version matches tag
@@ -31,3 +31,26 @@ jobs:
3131
environments: default
3232
- name: Publish to PyPi
3333
run: pixi run publish-ci cheese3d
34+
- name: Refresh env lockfile and push
35+
run: |
36+
TAG_VERSION="${GITHUB_REF#refs/tags/cheese3d/v}"
37+
git config user.name "github-actions[bot]"
38+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
39+
git fetch origin main
40+
git checkout main
41+
for i in $(seq 1 10); do
42+
(cd public-env && pixi update --quiet cheese3d) || true
43+
if grep -q "cheese3d-${TAG_VERSION}-" public-env/pixi.lock; then
44+
echo "env lockfile now pins cheese3d ${TAG_VERSION}"
45+
break
46+
fi
47+
echo "cheese3d ${TAG_VERSION} not visible on PyPi yet, retrying in 30s..."
48+
sleep 30
49+
done
50+
if git diff --quiet public-env/pixi.lock; then
51+
echo "public-env/pixi.lock unchanged, nothing to commit"
52+
exit 0
53+
fi
54+
git add public-env/pixi.lock
55+
git commit -m "public-env: refresh lockfile for cheese3d v${TAG_VERSION}"
56+
git push origin main

‎docs/source/guides/installation.rst‎

Lines changed: 30 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,34 +4,56 @@ Installation
44
Requirements
55
------------
66

7-
Cheese3D is a Python package with a few external dependencies. Our environment is managed by `Pixi <https://pixi.sh/latest/>`__. Install Pixi using (on macOS or Windows):
7+
Cheese3D is a Python package with a few external dependencies. Our environment is managed by `Pixi <https://pixi.sh/latest/>`__. Install Pixi using (on Linux or macOS):
88

99
.. code-block:: bash
1010
1111
curl -fsSL https://pixi.sh/install.sh | sh
1212
13+
Pixi is like Anaconda (i.e., ``conda``) but faster and more robust.
14+
1315
Setup
1416
-----
1517

16-
.. warning::
17-
18-
We are currently upstreaming changes in order to publish Cheese3D on PyPi. Until then, follow the instructions below to install Cheese3D directly from Github.
18+
Cheese3D is published on PyPi. We ship a minimal Pixi environment (``pixi.toml`` + ``pixi.lock``) that pins ``cheese3d``, ``cheese3d-annotator``, and the native dependencies (ffmpeg, CUDA, etc.) they need. You don't need to clone the repository, just download the two manifest files.
1919

20-
Clone the Cheese3D repository:
20+
Create a directory for the environment and fetch the manifest files:
2121

2222
.. code-block:: bash
2323
24-
git clone https://github.com/Hou-Lab-CSHL/cheese3d.git
24+
mkdir cheese3d && cd cheese3d
25+
curl -fsSLO https://raw.githubusercontent.com/Hou-Lab-CSHL/cheese3d/main/public-env/pixi.toml
26+
curl -fsSLO https://raw.githubusercontent.com/Hou-Lab-CSHL/cheese3d/main/public-env/pixi.lock
27+
28+
Now, you should have a folder called ``cheese3d`` with two files inside it: ``pixi.toml`` and ``pixi.lock``.
2529

26-
Setup the environment then activate it. Any future commands require activating the environment first.
30+
Activate the environment. Pixi will install everything on first use. Any future commands require activating the environment first.
2731

2832
.. code-block:: bash
2933
30-
cd cheese3d
3134
pixi shell
3235
3336
Installation should take a few minutes for each step to complete. If any step is taking too long, please open an issue (https://github.com/Hou-Lab-CSHL/cheese3d/issues).
3437

38+
.. note::
39+
40+
These instructions are for **using** Cheese3D. If you want to edit the source code for Cheese3D, see the `CONTRIBUTING guide <https://github.com/Hou-Lab-CSHL/cheese3d/blob/main/CONTRIBUTING.md>`__ for details.
41+
42+
Manual environment
43+
^^^^^^^^^^^^^^^^^^
44+
45+
Pixi installs everything into a ``.pixi/`` directory inside the ``cheese3d`` folder you just created. If you'd rather have a global environment or manage dependencies yourself (e.g., with ``conda``, ``mamba``, ``venv``, or system package managers), here is what Cheese3D needs:
46+
47+
- **Python** 3.10
48+
- **ffmpeg** >= 5.1.2
49+
- **NumPy** < 2.0
50+
- **CUDA** 11.7 and **cuDNN** 8 (Linux only, for GPU acceleration). Make sure these libraries are discoverable on ``LD_LIBRARY_PATH``; Pixi handles this automatically.
51+
- **Cheese3D** itself, from PyPi:
52+
53+
.. code-block:: bash
54+
55+
pip install cheese3d cheese3d-annotator
56+
3557
Platform-specific support
3658
-------------------------
3759

‎public-env/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# cheese3d install environment
2+
3+
A minimal [pixi](https://pixi.sh) workspace for end users who want to **run**
4+
Cheese3D. It installs `cheese3d` and `cheese3d-annotator` from PyPI plus the
5+
native dependencies (ffmpeg, CUDA, etc.) that those packages expect from conda.
6+
7+
## Maintainer notes
8+
9+
- `pixi.lock` is refreshed automatically by the `publish-cheese3d` and
10+
`publish-cheese3d-annotator` GitHub workflows. After each tag-triggered
11+
publish, the workflow re-runs `pixi update` here and pushes the resulting
12+
lockfile bump back to `main`.
13+
14+
- If you need to refresh it locally (e.g. to test before a release), run:
15+
16+
```sh
17+
cd public-env
18+
pixi update
19+
git add pixi.lock && git commit -m "public-env: refresh lockfile"
20+
```
21+
22+
- This workspace is intentionally separate from the root workspace so that the
23+
shipped `pixi.lock` does not include solver output for the `dev` / `docs`
24+
features. Keep the conda-side dependency list here in sync with the
25+
corresponding `[dependencies]` / `[target.*.dependencies]` blocks in
26+
`../pixi.toml` when those change.

0 commit comments

Comments
 (0)