Skip to content

Commit 28679a0

Browse files
authored
Merge pull request #3676 from reubenmiller/docs-update-build-instructions
docs: update build instructions
2 parents a994286 + 09d729f commit 28679a0

File tree

1 file changed

+125
-122
lines changed

1 file changed

+125
-122
lines changed

docs/src/contribute/build.md

Lines changed: 125 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -8,210 +8,213 @@ This page details how to build %%te%% from the source code.
88

99
## Requirements
1010

11-
You can use any OS to build from source (below has been tested on Ubuntu, but we also use Debian, macOS, and FreeBSD successfully).
11+
Whilst you should be able to build %%te%% on different Operating Systems and CPU architectures, it is best to stick with one of the following setups if you would like support when something goes wrong.
1212

13-
Our recommended setup and required tools are:
14-
15-
* Ubuntu 20.04 or Debian 12 (Bookworm)
13+
* One of the following Operating Systems
14+
* Linux (we recommend using either Debian or Ubuntu)
15+
* WSL 2 (Windows Subsystem for Linux)
16+
* macOS
1617
* git
17-
* Rust toolchain
18+
* Rust toolchain, the Minimum Supported Rust Version (MSRV) is 1.78
19+
* [just](https://github.com/casey/just)
1820

19-
Following packages are required:
21+
A list of our test platforms can be found [here](../references/supported-platforms.md).
2022

21-
* build-essentials
22-
* curl
23-
* gcc
23+
### Initial setup
2424

25-
A list of our test platforms can be found [here](../references/supported-platforms.md).
25+
The instructions below walk you through the process of installing the required tools and checking out the project for the first time.
2626

27-
## Get the code
27+
1. Install the dependencies
2828

29-
%%te%% code is in git repository on github to acquire the code use following command:
29+
```sh tab={"label":"macOS"}
30+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
31+
cargo install just
32+
```
3033

31-
* via SSH:
34+
```sh tab={"label":"Linux"}
35+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
36+
cargo install just
37+
```
3238

33-
```sh
34-
git clone git@github.com:thin-edge/thin-edge.io.git
35-
```
39+
```sh tab={"label":"WSL2"}
40+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
41+
cargo install just
42+
```
3643

37-
* or via HTTPS:
44+
:::note
45+
46+
* If you have any problems installing Rust then consult the [official Rust installation guide](https://www.rust-lang.org/tools/install).
47+
* [just](https://just.systems/) is also written in Rust, so it can also be installed directly using Rust's package manager, Cargo.
48+
:::
3849
39-
```sh
40-
git clone https://github.com/thin-edge/thin-edge.io.git
41-
```
4250
43-
## Installing toolchain
51+
2. Checkout the project
4452
45-
### Rust toolchain
53+
:::tip
54+
If you plan on contributing to the project, then please [fork the project](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) first, then clone your fork instead of the main project.
55+
:::
4656
47-
To install Rust follow [Official installation guide](https://www.rust-lang.org/tools/install).
48-
To get started you need Cargo's bin directory (`$HOME/.cargo/bin`) in your `PATH` environment variable.
57+
The %%te%% source is hosted in a git repository by GitHub, so you can get the project by using the one of the following commands:
4958
50-
```sh
51-
export PATH=$PATH:$HOME/.cargo/bin
52-
```
59+
```sh tab={"label":"HTTPS"}
60+
git clone https://github.com/thin-edge/thin-edge.io.git
61+
cd thin-edge.io
62+
```
63+
64+
```sh tab={"label":"SSH"}
65+
git clone git@github.com:thin-edge/thin-edge.io.git
66+
cd thin-edge.io
67+
```
68+
69+
```sh tab={"label":"GitHub CLI"}
70+
gh repo clone thin-edge/thin-edge.io
71+
cd thin-edge.io
72+
```
73+
74+
5375
54-
And then you can run `rustc` to view current version:
76+
## Building
77+
78+
### Build Packages
79+
80+
By default, if no target is provided, then the target architecture will be automatically detected, and the linux variant will be chosen.
5581
5682
```sh
57-
rustc --version
83+
just release
5884
```
5985
6086
```text title="Output"
61-
rustc 1.65.0 (897e37553 2022-11-02)
87+
target/aarch64-unknown-linux-gnu/packages
6288
```
6389
6490
:::note
65-
Above command will add rust to path only for existing session,
66-
after you restart the session you will have to add it again,
67-
to add rust to the path permanently it will depend on your shell but for Bash,
68-
you simply need to add the line from above, `export PATH=$PATH:$HOME/.cargo/bin` to your `~/.bashrc`.
91+
For macOS users, `just release` will use chose the default target based on your machine's CPU architecture. The table below shows the default targets based on the type of CPU architecture of your machine.
6992

70-
For other shells, you'll want to find the appropriate place to set a configuration at start time,
71-
eg. zsh uses `~/.zshrc`. Check your shell's documentation to find what file it uses.
93+
|Processor|Default Target|
94+
|---|--------------|
95+
|Apple Silicon|aarch64-unknown-linux-musl|
96+
|Intel (x86_64) processor|x86_64-unknown-linux-musl|
7297
:::
7398

74-
%%te%% operates the `MSRV` (Minimum Supported Rust Version) and uses stable toolchain.
99+
You can build for other targets (e.g. cross compiling), by simply providing the Rust target as an additional argument:
75100

76-
Current MSRV is `1.65`.
101+
```sh
102+
# Intel/AMD (64 bit)
103+
just release x86_64-unknown-linux-musl
77104
78-
### Cross compilation toolchain (optional)
105+
# Intel/AMD (32 bit)
106+
just release i686-unknown-linux-musl
79107
80-
%%te%% can be compiled for target architecture on non-target device, this is called cross compilation.
81-
Currently we support `Raspberry Pi 3B` for `armv7` architecture with Rust's cross compilation toolchain called [cargo cross](https://github.com/cross-rs/cross).
108+
# arm64 (64 bit), e.g. Raspberry Pi 3, 4, 5
109+
just release aarch64-unknown-linux-musl
82110
83-
To install [cargo cross](https://github.com/cross-rs/cross):
111+
# armv7 (32 bit), e.g. Raspberry Pi 2, 3
112+
just release armv7-unknown-linux-musleabihf
84113
85-
```sh
86-
cargo install cross
114+
# armv6 (32 bit, hard-float), e.g. Raspberry Pi 1
115+
just release arm-unknown-linux-musleabihf
87116
```
88117

89-
### Linux packaging (optional)
118+
:::tip
119+
By default, [cargo-zigbuild](https://github.com/rust-cross/cargo-zigbuild) is used for cross compilation as it has minimal dependencies and works on different host machines (e.g. aarch64 or x86_64) without requiring docker. You are free to use other cross compilation tools, however we might not be able to give advice if it does not work.
90120

91-
We use [nfpm](https://github.com/goreleaser/nfpm) to build our linux packages (deb, rpm and apk).
121+
If you're looking to build other targets, then have a look at our [build-workflow](https://github.com/thin-edge/thin-edge.io/blob/main/.github/workflows/build-workflow.yml) as it provides another way to build the project but it requires a host machine with an x86_64 CPU.
122+
:::
92123
93-
Follow the [nfpm install instructions](https://nfpm.goreleaser.com/install/) to install the dependency. The linux packages will automatically be built when running `just release`.
124+
The `release` task will also build the linux packages, e.g. dep, rpm, apk and plain tarballs. Under the hood, we use [nfpm](https://github.com/goreleaser/nfpm) for the packaging. The task will attempt to installing it for you, however if that fails, you can manually install it by following the [nfpm install instructions](https://nfpm.goreleaser.com/install/).
94125
126+
### Build Linux virtual packages
95127
96-
```sh
97-
just release
98-
```
128+
%%te%% is composed of multiple packages (e.g. tedge, tedge-agent, tedge-mapper), so installing all of them can be complicated for new users, so to make this easier, we also create two virtual packages which allow you to install different combinations of the packages from a single package name. The virtual packages don't include any code themselves, they just have specific packages listed as dependencies so that the package manager will automatically install all of the dependencies when installing the virtual package.
99129

100-
The virtual packages (e.g. `tedge-full` and `tedge-minimal`) can be built using the following command:
130+
The Linux virtual packages (e.g. `tedge-full` and `tedge-minimal`) can be built using the following command:
101131

102132
```sh
103133
just release-linux-virtual
104134
```
105135

106-
## Compiling
107-
108-
To build %%te%% we are using `cargo`.
109-
110-
As we are using `cargo workspace` for all our crates. All compiled files are put in `./target/` directory with target's name eg: `./target/debug` or `./target/release` for native builds and for cross compiled targets `./target/<architecture>/debug` or `./target/<architecture>/release` dependent on the target of the build.
111-
112-
### Compiling dev
113-
114-
To compile dev profile (with debug symbols) we use following command:
115-
116-
```sh
117-
cargo build
118-
```
136+
```text title="Output"
137+
-----------------------------------------------------
138+
thin-edge.io packager: build_virtual
139+
-----------------------------------------------------
140+
Parameters
119141
120-
Build artifacts can be found in `./target/debug` and will include executables:
142+
packages:
143+
version:
144+
types: deb,apk,rpm,tarball
145+
output_dir: target/virtual-packages
121146
122-
```sh
123-
ls -l ./target/debug/tedge*
124-
```
147+
Cleaning output directory: target/virtual-packages
148+
using deb packager...
149+
created package: target/virtual-packages/tedge-full_1.4.3~230+gcfaf55d_all.deb
150+
using rpm packager...
151+
created package: target/virtual-packages/tedge-full-1.4.3~230+gcfaf55d-1.noarch.rpm
152+
using apk packager...
153+
created package: target/virtual-packages/tedge-full_1.4.3_rc230+gcfaf55d_pr0_noarch.apk
154+
using deb packager...
155+
created package: target/virtual-packages/tedge-minimal_1.4.3~230+gcfaf55d_all.deb
156+
using rpm packager...
157+
created package: target/virtual-packages/tedge-minimal-1.4.3~230+gcfaf55d-1.noarch.rpm
158+
using apk packager...
159+
created package: target/virtual-packages/tedge-minimal_1.4.3_rc230+gcfaf55d_pr0_noarch.apk
125160
126-
```text title="Output"
127-
-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge
128-
-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge-mapper
161+
Successfully created packages
129162
```
130163

131-
Binaries can be run eg: `./target/debug/tedge`.
132-
Alternatively, you can use `cargo` to build and run executable in a single command:
164+
## Development
133165

134-
```sh
135-
cargo run --bin tedge
136-
```
166+
### Build (debug)
137167

138-
### Compiling release
139-
140-
To compile release profile we use following command:
168+
To build a non-optimized binary with debugging information, use the following command:
141169

142170
```sh
143-
cargo build --release
171+
cargo build
144172
```
145173

146-
Build artifacts can be found in `./target/release` and will include executables:
174+
Build artifacts can be found in `./target/debug` and will include the executable:
147175

148176
```sh
149-
ls -l ./target/release/tedge*
177+
ls -l ./target/debug/tedge
150178
```
151179

152180
```text title="Output"
153181
-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge
154-
-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge-mapper
155182
```
156183

157-
Binaries can be run eg: `./target/release/tedge`.
158-
159-
## Building deb package
160-
161-
Currently %%te%% contains 2 binaries, `tedge` (cli) and `tedge-mapper` which are packaged as separate debian packages. To create following commands are to be issued:
162-
163-
```sh
164-
cargo deb -p tedge
165-
cargo deb -p tedge-mapper
166-
```
184+
:::note
185+
The `tedge` is a multi-call binaries, which means that the single binary includes the core components of %%te%%, e.g. tedge, tedge-agent, tedge-mapper etc.
167186

168-
All resulting packages are going to be in: `./target/debian/` directory:
187+
The easiest way to run a specific component manually is to use the `tedge run <component>` command, for example:
169188

170189
```sh
171-
ls -l ./target/debian
172-
```
173-
174-
```text title="Output"
175-
total 2948
176-
-rw-rw-r-- 1 user user 11111 Jan 1 00:00 tedge_0.9.0_amd64.deb
177-
-rw-rw-r-- 1 user user 11111 Jan 1 00:00 tedge-mapper_0.9.0_amd64.deb
190+
tedge run tedge-agent
178191
```
179192

180-
## Cross compiling
181-
182-
To create binaries which can run on different platform than one you are currently on you can use [cargo cross](https://github.com/cross-rs/cross):
183-
184-
```sh
185-
cross build --target armv7-unknown-linux-gnueabihf
186-
```
193+
You can run the same component by creating a symlink called `tedge-agent` which links to the `tedge` binary, and call the symlink instead.
194+
:::
187195

188-
Build artifacts can be found in `./target/armv7-unknown-linux-gnueabihf/debug` and will include executables:
196+
Alternatively, you can use `cargo` to build and run executable in a single command:
189197

190198
```sh
191-
ls -l ./target/armv7-unknown-linux-gnueabihf/debug/tedge*
192-
```
193-
194-
```text title="Output"
195-
-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge
196-
-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge-mapper
199+
cargo run
197200
```
198201

199-
To cross compile release version of the binaries just add `--release` to the above command like so:
202+
If you need to pass arguments to the %%te%% component, then you use the `--` syntax, and everything afterwards will be passed to the binary being run and not to the `cargo run` command.
200203

201204
```sh
202-
cross build --target armv7-unknown-linux-gnueabihf --release
205+
cargo run -- mqtt sub '#'
203206
```
204207

205-
## Running tests
208+
### Running tests
206209

207-
When contributing to %%te%% we ask you to write tests for the code you have written. The tests will be run by build pipeline when you create pull request, but you can easily run all the tests when you are developing with following command:
210+
When contributing to %%te%%, we ask you to write tests for the code you have written. The tests will be run by the build pipeline when you create a pull request, but you can easily run all the tests whilst you are developing with following command:
208211

209212
```sh
210-
cargo test
213+
just test
211214
```
212215

213-
This will run all tests from the repository and sometime may take long time, `cargo` allows you to run specific test or set of tests for binary:
216+
This will run all tests from the repository and may take some time to complete. Alternatively, you can run a specific test or set of tests for a given binary:
214217

215218
```sh
216-
cargo test --bin tedge
219+
just test --bin tedge
217220
```

0 commit comments

Comments
 (0)