From a0fe0174dc34004c82e4c3e4c9b3c0e498bc7678 Mon Sep 17 00:00:00 2001 From: Lakshya Singh Date: Thu, 19 Jun 2025 08:33:12 +0530 Subject: [PATCH] chore: update docs for uv update commands and usage for uv --- contrib/pyln-client/README.md | 2 +- contrib/pyln-proto/README.md | 2 +- contrib/pyln-testing/README.md | 2 +- .../contributor-workflow.md | 31 +++++++++++++++++++ doc/contribute-to-core-lightning/testing.md | 8 ++++- doc/developers-guide/app-development/grpc.md | 12 ++----- .../app-development/json-rpc.md | 2 +- .../getting-started/installation.md | 21 +++++-------- plugins/grpc-plugin/README.md | 14 +++------ 9 files changed, 55 insertions(+), 39 deletions(-) diff --git a/contrib/pyln-client/README.md b/contrib/pyln-client/README.md index 959127044..38d2ae0ea 100644 --- a/contrib/pyln-client/README.md +++ b/contrib/pyln-client/README.md @@ -21,7 +21,7 @@ installing into your python3 environment: ```bash git clone https://github.com/ElementsProject/lightning.git cd lightning/contrib/pyln-client -poetry install +uv sync ``` This will add links to the library into your environment so changing the diff --git a/contrib/pyln-proto/README.md b/contrib/pyln-proto/README.md index 8914b3226..ca48ceeb7 100644 --- a/contrib/pyln-proto/README.md +++ b/contrib/pyln-proto/README.md @@ -21,7 +21,7 @@ installing into your python3 environment: ```bash git clone https://github.com/ElementsProject/lightning.git cd lightning/contrib/pyln-proto -poetry install +uv sync ``` This will add links to the library into your environment so changing the diff --git a/contrib/pyln-testing/README.md b/contrib/pyln-testing/README.md index 2c89fa9bd..78850cdc5 100644 --- a/contrib/pyln-testing/README.md +++ b/contrib/pyln-testing/README.md @@ -23,7 +23,7 @@ installing into your python3 environment: ```bash git clone https://github.com/ElementsProject/lightning.git cd lightning/contrib/pyln-testing -poetry install +uv sync --extra grpc ``` This will add links to the library into your environment so changing the diff --git a/doc/contribute-to-core-lightning/contributor-workflow.md b/doc/contribute-to-core-lightning/contributor-workflow.md index 30a610b83..1d59f9de8 100644 --- a/doc/contribute-to-core-lightning/contributor-workflow.md +++ b/doc/contribute-to-core-lightning/contributor-workflow.md @@ -35,6 +35,37 @@ It will also print out (to stderr) the gdb command for manual connection. The s make -j$(nproc) ``` +## Building Python Packages + +Core Lightning includes several Python packages in the workspace that can be built individually or all at once: + +```shell +# Build all Python packages +make pyln-build-all + +# Build individual packages +make pyln-build-client +make pyln-build-proto +make pyln-build-testing +make pyln-build-grpc-proto + +# Build bolt specification packages +make pyln-build-bolt1 +make pyln-build-bolt2 +make pyln-build-bolt4 +make pyln-build-bolt7 + +# Build wss-proxy plugin +make pyln-build-wss-proxy +``` + +You can also build packages directly with uv: + +```shell +uv build contrib/pyln-client/ +uv build contrib/pyln-proto/ +``` + ## Making BOLT Modifications All of code for marshalling/unmarshalling BOLT protocol messages is generated directly from the spec. These are pegged to the BOLTVERSION, as specified in `Makefile`. diff --git a/doc/contribute-to-core-lightning/testing.md b/doc/contribute-to-core-lightning/testing.md index 9d0558ab2..c7092a8de 100644 --- a/doc/contribute-to-core-lightning/testing.md +++ b/doc/contribute-to-core-lightning/testing.md @@ -39,13 +39,19 @@ There are four kinds of tests: - **blackbox tests** - These tests setup a mini-regtest environment and test lightningd as a whole. They can be run individually: - `PYTHONPATH=contrib/pyln-client:contrib/pyln-testing:contrib/pyln-proto:contrib/pyln-grpc-proto py.test -v tests/` + `uv run python -m pytest -v tests/` + + Note: For testing that requires grpc functionality, ensure you have the grpc extras installed: `uv sync --extra grpc` You can also append `-k TESTNAME` to run a single test. Environment variables `DEBUG_SUBD=[:]` (where path must match the end of the lightning daemon path, for matching only one of several lightningd instances) and `TIMEOUT=` can be useful for debugging subdaemons on individual tests, and `DEBUG_LIGHTNINGD` for attaching a debugger to each `lightningd` instance created. Alternatively, to run a specific test via the `Makefile`, you can specify the test by setting the environment variable `PYTEST_TESTS`: `PYTEST_TESTS="tests/test_askrene.py::test_layers" make pytest` + + Or run tests directly with uv: + + `uv run python -m pytest tests/test_askrene.py::test_layers -v` - **pylightning tests** - will check contrib pylightning for codestyle and run the tests in `contrib/pylightning/tests` afterwards: diff --git a/doc/developers-guide/app-development/grpc.md b/doc/developers-guide/app-development/grpc.md index 8c0e67b8f..50f5345a5 100644 --- a/doc/developers-guide/app-development/grpc.md +++ b/doc/developers-guide/app-development/grpc.md @@ -35,18 +35,10 @@ The gRPC interface is described in the [protobuf file](https://github.com/Elemen In this tutorial, we walk through the steps for Python, however they are mostly the same for other languages. For instance, if you're developing in Rust, use [`tonic-build`](https://docs.rs/tonic-build/latest/tonic_build/) to generate the bindings. For other languages, see the official [gRPC docs](https://grpc.io/docs/languages/) on how to generate gRPC client library for your specific language using the protobuf file. -We start by downloading the dependencies and `protoc` compiler: - -```shell -pip install grpcio-tools -``` - - - -Next we generate the bindings in the current directory: +We generate the bindings in the current directory: ```bash -python -m grpc_tools.protoc \ +uv run -m grpc_tools.protoc \ -I path/to/cln-grpc/proto \ path/to/cln-grpc/proto/node.proto \ --python_out=. \ diff --git a/doc/developers-guide/app-development/json-rpc.md b/doc/developers-guide/app-development/json-rpc.md index ecf1641d6..f140f046a 100644 --- a/doc/developers-guide/app-development/json-rpc.md +++ b/doc/developers-guide/app-development/json-rpc.md @@ -34,7 +34,7 @@ Alternatively you can also install the development version to get access to curr ```shell git clone https://github.com/ElementsProject/lightning.git cd lightning/contrib/pyln-client -poetry install +uv sync ``` diff --git a/doc/getting-started/getting-started/installation.md b/doc/getting-started/getting-started/installation.md index 595907713..3c9a23ff5 100644 --- a/doc/getting-started/getting-started/installation.md +++ b/doc/getting-started/getting-started/installation.md @@ -79,10 +79,10 @@ sudo apt-get install -y \ jq autoconf automake build-essential git libtool libsqlite3-dev libffi-dev \ python3 python3-pip net-tools zlib1g-dev libsodium-dev gettext pip3 install --upgrade pip -pip3 install --user poetry +curl -LsSf https://astral.sh/uv/install.sh | sh ``` -(If installing `poetry` with `pip` as above fails, try installing it with the [official poetry installer](https://python-poetry.org/docs/#installing-with-the-official-installer).) +After installing uv, restart your shell or run `source ~/.bashrc` to ensure `uv` is in your PATH. If you don't have Bitcoin installed locally you'll need to install that as well. It's now available via [snapd](https://snapcraft.io/bitcoin-core). @@ -113,7 +113,6 @@ For development or running tests, get additional dependencies: ```shell sudo apt-get install -y valgrind libpq-dev shellcheck cppcheck \ libsecp256k1-dev lowdown -pip3 install pytest ``` If you can't install `lowdown`, a version will be built in-tree. @@ -134,9 +133,9 @@ There are two ways to build core lightning, and this depends on how you want use To build CLN for production: ```shell -poetry install +uv sync --all-extras --all-groups ./configure -RUST_PROFILE=release poetry run make +RUST_PROFILE=release uv run make sudo RUST_PROFILE=release make install ``` @@ -147,16 +146,10 @@ sudo RUST_PROFILE=release make install To build CLN for development: ```shell -poetry shell -``` - -This will put you in a new shell to enter the following commands: - -```shell -poetry install +uv sync --all-extras --all-groups ./configure -make -make check VALGRIND=0 +uv run make +uv run make check VALGRIND=0 ``` Optionally, add `-j$(nproc)` after `make` to speed up compilation. (e.g. `make -j$(nproc)`) diff --git a/plugins/grpc-plugin/README.md b/plugins/grpc-plugin/README.md index 0894c49e1..4dc5b81ff 100644 --- a/plugins/grpc-plugin/README.md +++ b/plugins/grpc-plugin/README.md @@ -23,7 +23,7 @@ if they don't already exist: - `client.pem` and `client-key.pem`: this is an example identity that can be used by a client to connect to the plugin, and issue requests. It is also signed by the CA. - + These files are generated with sane defaults, however you can generate custom certificates should you require some changes (see below for details). @@ -39,16 +39,10 @@ bindings. In this example we walk through the steps for python, however they are mostly the same for other languages. -We start by downloading the dependencies and `protoc` compiler: +We generate the bindings in the current directory: ```bash -pip install grpcio-tools -``` - -Next we generate the bindings in the current directory: - -```bash -python -m grpc_tools.protoc \ +uv run -m grpc_tools.protoc \ -I path/to/cln-grpc/proto \ path/to/cln-grpc/proto/node.proto \ --python_out=. \ @@ -62,7 +56,7 @@ This will generate two files in the current directory: exchanging with the server. - `node_pb2_grpc.py`: the service and method stubs representing the server-side methods as local objects and associated methods. - + And finally we can use the generated stubs and mTLS identity to connect to the node: