Skip to content

Commit

Permalink
Update README to document new developer pitfalls
Browse files Browse the repository at this point in the history
  • Loading branch information
andrew-signal authored Oct 23, 2024
1 parent e2b453f commit c3a3d5c
Showing 1 changed file with 52 additions and 7 deletions.
59 changes: 52 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,14 +41,31 @@ increases to the minimum supported tools versions.

# Building

### Toolchain Installation

To build anything in this repository you must have [Rust](https://rust-lang.org) installed,
as well as Clang, libclang, [CMake](https://cmake.org), Make, protoc, and git.

#### Linux/Debian

On a Debian-like system, you can get these extra dependencies through `apt`:

```shell
$ apt-get install clang libclang-dev cmake make protobuf-compiler git
```

#### macOS

On macOS, we have a best-effort maintained script to set up the Rust toolchain you can run by:

```shell
$ bin/mac_setup.sh
```

## Rust

### First Build and Test

The build currently uses a specific version of the Rust nightly compiler, which
will be downloaded automatically by cargo. To build and test the basic protocol
libraries:
Expand All @@ -60,8 +77,24 @@ $ cargo test
...
```

When making a PR that adjusts dependencies, you'll need to regenerate our acknowledgments files.
See [``acknowledgments/README.md``](acknowledgments/).
### Additional Rust Tools

The basic tools above should get you set up for most libsignal Rust development.

Eventually, you may find that you need some additional Rust tools like `cbindgen` to modify the bridges to the
client libraries or `taplo` for code formatting.

You should always install any Rust tools you need that may affect the build from cargo rather than from your system
package manager (e.g. `apt` or `brew`). Package managers sometimes contain outdated versions of these tools that can break
the build with incompatibility issues (especially cbindgen).

To install the main Rust extra dependencies matching the versions we use, you can run the following commands:

```shell
$ cargo +stable install cbindgen cargo-fuzz
$ cargo +stable install --version "$(cat ../acknowledgments/cargo-about-version)" --locked cargo-about
$ cargo +stable install --version "$(cat ../.taplo-cli-version)" --locked taplo-cli
```

## Java/Android

Expand Down Expand Up @@ -89,11 +122,7 @@ $ make
```

When exposing new APIs to Java, you will need to run `rust/bridge/jni/bin/gen_java_decl.py` in
addition to rebuilding. This requires installing the `cbindgen` Rust tool:

```shell
$ cargo +stable install cbindgen
```
addition to rebuilding. This requires installing the `cbindgen` Rust tool, as detailed above.

### Maven Central

Expand Down Expand Up @@ -172,6 +201,22 @@ the project.

Signing a [CLA (Contributor License Agreement)](https://signal.org/cla/) is required for all contributions.

## Code Formatting and Acknowledgments

You can run the styler on the entire project by running:

```shell
just format-all
```

You can run more extensive tests as well as linters and clippy by running:

```shell
just check-pre-commit
```

When making a PR that adjusts dependencies, you'll need to regenerate our acknowledgments files. See [``acknowledgments/README.md``](acknowledgments/).

# Legal things
## Cryptography Notice

Expand Down

0 comments on commit c3a3d5c

Please sign in to comment.