Skip to content

Commit 1db027c

Browse files
mgeiermgeier
committed
DOC: update installation instructions for uv
1 parent 2396662 commit 1db027c

File tree

3 files changed

+113
-92
lines changed

3 files changed

+113
-92
lines changed

‎CONTRIBUTING.rst‎

Lines changed: 40 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,48 +6,68 @@ please create an issue or a pull request at
66
https://github.com/spatialaudio/jackclient-python.
77
Contributions are always welcome!
88

9-
Instead of pip-installing the latest release from PyPI, you should get the
10-
newest development version from Github_::
9+
Instead of installing the latest release from PyPI_, you should get the
10+
newest development version from GitHub_::
1111

1212
git clone https://github.com/spatialaudio/jackclient-python.git
1313
cd jackclient-python
14-
python -m pip install -e .
15-
python jack_build.py
14+
uv sync
15+
uv run jack_build.py
1616

17-
... where ``-e`` stands for ``--editable``.
1817
This way, your installation always stays up-to-date, even if you pull new
19-
changes from the Github repository.
18+
changes from the GitHub repository.
2019

21-
.. _Github: https://github.com/spatialaudio/jackclient-python/
20+
.. _PyPI: https://pypi.org/project/JACK-Client/
21+
.. _GitHub: https://github.com/spatialaudio/jackclient-python/
2222

2323
.. note::
2424

2525
Whenever the file ``jack_build.py`` changes (either because you edited it or
26-
it was updated by pulling from Github or switching branches), you have to
26+
it was updated by pulling from GitHub or switching branches), you have to
2727
run the last command again.
2828

29-
If you make changes to the documentation, you can locally re-create the HTML
30-
pages using Sphinx_.
31-
You can install it and a few other necessary packages with::
3229

33-
python -m pip install -r doc/requirements.txt
30+
Building the Documentation
31+
^^^^^^^^^^^^^^^^^^^^^^^^^^
3432

35-
To create the HTML pages, use::
33+
If you make changes to the documentation,
34+
you can locally re-create the HTML pages using Sphinx_
35+
(which will be automatically installed as part of the development dependencies).
36+
From the main ``jackclient-python`` directory, run::
3637

37-
python -m sphinx doc _build
38+
uv run sphinx-build doc _build
3839

3940
The generated files will be available in the directory ``_build/``.
4041

4142
.. _Sphinx: https://www.sphinx-doc.org/
4243

43-
There are no proper tests (yet?), but the code examples from the README file
44-
can be verified with pytest_.
45-
If you haven't installed it already, you can install it with::
44+
While working on the documentation, it might be helpful to re-run Sphinx
45+
whenever something changes. This can be done with::
4646

47-
python -m pip install pytest
47+
uv run --with sphinx-autobuild sphinx-autobuild doc _build
4848

49-
As soon as pytest_ is installed, you can run the (rudimentary) tests with::
49+
Running the Tests
50+
^^^^^^^^^^^^^^^^^
5051

51-
python -m pytest
52+
There are no proper tests (yet?), but the code examples in the documentation
53+
can be verified with pytest_ (which is also part of the development dependencies).
54+
You can run the (rudimentary) tests with::
55+
56+
uv run python -m pytest
5257

5358
.. _pytest: https://pytest.org/
59+
60+
61+
Editable Installation
62+
^^^^^^^^^^^^^^^^^^^^^
63+
64+
If you want to work in a different directory on your own files,
65+
but using the latest development version (or a custom branch) of
66+
the ``jack`` module, you can switch to a directory of your choice
67+
and enter this::
68+
69+
uv init --bare
70+
uv add --editable --no-workspace path/to/your/jackclient-python/repo
71+
72+
You can install further packages with ``uv add`` and then run
73+
whatever you need with ``uv run``.

‎README.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,13 @@ JACK Audio Connection Kit (JACK) Client for Python
33

44
This Python module (named ``jack``) provides bindings for the JACK_ library.
55

6+
Quick Start:
7+
#. Install JACK, Python and (optionally) NumPy
8+
9+
#. Install the ``JACK-Client`` package for Python
10+
11+
#. Try the examples shown in the documentation
12+
613
Documentation:
714
https://jackclient-python.readthedocs.io/
815

‎doc/installation.rst‎

Lines changed: 66 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,78 @@
11
Installation
22
============
33

4-
.. image:: https://badge.fury.io/py/JACK-Client.svg
5-
:target: https://pypi.org/project/JACK-Client/
4+
Requirements
5+
------------
66

7-
You can use ``pip`` to install the ``jack`` module::
7+
The JACK_ library must be installed on your system (and CFFI must be able
8+
to find it). You should use your package manager to install it.
9+
Make sure you install the JACK daemon (called ``jackd``). This will also
10+
install the JACK library package.
11+
If you don't have a package manager, you can try one of the binary installers
12+
from the `JACK download page`_.
13+
If you prefer, you can of course also download the sources and compile
14+
everything locally.
815

9-
python -m pip install JACK-Client
16+
You'll also need to install Python_ if you haven't yet done so.
17+
There are many ways to install Python,
18+
and you can use any way you like,
19+
however, we recommend using uv_ as shown in the steps below.
1020

