You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -8,210 +8,213 @@ This page details how to build %%te%% from the source code.
8
8
9
9
## Requirements
10
10
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.
12
12
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
16
17
* git
17
-
* Rust toolchain
18
+
* Rust toolchain, the Minimum Supported Rust Version (MSRV) is 1.78
19
+
*[just](https://github.com/casey/just)
18
20
19
-
Following packages are required:
21
+
A list of our test platforms can be found [here](../references/supported-platforms.md).
20
22
21
-
* build-essentials
22
-
* curl
23
-
* gcc
23
+
### Initial setup
24
24
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.
26
26
27
-
## Get the code
27
+
1. Install the dependencies
28
28
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
+
```
30
33
31
-
* via SSH:
34
+
```sh tab={"label":"Linux"}
35
+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
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
+
:::
46
56
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:
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.
55
81
56
82
```sh
57
-
rustc --version
83
+
just release
58
84
```
59
85
60
86
```text title="Output"
61
-
rustc 1.65.0 (897e37553 2022-11-02)
87
+
target/aarch64-unknown-linux-gnu/packages
62
88
```
63
89
64
90
:::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.
69
92
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.
%%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:
75
100
76
-
Current MSRV is `1.65`.
101
+
```sh
102
+
# Intel/AMD (64 bit)
103
+
just release x86_64-unknown-linux-musl
77
104
78
-
### Cross compilation toolchain (optional)
105
+
# Intel/AMD (32 bit)
106
+
just release i686-unknown-linux-musl
79
107
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
82
110
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
84
113
85
-
```sh
86
-
cargo install cross
114
+
# armv6 (32 bit, hard-float), e.g. Raspberry Pi 1
115
+
just release arm-unknown-linux-musleabihf
87
116
```
88
117
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.
90
120
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
+
:::
92
123
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/).
94
125
126
+
### Build Linux virtual packages
95
127
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.
99
129
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:
101
131
102
132
```sh
103
133
just release-linux-virtual
104
134
```
105
135
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:
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
125
160
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
129
162
```
130
163
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
133
165
134
-
```sh
135
-
cargo run --bin tedge
136
-
```
166
+
### Build (debug)
137
167
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:
141
169
142
170
```sh
143
-
cargo build --release
171
+
cargo build
144
172
```
145
173
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:
147
175
148
176
```sh
149
-
ls -l ./target/release/tedge*
177
+
ls -l ./target/debug/tedge
150
178
```
151
179
152
180
```text title="Output"
153
181
-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge
154
-
-rwxrwxr-x 2 user user 11111 Jan 1 00:00 tedge-mapper
155
182
```
156
183
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.
167
186
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:
169
188
170
189
```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
178
191
```
179
192
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):
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
+
:::
187
195
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:
189
197
190
198
```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
197
200
```
198
201
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.
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:
208
211
209
212
```sh
210
-
cargotest
213
+
justtest
211
214
```
212
215
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 sometime to complete. Alternatively, you can run a specific test or set of tests for a given binary:
0 commit comments