From 1e3aec22ea907e33927ea523f8d514d09aaef1a9 Mon Sep 17 00:00:00 2001 From: Soc Virnyl Estela Date: Tue, 5 Nov 2024 22:28:18 +0800 Subject: [PATCH] docs: enhance README Signed-off-by: Soc Virnyl Estela --- README.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 141 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1e9d38e..4b67455 100644 --- a/README.md +++ b/README.md @@ -244,14 +244,129 @@ specifically, `$CARGO_HOME/registry`. The service file will look like this true registry true - rust/pvsecret + rust/pvsecret/Cargo.toml + rust/pv/Cargo.toml + rust/utils/Cargo.toml ``` -The logic is similar but the results of vendoring the home registry results to lessened mental strain when trying -to simplify the build process in the specfile. Here is what it looks like +Another example would be libflux. It can have three different configurations and we include **vendor** method for comparisons. + +**Registry method variant 1** +```xml + + + + flux*.tar.gz + true + registry + true + libflux/Cargo.toml + + + +``` + +> [!NOTE] +> You have to decide when to set `no-root-manifest` to true or false. +> A big mistake here is you know that the project has a crate +> with a clear "root" manifest but not in the top-most level +> directory, so you accidentally set it to true. When we refer +> to `no-root-manifest`, we are actually referring to the fact +> that the "root" manifest is not at the top-most level of the directory. + +**Registry method variant 2** +```xml + + + + flux*.tar.gz + true + registry + libflux + + + +``` + +> [!NOTE] +> The second registry method variant is cleaner, as it avoids setting `no-root-manifest` +> and it's pretty clear that we are actually defining a **custom** +> **root** here. + +**Vendor method** +```xml + + + + flux*.tar.gz + true + libflux + + + +``` +> [!NOTE] +> The **vendor method** is cleaner than the previous. As we said before, there is a clear +> location of where our "root" manifest is. + +If we extract the contents of `registry.tar.zst` for both registry variants, you will get a tree like this + +``` +. +├── .cargo +│   └── registry +│ +└── libflux + └── Cargo.lock +``` + +As for **vendor method**, we get this instead. + +``` +. +└── libflux + ├── .cargo + ├── Cargo.lock + └── vendor + +``` + +It's good to know why this happens and why it's decided to be like this. For example, if one decides to use the +vendor method, they can just add this to their specfile on the build section. + +``` +%build +pushd libflux +%cargo_build +popd +``` + +The register method looks like this. + +``` +%build +export CARGO_HOME=$PWD/.cargo +pushd libflux +%cargo_build +popd +``` + +One caveat with **vendor** method is it can only do *one* thing, so we ended up littered with many +vendored tarballs. While for **registry**, we can have one registry tarball and that's it. +You can see how advantageous it is when you look back at the s390-tools example at the +[beginning](#cargo-vendor-home-registry) of this section. + +In conclusion, the logic is similar but the results of vendoring the home registry +results to lessened mental strain when trying to simplify the +build process in the specfile. Here is what it looks like. + +> [!WARN] +> This is just a theoretical scenario with s390-tools. This +> kind of specfile has not been tested whatsoever. It only +> serves as demonstration. ``` @@ -260,22 +375,44 @@ to simplify the build process in the specfile. Here is what it looks like %build export CARGO_HOME=$PWD/.cargo +pushd rust/pv %{cargo_build} +popd +pushd rust/pvsecret +%{cargo_build} +popd %install export CARGO_HOME=$PWD/.cargo +pushd rust/pv +%{cargo_install} +popd +pushd rust/pvsecret %{cargo_install} +popd %check export CARGO_HOME=$PWD/.cargo +pushd rust/pv %{cargo_test} +popd +pushd rust/pvsecret +%{cargo_test} +popd + ``` This attempt started in this repository but now, -it's been merged to avoid maintenance burden. As the old repository will retire, it still remains there for those that +it's been merged here to avoid maintenance burden. As the old repository will retire, it still remains there for those that are curious about how we go from there to here. +> [!IMPORTANT] +> Overall, both methods are not perfect. But with the right combination of `--custom-root` and `--no-root-manifest`, +> it gets easier if you're able to find that combination. +> You can see more in the [./cargo/tests/behaviour.rs](./cargo/tests//behaviour.rs) for +> such combinations. + Filtering is not supported in this method. See more in the [./cargo_vendor.service](./cargo_vendor.service) file or the [Parameters](#parameters) section below.