docs: Fix and refine protocol setup docs #3

danwilliams · 2024-06-20T13:39:05Z

Refined the example build script

Corrected Cargo target directory.
Added checks and error-handling to the example build script.
Removed command to install Wasm target in favour of checking via rustup instead.
Removed hard-coded application name and obtained this via cargo instead.

Adjusted example Cargo.toml

Corrected path to SDK crate.
Adjusted app-release profile to strip symbols from the binary, and optimise LTO for speed.

Fixed complete code example

Added missing borsh configuration line.

- Corrected Cargo target directory. - Added checks and error-handling to the example build script. - Removed command to install Wasm target in favour of checking via rustup instead. - Removed hard-coded application name and obtained this via Cargo instead.

- Corrected path to SDK crate. - Adjusted app-release profile to strip symbols from the binary, and optimise LTO for speed.

- Added missing borsh configuration line.

miraclx · 2024-06-21T07:19:14Z

docs/03-build/01-protocol-sdks/02-protocol-rs-sdk.mdx

@@ -190,6 +215,7 @@ use calimero_sdk::{app, env};

 #[app::state]
 #[derive(Default, BorshSerialize, BorshDeserialize)]
+#[borsh(crate = "calimero_sdk::borsh")]


line 364 as well

miraclx · 2024-06-21T07:38:18Z

docs/03-build/01-protocol-sdks/02-protocol-rs-sdk.mdx

@@ -86,16 +87,17 @@ crate-type = ["cdylib"]

 # highlight-start
 [dependencies]
-calimero-sdk = { git = "https://github.com/calimero-network/core" }
+calimero-sdk = { git = "https://github.com/calimero-network/core/crates/sdk" }


this was correct actually, it should be

Suggested change

calimero-sdk = { git = "https://github.com/calimero-network/core/crates/sdk" }

calimero-sdk = { git = "https://github.com/calimero-network/core" }

although, I'd expect this to fail now because calimero-network/core is a private repo

I don't think it would work at all, as we use a workspace and the sdk crate is inside it...? When using the repo locally, I needed to specify the path to the crate.

as we use a workspace and the sdk crate is inside it

yeah, with git, cargo's behavior is to clone the repo, and then use it's root manifest to locate the member crate

but with the path field, you need to include the full path

even locally, if you use the git field, it needs to be the root of the repo

calimero-sdk = { git = "https://github.com/calimero-network/core" } calimero-sdk = { git = "file:///path/to/calimero-network/core" } calimero-sdk = { path = "/path/to/calimero-network/core/crates/sdk" }

It's probably due to it being private that it didn't work for me, then 🙂

miraclx · 2024-06-21T08:02:28Z

docs/03-build/01-protocol-sdks/02-protocol-rs-sdk.mdx

