diff --git a/develop/deprecation_policy.html b/develop/deprecation_policy.html index 8c94bf8057..3cae1c2ce2 100644 --- a/develop/deprecation_policy.html +++ b/develop/deprecation_policy.html @@ -157,6 +157,10 @@ version in future releases.

Details on the upstream support life cycles for Python and PostgreSQL are documented at https://endoflife.date/python and https://endoflife.date/postgresql.

+

A Rust compiler is required to build Synapse from source. For any given release +the minimum required version may be bumped up to a recent Rust version, and so +people building from source should ensure they can fetch recent versions of Rust +(e.g. by using rustup).

Context

It is important for system admins to have a clear understanding of the platform requirements of Synapse and its deprecation policies so that they can @@ -167,6 +171,12 @@ long process.

By following the upstream support life cycles Synapse can ensure that its dependencies continue to get security patches, while not requiring system admins to constantly update their platform dependencies to the latest versions.

+

For Rust, the situation is a bit different given that a) the Rust foundation +does not generally support older Rust versions, and b) the library ecosystem +generally bump their minimum support Rust versions frequently. In general, the +Synapse team will try to avoid updating the dependency on Rust to the absolute +latest version, but introducing a formal policy is hard given the constraints of +the ecosystem.

diff --git a/develop/development/contributing_guide.html b/develop/development/contributing_guide.html index c6e4c274a4..84356e5152 100644 --- a/develop/development/contributing_guide.html +++ b/develop/development/contributing_guide.html @@ -166,6 +166,8 @@ on Windows is not officially supported.

Synapse can connect to PostgreSQL via the psycopg2 Python library. Building this library from source requires access to PostgreSQL's C header files. On Debian or Ubuntu Linux, these can be installed with sudo apt install libpq-dev.

The source code of Synapse is hosted on GitHub. You will also need a recent version of git.

For some tests, you will need a recent version of Docker.

+

A recent version of the Rust compiler is needed to build the native modules. The +easiest way of installing the latest version is to use rustup.

3. Get the source.

The preferred and easiest way to contribute changes is to fork the relevant project on GitHub, and then create a pull request to ask us to pull your @@ -222,6 +224,10 @@ to check that your contributions render correctly. The docs are written in

Some documentation also exists in Synapse's GitHub Wiki, although this is primarily contributed to by community authors.

+

When changes are made to any Rust code then you must call either poetry install +or maturin develop (if installed) to rebuild the Rust code. Using maturin +is quicker than poetry install, so is recommended when making frequent +changes to the Rust code.

8. Test, test, test!

While you're developing and before submitting a patch, you'll @@ -270,7 +276,7 @@ working directory. Typically, this ends up being _trial_temp/test.dbThe database file can then be inspected with:

sqlite3 _trial_temp/test.db
-

Note that the database file is cleared at the beginning of each test run. Thus it +

Note that the database file is cleared at the beginning of each test run. Thus it will always only contain the data generated by the last run test. Though generally when debugging, one is only running a single test anyway.

Running tests under PostgreSQL

diff --git a/develop/print.html b/develop/print.html index bd0b3d5e99..09cf27ac28 100644 --- a/develop/print.html +++ b/develop/print.html @@ -360,6 +360,9 @@ and mounting it to /var/synapse should be taken into consideration.
  • Python 3.7 or later, up to Python 3.10.
  • At least 1GB of free RAM if you want to join large public rooms like #matrix:matrix.org
    • +

    If building on an uncommon architecture for which pre-built wheels are +unavailable, you will need to have a recent Rust compiler installed. The easiest +way of installing the latest version is to use rustup.

    To install the Synapse homeserver run:

    mkdir -p ~/synapse
 virtualenv -p python3 ~/synapse/env
@@ -14193,6 +14196,8 @@ on Windows is not officially supported.
    
 
    Synapse can connect to PostgreSQL via the psycopg2 Python library. Building this library from source requires access to PostgreSQL's C header files. On Debian or Ubuntu Linux, these can be installed with sudo apt install libpq-dev.
    
 
    The source code of Synapse is hosted on GitHub. You will also need a recent version of git.
    
 
    For some tests, you will need a recent version of Docker.
    
+
    A recent version of the Rust compiler is needed to build the native modules. The
+easiest way of installing the latest version is to use rustup.
    
 
    3. Get the source.
    
 
    The preferred and easiest way to contribute changes is to fork the relevant
 project on GitHub, and then create a pull request to ask us to pull your
@@ -14249,6 +14254,10 @@ to check that your contributions render correctly. The docs are written in
 
    Some documentation also exists in Synapse's GitHub
 Wiki, although this is primarily
 contributed to by community authors.
    
+
    When changes are made to any Rust code then you must call either poetry install
+or maturin develop (if installed) to rebuild the Rust code. Using maturin
+is quicker than poetry install, so is recommended when making frequent
+changes to the Rust code.
    
 
    8. Test, test, test!
    
 
    
 
    While you're developing and before submitting a patch, you'll
@@ -14297,7 +14306,7 @@ working directory. Typically, this ends up being _trial_temp/test.dbThe database file can then be inspected with:
    
 
    sqlite3 _trial_temp/test.db
 
    
-
    Note that the database file is cleared at the beginning of each test run. Thus it 
+
    Note that the database file is cleared at the beginning of each test run. Thus it
 will always only contain the data generated by the last run test. Though generally
 when debugging, one is only running a single test anyway.
    
 
    Running tests under PostgreSQL
    
@@ -16669,6 +16678,10 @@ version in future releases.
    
 
    Details on the upstream support life cycles for Python and PostgreSQL are
 documented at https://endoflife.date/python and
 https://endoflife.date/postgresql.
    
+
    A Rust compiler is required to build Synapse from source. For any given release
+the minimum required version may be bumped up to a recent Rust version, and so
+people building from source should ensure they can fetch recent versions of Rust
+(e.g. by using rustup).
    
 
    Context
    
 
    It is important for system admins to have a clear understanding of the platform
 requirements of Synapse and its deprecation policies so that they can
@@ -16679,6 +16692,12 @@ long process.
    
 
    By following the upstream support life cycles Synapse can ensure that its
 dependencies continue to get security patches, while not requiring system admins
 to constantly update their platform dependencies to the latest versions.
    
+
    For Rust, the situation is a bit different given that a) the Rust foundation
+does not generally support older Rust versions, and b) the library ecosystem
+generally bump their minimum support Rust versions frequently. In general, the
+Synapse team will try to avoid updating the dependency on Rust to the absolute
+latest version, but introducing a formal policy is hard given the constraints of
+the ecosystem.
    
 
    Summary of performance impact of running on resource constrained devices such as SBCs
    
 
    I've been running my homeserver on a cubietruck at home now for some time and am often replying to statements like "you need loads of ram to join large rooms" with "it works fine for me". I thought it might be useful to curate a summary of the issues you're likely to run into to help as a scaling-down guide, maybe highlight these for development work or end up as documentation. It seems that once you get up to about 4x1.5GHz arm64 4GiB these issues are no longer a problem.
    
 
+
    If building on an uncommon architecture for which pre-built wheels are
+unavailable, you will need to have a recent Rust compiler installed. The easiest
+way of installing the latest version is to use rustup.
    
 
    To install the Synapse homeserver run:
    
 
    mkdir -p ~/synapse
 virtualenv -p python3 ~/synapse/env