Improve top-level README's GettingStarted section
#39
Conversation
shannynat
force-pushed
the
103-readme-upgrade
branch
4 times, most recently
from
2461ead to
f94a55e
Compare
| [client's README](crates/aranya-client/README.md) has more information on using | ||
| the Rust client. | ||
|
|
||
| 2. `aranya-client-capi` C API |
There was a problem hiding this comment.
Have a couple questions here in the comments:
- When using the C api, how would the daemon be integrated/set-up? Would they still need the rust executable?
- What steps need to be taken to use the aranya-client-capi?
There was a problem hiding this comment.
When using the C API, a library containing the Aranya client will be provided along with the corresponding C header file. The daemon is the same executable regardless of whether the application is using a C API library or interfacing via a Rust API.
gknopf-aranya
requested review from
smckeon-so,
chip-so,
benz-spideroak and
ycarmy
| Or, add it to your project's `Cargo.toml`: | ||
| ``` | ||
| [dependencies] | ||
| aranya-daemon = { git = "[email protected]:aranya-project/aranya.git" } |
There was a problem hiding this comment.
Users will usually download an aranya daemon executable we build and publish in our cicd pipeline rather than building it themselves.
If it's an unsupported platform, then they'd need to build it themselves.
The daemon is one of the release artifacts here:
https://github.com/aranya-project/aranya/releases
| Aranya provides a client library and the daemon executable which processes | ||
| requests sent from the client and handles syncing with team members. | ||
|
|
||
| There are a few ways you can integrate the Aranya library into your project: |
There was a problem hiding this comment.
I'd have the items in the list together like this:
- Rust library
- C API
With markdown links to the relevant subsections.
| C API lets you call the aranya client from your C applications. | ||
| - In a real-world scenario, how would the daemon be integrated/set-up? | ||
| - Just the rust executable? | ||
| - What else would they need to do to set-up using the aranya-client-capi stuff? |
There was a problem hiding this comment.
You could take a look at the C API example to get an idea of the steps to integrate:
https://github.com/aranya-project/aranya/blob/main/examples/c/run.bash
Build the daemon or use a prebuilt executable.
Create the daemon config file and start the daemon while providing it a path to the config file.
Build a C application that imports the C API library & header file (e.g. with cmake) and start the application.
| - What else would they need to do to set-up using the aranya-client-capi stuff? | ||
| --> | ||
|
|
||
| Use the [`aranya-client-capi` C API](crates/aranya-client-capi/) to integrate |
There was a problem hiding this comment.
Or they can download the C API library for their target platform from the latest release:
https://github.com/aranya-project/aranya/releases/tag/v0.4.0
| `aranya-client-capi` C API. | ||
|
|
||
| <!-- TODO: verify this is accurate --> | ||
| In both cases, the Aranya client will need to communicate with the Aranya |
There was a problem hiding this comment.
The communication between the Aranya client and daemon is handled behind the scenes. Getting started with Aranya does not require this API to be understood. All the user needs to understand is the Aranya client's application API (e.g. the C API or Rust API the application is integrating with). There is an architecture diagram we could look at to see why that is.
|
|
||
| This example goes through the following steps: | ||
|
|
||
| Step 1: Configure, build and run the daemon for each user |
There was a problem hiding this comment.
Or use a pre-built daemon from the latest Aranya release
| Step 6. Submit an action to `Member A`'s daemon to create an Aranya Fast | ||
| Channel | ||
|
|
||
| Step 7. Call the Fast Channels API from `Member A`'s daemon to send a message. |
There was a problem hiding this comment.
The application is invoking the C API to send a message, not the daemon API
| Step 5. Submit actions to the `Operator`'s daemon to assign the Fast Channels | ||
| label to `Member A` and `Member B` | ||
|
|
||
| Step 6. Submit an action to `Member A`'s daemon to create an Aranya Fast |
There was a problem hiding this comment.
The application invokes the C API, which may translate to invoking an action via the daemon API behind the scenes. But the user doesn't need to know that in order to use the C API.
|
|
||
| #### Rust | ||
|
|
||
| ```rust |
There was a problem hiding this comment.
Let's wait until the Rust example app PR is merged before documenting this part:
#31
There was a problem hiding this comment.
The PR was merged, so we can borrow the Rust example code from there.
| The following snippet has been modified for simplicity. To see actual usage, | ||
| see the [C example](../examples/c/example.c#L162). | ||
|
|
||
| ```C |
There was a problem hiding this comment.
This C snippet seems like it belongs with step 2 of the above C application example
|
@shannynat could you push the "Update branch" button on this PR? |
|
@shannynat, @cmarsh-spideroak, @ycarmy, @smckeon-so I'm thinking we can complete reviewing the getting started guide and merge it in here. But right after it's merged, we'll want to move it over to |
This adds an `Integration & Development` section in place of `Getting Started` and includes initial information for downloading, building and using Aranya and examples.
shannynat
force-pushed
the
103-readme-upgrade
branch
from
f94a55e to
a5b57bd
Compare
@gknopf-aranya for whatever reason the ui isn't showing me the update branch button (i tried two different browsers) so had to rebase on main |
Co-authored-by: gknopf-aranya <[email protected]>
@gknopf-aranya just to make sure i'm understanding, we want to move This PR is just meant to update the top-level and C example readmes, I don't plan on updating the walkthrough here (though I did pull some snippets from that file for these updates). Edit: to clarify, if my understanding is correct, the walkthrough moving over the docs site is not blocked by this PR |
|
Sounds good |
|
@shannynat we'll want to move the getting started guide to the docs website after this PR is merged. cc: @ycarmy, @smckeon-so |
Update the README's
GettingStartedsection to include exact commands/versions for steps to download prereqs and the code, integration instructions, and higher level information about the examples.Closes #38.