+# Get the application name from Cargo
+APP_ID=$(cargo pkgid)
+APP_NAME=${APP_ID#*#}
+APP_NAME=${APP_NAME%%:*}
+TARGET_DIR="${CARGO_TARGET_DIR:-target}"
+WASM_FILE="$TARGET_DIR/wasm32-unknown-unknown/app-release/$APP_NAME.wasm"
+
+# Build the application
 cargo build --target wasm32-unknown-unknown --profile app-release


bit tempted to leave this to cargo with --message-format json but that'll require a JSON parsing step

primarily because this parsing logic assumes the folder name won't match the package name

$ cargo metadata --format-version 1 | jq -r '.workspace_members[]' path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/crates/application#[email protected] path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/crates/network#[email protected] path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/crates/primitives#[email protected] path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/crates/identity#[email protected] path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/crates/node#[email protected] path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/crates/runtime#[email protected] path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/crates/server#[email protected] path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/crates/server-primitives#[email protected] path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/crates/store#[email protected] path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/crates/sdk#[email protected] path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/crates/sdk/macros#[email protected] path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/apps/kv-store#0.1.0 path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/apps/only-peers#0.1.0 path+file:///Users/miraclx/git/calimero-is-near/cali2.0-experimental/contracts/package-manager#0.1.0

as observed, the package name is only present post-# when its dir already isn't the package name

and secondarily.. it requires the developer to manually modify the build script if they're using it inside a workspace

alternatively, if we choose to rely on JSON serialization:

WASM_FILE=$( cargo build \ --target wasm32-unknown-unknown --profile app-release \ --message-format json-render-diagnostics \ | jq -r 'select(.target.name == "kv-store") | .filenames[] | select(endswith(".wasm"))' ) # if $wasm_file doesn't exist, maybe we didn't build the `cdylib`? check that `lib.crate-type` is well defined

I specifically tried to avoid JSON and jq, as it introduces another dependency 🙂 Hence using cargo pkgid instead of cargo metadata.

If you feel requiring jq is okay, I can make the change...? Or otherwise, I can adjust for the situation you mentioned?

Yeah, I'm torn here.. I don't like the required dependency, but at the same time, idk if any simple solution exists to get the correct default target directory for the crate (the secondary concern).

I guess it is an example... so not canon... and we do have the intention of creating a CLI, so this is somewhat temporary. In which case, maybe I am being too fussy about the extra dependency...?

It's a valid concern ngl, can't even guarantee everyone on the team has jq installed 😅

Getting the target folder wrong is also an interesting case, since cargo will implicitly create one.

miraclx · 2024-06-21T08:17:33Z

docs/03-build/01-protocol-sdks/02-protocol-rs-sdk.mdx

@@ -111,25 +113,48 @@ set -e

 cd "$(dirname $0)"

-TARGET="${CARGO_TARGET_DIR:-../../target}"
+# Check if rustup is installed


Some environments may not have rustup available, IIRC, termux was one of those platforms which had cargo and rustc in it's package manager, but not rustup.

Checking for the presence of the target's libdir is one solution to decoupling from rustup

test -d "$(rustc --target wasm32-unknown-unknown --print target-libdir)"

Perhaps if there's no rustup I should fall back to trying to use rustc directly? It's preferable to use rustup ideally.

Indifferent. But personally, I think I'd go with the simpler approach, since the only thing we need is to check for the presence of the target, that it's usable by rustc.. and not much else

Plus, this is in a doc, so I tried to keep it compact.. but at the same time Vuki's working on a template at calimero-network/core-app-template#2 so I guess that's okay.

The final shape is up to you though

MatejVukosav · 2024-07-04T14:07:46Z

@danwilliams what is the status with this PR? Is it still relevant?

danwilliams added 3 commits June 20, 2024 14:28

Adjusted example Cargo.toml

0af143c

- Corrected path to SDK crate. - Adjusted app-release profile to strip symbols from the binary, and optimise LTO for speed.

Fixed complete code example

3d002ae

- Added missing borsh configuration line.

danwilliams requested review from MatejVukosav and miraclx June 20, 2024 13:39

danwilliams self-assigned this Jun 20, 2024

miraclx reviewed Jun 21, 2024

View reviewed changes

MatejVukosav closed this Oct 21, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Fix and refine protocol setup docs #3

docs: Fix and refine protocol setup docs #3

danwilliams commented Jun 20, 2024

miraclx Jun 21, 2024

miraclx Jun 21, 2024

danwilliams Jun 21, 2024

miraclx Jun 21, 2024

danwilliams Jun 21, 2024

miraclx Jun 21, 2024 •

edited

Loading

miraclx Jun 21, 2024

danwilliams Jun 21, 2024

danwilliams Jun 21, 2024

miraclx Jun 21, 2024

danwilliams Jun 21, 2024

miraclx Jun 21, 2024

miraclx Jun 21, 2024

miraclx Jun 21, 2024

danwilliams Jun 21, 2024

miraclx Jun 21, 2024

MatejVukosav commented Jul 4, 2024

	calimero-sdk = { git = "https://github.com/calimero-network/core/crates/sdk" }
	calimero-sdk = { git = "https://github.com/calimero-network/core" }

docs: Fix and refine protocol setup docs #3

docs: Fix and refine protocol setup docs #3

Conversation

danwilliams commented Jun 20, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

miraclx Jun 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MatejVukosav commented Jul 4, 2024

miraclx Jun 21, 2024 •

edited

Loading