11-
Depending on your Python installation (see `Requirements`_ below),
12-
you may have to use ``python3`` instead of ``python``.
13-
If you have installed the module already, you can use the ``--upgrade`` flag to
14-
get the newest release.
21+
You can install ``uv`` with your favorite package manager,
22+
or by one of the other methods described at
23+
https://docs.astral.sh/uv/getting-started/installation/.
1524

16-
To un-install, use::
25+
If you don't like ``uv``, no problem!
26+
You can also use Python's official packaging tool pip_ or any other third-party tool,
27+
as long as it can install `the JACK-Client package`_.
1728

18-
python -m pip uninstall JACK-Client
29+
.. _JACK: https://jackaudio.org/
30+
.. _JACK download page: https://jackaudio.org/downloads/
31+
.. _Python: https://www.python.org/
32+
.. _uv: https://docs.astral.sh/uv/
33+
.. _pip: https://packaging.python.org/en/latest/tutorials/installing-packages/
34+
.. _the JACK-Client package: https://pypi.org/project/JACK-Client/
35+
.. _NumPy: http://www.numpy.org/
1936

20-
Requirements
37+
38+
Installation
2139
------------
2240

23-
You'll need some software packages in order to install and use the ``jack``
24-
module. Some of those might already be installed on your system and some are
25-
automatically installed when you use the aforementioned ``pip`` command.
26-
27-
Python:
28-
Of course, you'll need Python_. More specifically, you'll need Python 3.
29-
If you don't have Python installed yet, you should get one of the
30-
distributions which already include CFFI and NumPy (and many other useful
31-
things), e.g. Anaconda_ or WinPython_.
32-
33-
pip/setuptools:
34-
Those are needed for the installation of the Python module and its
35-
dependencies. Most systems will have these installed already, but if not,
36-
you should install it with your package manager or you can download and
37-
install ``pip`` and ``setuptools`` as described on the `pip installation`_
38-
page.
39-
If you happen to have ``pip`` but not ``setuptools``, use this command::
40-
41-
python -m pip install setuptools
42-
43-
To upgrade to a newer version of an already installed package (including
44-
``pip`` itself), use the ``--upgrade`` flag.
45-
46-
CFFI:
47-
The `C Foreign Function Interface for Python`_ is used to access the C-API
48-
of the JACK library from within Python. It is supported on CPython
49-
and is distributed with PyPy_. It will be automatically installed
50-
when installing the ``JACK-Client`` package with ``pip``.
51-
If you prefer, you can also install it with your package
52-
manager (the package might be called ``python3-cffi`` or similar).
53-
54-
JACK library:
55-
The JACK_ library must be installed on your system (and CFFI must be able
56-
to find it). Again, you should use your package manager to install it.
57-
Make sure you install the JACK daemon (called ``jackd``). This will also
58-
install the JACK library package.
59-
If you don't have a package manager, you can try one of the binary installers
60-
from the `JACK download page`_.
61-
If you prefer, you can of course also download the sources and compile
62-
everything locally.
63-
64-
NumPy (optional):
65-
NumPy_ is only needed if you want to access the input and output buffers in
66-
the process callback as NumPy arrays.
67-
The only place where NumPy is needed is `jack.OwnPort.get_array()`
68-
(and you can use `jack.OwnPort.get_buffer()` as a NumPy-less alternative).
69-
If you need NumPy, you can install it with your package manager or use a
70-
Python distribution that already includes NumPy (see above).
71-
You can also install NumPy with ``pip``, but depending on your platform, this
72-
might require a compiler and several additional libraries::
73-
74-
python -m pip install NumPy
41+
First, create a new directory wherever you want, change into it, then run::
7542

76-
.. _JACK: https://jackaudio.org/
77-
.. _NumPy: https://numpy.org/
78-
.. _Python: https://www.python.org/
79-
.. _Anaconda: https://www.anaconda.com/download/success
80-
.. _WinPython: http://winpython.github.io/
81-
.. _C Foreign Function Interface for Python: https://cffi.readthedocs.org/
82-
.. _PyPy: https://www.pypy.org/
83-
.. _JACK download page: https://jackaudio.org/downloads/
84-
.. _pip installation: https://pip.pypa.io/en/latest/installing/
43+
uv init --bare
44+
45+
This will create a file named ``pyproject.toml`` for you.
46+
Use the ``--help`` flag to see other options.
47+
48+
The ``jack`` module can now be installed with::
49+
50+
uv add JACK-Client
51+
52+
This will also create a file named ``uv.lock``, which tracks the exact versions
53+
of all installed packages.
54+
55+
NumPy_ is only needed if you want to access the input and output buffers in
56+
the process callback as NumPy arrays.
57+
The only place where NumPy is needed is `jack.OwnPort.get_array()`
58+
(and you can use `jack.OwnPort.get_buffer()` as a NumPy-less alternative).
59+
If you need NumPy, you can install it with::
60+
61+
uv add numpy
62+
63+
Similarly, you can install other Python-related tools::
64+
65+
uv add ...
66+
67+
Once everything is installed, you can start working with the editor/IDE/tool
68+
of your choice by simply prefixing it with ``uv run``, for example::
69+
70+
uv run python
71+
72+
If you have a Python script (for inspiration see :doc:`examples`),
73+
e.g. ``my_script.py``, you can run it with::
74+
75+
uv run my_script.py
76+
77+
If you want to install the latest development version of the JACK-Client,
78+
have a look at :doc:`contributing`.

0 commit comments

Comments
 (0)