diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 085e46c..e90b07a 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -6,48 +6,68 @@ please create an issue or a pull request at https://github.com/spatialaudio/jackclient-python. Contributions are always welcome! -Instead of pip-installing the latest release from PyPI, you should get the -newest development version from Github_:: +Instead of installing the latest release from PyPI_, you should get the +newest development version from GitHub_:: git clone https://github.com/spatialaudio/jackclient-python.git cd jackclient-python - python -m pip install -e . - python jack_build.py + uv sync + uv run jack_build.py -... where ``-e`` stands for ``--editable``. This way, your installation always stays up-to-date, even if you pull new -changes from the Github repository. +changes from the GitHub repository. -.. _Github: https://github.com/spatialaudio/jackclient-python/ +.. _PyPI: https://pypi.org/project/JACK-Client/ +.. _GitHub: https://github.com/spatialaudio/jackclient-python/ .. note:: Whenever the file ``jack_build.py`` changes (either because you edited it or - it was updated by pulling from Github or switching branches), you have to + it was updated by pulling from GitHub or switching branches), you have to run the last command again. -If you make changes to the documentation, you can locally re-create the HTML -pages using Sphinx_. -You can install it and a few other necessary packages with:: - python -m pip install -r doc/requirements.txt +Building the Documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^ -To create the HTML pages, use:: +If you make changes to the documentation, +you can locally re-create the HTML pages using Sphinx_ +(which will be automatically installed as part of the development dependencies). +From the main ``jackclient-python`` directory, run:: - python -m sphinx doc _build + uv run sphinx-build doc _build The generated files will be available in the directory ``_build/``. .. _Sphinx: https://www.sphinx-doc.org/ -There are no proper tests (yet?), but the code examples from the README file -can be verified with pytest_. -If you haven't installed it already, you can install it with:: +While working on the documentation, it might be helpful to re-run Sphinx +whenever something changes. This can be done with:: - python -m pip install pytest + uv run --with sphinx-autobuild sphinx-autobuild doc _build -As soon as pytest_ is installed, you can run the (rudimentary) tests with:: +Running the Tests +^^^^^^^^^^^^^^^^^ - python -m pytest +There are no proper tests (yet?), but the code examples in the documentation +can be verified with pytest_ (which is also part of the development dependencies). +You can run the (rudimentary) tests with:: + + uv run python -m pytest .. _pytest: https://pytest.org/ + + +Editable Installation +^^^^^^^^^^^^^^^^^^^^^ + +If you want to work in a different directory on your own files, +but using the latest development version (or a custom branch) of +the ``jack`` module, you can switch to a directory of your choice +and enter this:: + + uv init --bare + uv add --editable --no-workspace path/to/your/jackclient-python/repo + +You can install further packages with ``uv add`` and then run +whatever you need with ``uv run``. diff --git a/README.rst b/README.rst index e57b073..a5d5283 100644 --- a/README.rst +++ b/README.rst @@ -3,6 +3,13 @@ JACK Audio Connection Kit (JACK) Client for Python This Python module (named ``jack``) provides bindings for the JACK_ library. +Quick Start: + #. Install JACK, Python and (optionally) NumPy + + #. Install the ``JACK-Client`` package for Python + + #. Try the examples shown in the documentation + Documentation: https://jackclient-python.readthedocs.io/ diff --git a/doc/installation.rst b/doc/installation.rst index 4b50b7b..bf595ed 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -1,84 +1,78 @@ Installation ============ -.. image:: https://badge.fury.io/py/JACK-Client.svg - :target: https://pypi.org/project/JACK-Client/ +Requirements +------------ -You can use ``pip`` to install the ``jack`` module:: +The JACK_ library must be installed on your system (and CFFI must be able +to find it). You should use your package manager to install it. +Make sure you install the JACK daemon (called ``jackd``). This will also +install the JACK library package. +If you don't have a package manager, you can try one of the binary installers +from the `JACK download page`_. +If you prefer, you can of course also download the sources and compile +everything locally. - python -m pip install JACK-Client +You'll also need to install Python_ if you haven't yet done so. +There are many ways to install Python, +and you can use any way you like, +however, we recommend using uv_ as shown in the steps below. -Depending on your Python installation (see `Requirements`_ below), -you may have to use ``python3`` instead of ``python``. -If you have installed the module already, you can use the ``--upgrade`` flag to -get the newest release. +You can install ``uv`` with your favorite package manager, +or by one of the other methods described at +https://docs.astral.sh/uv/getting-started/installation/. -To un-install, use:: +If you don't like ``uv``, no problem! +You can also use Python's official packaging tool pip_ or any other third-party tool, +as long as it can install `the JACK-Client package`_. - python -m pip uninstall JACK-Client +.. _JACK: https://jackaudio.org/ +.. _JACK download page: https://jackaudio.org/downloads/ +.. _Python: https://www.python.org/ +.. _uv: https://docs.astral.sh/uv/ +.. _pip: https://packaging.python.org/en/latest/tutorials/installing-packages/ +.. _the JACK-Client package: https://pypi.org/project/JACK-Client/ +.. _NumPy: http://www.numpy.org/ -Requirements + +Installation ------------ -You'll need some software packages in order to install and use the ``jack`` -module. Some of those might already be installed on your system and some are -automatically installed when you use the aforementioned ``pip`` command. - -Python: - Of course, you'll need Python_. More specifically, you'll need Python 3. - If you don't have Python installed yet, you should get one of the - distributions which already include CFFI and NumPy (and many other useful - things), e.g. Anaconda_ or WinPython_. - -pip/setuptools: - Those are needed for the installation of the Python module and its - dependencies. Most systems will have these installed already, but if not, - you should install it with your package manager or you can download and - install ``pip`` and ``setuptools`` as described on the `pip installation`_ - page. - If you happen to have ``pip`` but not ``setuptools``, use this command:: - - python -m pip install setuptools - - To upgrade to a newer version of an already installed package (including - ``pip`` itself), use the ``--upgrade`` flag. - -CFFI: - The `C Foreign Function Interface for Python`_ is used to access the C-API - of the JACK library from within Python. It is supported on CPython - and is distributed with PyPy_. It will be automatically installed - when installing the ``JACK-Client`` package with ``pip``. - If you prefer, you can also install it with your package - manager (the package might be called ``python3-cffi`` or similar). - -JACK library: - The JACK_ library must be installed on your system (and CFFI must be able - to find it). Again, you should use your package manager to install it. - Make sure you install the JACK daemon (called ``jackd``). This will also - install the JACK library package. - If you don't have a package manager, you can try one of the binary installers - from the `JACK download page`_. - If you prefer, you can of course also download the sources and compile - everything locally. - -NumPy (optional): - NumPy_ is only needed if you want to access the input and output buffers in - the process callback as NumPy arrays. - The only place where NumPy is needed is `jack.OwnPort.get_array()` - (and you can use `jack.OwnPort.get_buffer()` as a NumPy-less alternative). - If you need NumPy, you can install it with your package manager or use a - Python distribution that already includes NumPy (see above). - You can also install NumPy with ``pip``, but depending on your platform, this - might require a compiler and several additional libraries:: - - python -m pip install NumPy +First, create a new directory wherever you want, change into it, then run:: -.. _JACK: https://jackaudio.org/ -.. _NumPy: https://numpy.org/ -.. _Python: https://www.python.org/ -.. _Anaconda: https://www.anaconda.com/download/success -.. _WinPython: http://winpython.github.io/ -.. _C Foreign Function Interface for Python: https://cffi.readthedocs.org/ -.. _PyPy: https://www.pypy.org/ -.. _JACK download page: https://jackaudio.org/downloads/ -.. _pip installation: https://pip.pypa.io/en/latest/installing/ + uv init --bare + +This will create a file named ``pyproject.toml`` for you. +Use the ``--help`` flag to see other options. + +The ``jack`` module can now be installed with:: + + uv add JACK-Client + +This will also create a file named ``uv.lock``, which tracks the exact versions +of all installed packages. + +NumPy_ is only needed if you want to access the input and output buffers in +the process callback as NumPy arrays. +The only place where NumPy is needed is `jack.OwnPort.get_array()` +(and you can use `jack.OwnPort.get_buffer()` as a NumPy-less alternative). +If you need NumPy, you can install it with:: + + uv add numpy + +Similarly, you can install other Python-related tools:: + + uv add ... + +Once everything is installed, you can start working with the editor/IDE/tool +of your choice by simply prefixing it with ``uv run``, for example:: + + uv run python + +If you have a Python script (for inspiration see :doc:`examples`), +e.g. ``my_script.py``, you can run it with:: + + uv run my_script.py + +If you want to install the latest development version of the JACK-Client, +have a look at :doc:`contributing`.