Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@tsopokis
tsopokis committed Apr 17, 2024
1 parent 8502ed1 commit d73109c
Show file tree
Hide file tree
Showing 5 changed files with 59 additions and 69 deletions.
44 changes: 29 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,39 @@
---
title: Corteca Toolchain v23.12.1
---
# Corteca Toolchain v23.12.1

Part of Corteca Developer Toolkit, Toolchain is a set of compilation tools that help isolate the application within the container, avoiding interaction with the host system's libraries in the creation of applications for [Corteca Marketplace](https://www.nokia.com/networks/fixed-networks/corteca-applications/). This repository is hosted on [https://github.com/nokia/corteca-toolchain](https://github.com/nokia/corteca-toolchain)

## Repo layout

```text
├── context -> Toolchain image context (files to be included in the images)
│ ├── config -> Buildroot configuration files for each toolchain
│ ├── environments -> Environment variables for each toolchain
```shell
├── context # Toolchain image context (files to be included in the images)
│ ├── config # Buildroot configuration files for each toolchain
│ ├── environments # Environment variables for each toolchain
│ └── scripts
│ └── nokia_toolchain.sh -> Script for invoking toolchain actions inside the container
├── images -> Image resources for this file
├── sample-application -> Sample Container Application
├── Dockerfile -> Toolchain image Dockerfile
└── README.md -> this file
└── USAGE.md -> Corteca Development Platform Documentation
│ └── nokia_toolchain.sh # Script for invoking toolchain actions inside the container
├── images # Image resources for this file
├── sample-application # Sample Container Application
├── Dockerfile # Toolchain image Dockerfile
├── README.md # this file
└── USAGE.md # Corteca Development Platform Documentation
```

## Introduction

This repository contains the files needed to build the Corteca Toolchains.
This repository contains the files needed to build the Corteca Toolchains. There are 2 flavors of the toolchain depending on the target CPU architecture:

| Toolchain name | CPU Architecture | Indicative list of Corteca devices |
| ---------- | ----------------------- | ------------ |
| `corteca-toolchain-armv7` | armv7, arm-el, 32-bits | Beacon 6 |
| `corteca-toolchain-armv8` | armv8, aarch64, 64-bits | Beacon 10, Beacon 24, Beacon G6, XS-2426X-A, XS-2426G-B, Beacon3.1 / G-1426G-A |

Both of the images are based on Buildroot v2023.02.1 and are configured for each CPU architecture. The following packages are installed by default in the target filesystem:

- Linux Kernel Headers v4.14.x
- binutils v2.37
- libc: musl v1.2.3
- gcc v10
- ubus
- mbedTLS

## Prerequisites

Expand All @@ -39,4 +51,6 @@ If this fails, please follow the installation procedure for your OS.

### Sample application

In order to be able to build your application you need to create a directory structure to hold the source code and all the other files that are need for the container package creation. For more information on those, you can take a look at the [Sample Container Application Documentation](./sample-application/README.md).
In order to be able to build your application you need to create a specific directory structure to hold the source code and all the other files that are need for the container package creation. For more information on this, you can take a look at the [Sample Container Application Documentation](sample-application/README.md).

For instructions on using the toolchain to build your application, refer to [Corteca Development Platform Documentation](USAGE.md)
17 changes: 2 additions & 15 deletions USAGE.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,8 @@
---
title: Corteca Development Platform Documentation v23.12.1
---
# Corteca Development Platform Documentation v23.12.1

## Introduction

This guide contains step-by-step instructions on how to generate a containerized application package for the Corteca ecosystem.

### Docker

The toolchains for compiling and building the containers require docker or a compatible container engine. This document assumes that you use docker.
Make sure you have docker installed.

```shell
docker --version
```

If this fails, please follow the installation procedure for your OS.
This guide contains step-by-step instructions on how to generate a containerized application package for the Corteca ecosystem. You need to have Docker Desktop or Docker Engine installed.

### Corteca Toolchains

Expand Down
67 changes: 28 additions & 39 deletions sample-application/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
---
title: Sample Container Application v23.12.1
---
# Sample Container Application v23.12.1

This is a sample hello world application used to demonstrate the Corteca tooolchain functionality

Expand All @@ -10,71 +8,62 @@ For your container application, the following structure shows the recommended la

| name | Description |
| ---- | ----------- |
| .devcontainer/ | The directory with the VSCode DevContainer plugin configuration files for the toolchains |
| build/ | Directory for the compiled/generated artifacts. Files that will be create by make will end up in here |
| dist/ | Directory for the generated compressed container application artifacts. |
| src/ | Directory with the source code of the application |
| target/ | Directory for files that we need to copy `as is` to the container (e.g: configuration files, precompiled binaries, etc. reside in here) |
| tests/ | Functional and product testing scripts |
| ADF | Application Description File (json file), used to describe the content in the tarball and the application runtime environment requirements |
| Makefile | The main makefile that is used to invoke the scripts needed to build the app. In gerneral it will invoke the `Makefile` in `src/` directory |
| README.md | Readme of the application (this file) |
| `.devcontainer/` | The directory with the VSCode DevContainer plugin configuration files for the toolchains |
| `build/` | Directory for the compiled/generated artifacts. Files that will be create by make will end up in here |
| `dist/` | Directory for the generated compressed container application artifacts. |
| `src/` | Directory with the source code of the application |
| `target/` | Directory for files that we need to copy `as is` to the container (e.g: configuration files, precompiled binaries, etc. reside in here) |
| `tests/` | Functional and product testing scripts |
| `ADF` | Application Description File (json file), used to describe the content in the tarball and the application runtime environment requirements |
| `Makefile` | The main makefile that is used to invoke the scripts needed to build the app. In gerneral it will invoke the `Makefile` in `src/` directory |
| `README.md` | Readme of the application (this file) |

In your host you must have a directory that includes the ADF file of your application and a directory named `src/` with the source code of your application. Inside `src/` you must have a Makefile that can compile your application.

### build/

Compiled/generated artifacts will be created in here.
Compiled/generated artifacts will be created in here. `<ARCH>` can be one of `armv7` or `armv8`.

| name | Description |
| ---- | ----------- |
| build/`ARCH`/app | For each architecture there is a directory structure with the compiled binaries/libraries. This directory is copied recursively to the target rootfs |
| build/`ARCH`/pkg | Directory with all the files of the application package |
| build/`ARCH`/pkg/ADF | `ADF` file to be included in the application package (automatically copied here)|
| build/`ARCH`/pkg/rootfs.tar.gz | Compressed contents of `build/ARCH/rootfs/` |
| build/`ARCH`/rootfs/ | Extracted rootfs directory. All compiled/generated files and the files from `target/`, are copied here before genertating `build/ARCH/pkg/rootfs.tar.gz` |
| `build/<ARCH>/app` | For each architecture there is a directory structure with the compiled binaries/libraries. This directory is copied recursively to the target rootfs |
| `build/<ARCH>/pkg` | Directory with all the files of the application package |
| `build/<ARCH>/pkg/ADF` | `ADF` file to be included in the application package (automatically copied here)|
| `build/<ARCH>/pkg/rootfs.tar.gz` | Compressed contents of `build/<ARCH>/rootfs/` |
| `build/<ARCH>/rootfs/` | Extracted rootfs directory. All compiled/generated files and the files from `target/`, are copied here before generating `build/<ARCH>/pkg/rootfs.tar.gz` |

### dist/

Compressed package of the containerized application for each architecture will be created in here. These files can be used to install the application in a device.

| name | Description |
| ---- | ----------- |
| dist/`APP`-`VERSION`-`ARCH`-rootfs.tar.gz | The complete container application package file for each architecture|
| `dist/<APP>-<VERSION>-<ARCH>-rootfs.tar.gz` | The complete container application package file for each architecture|

### src/

For a container application you need to have the source code of your application in folder `src/`

| name | Description |
| ---- | ----------- |
| src/helloworld.c | Source code file |
| . | all |
| . | other |
| . | files |
| src/Makefile | The source code makefile, used to compile/build the application |

If you don't use make for your application, then you need to adjust the main `Makefile` and set the `build` target accordingly.
For a container application you need to have the source code of your application under folder `src/`. If you don't use make for your application, then you need to adjust the main `Makefile` and set the `build` target accordingly.

### target/

Directory for files that we need to copy `as is` to the container (e.g: configuration files, precompiled binaries, etc. reside in here).

| name | Description |
| ---- | ----------- |
| target/noarch/ | Directory for architecture agnostic files (e.g.: configuration files, scripts, static files, images/logos, etc). |
| target/`ARCH`/ | Directory with precompiled or other files that are architecture specific. (e.g.: precompiled libraries, binaries, etc ) |
| `target/noarch/` | Directory for architecture agnostic files (e.g.: configuration files, scripts, static files, images/logos, etc). |
| `target/armv7/` | Directory with precompiled or other files that are specific to armv7 architecture. |
| `target/armv8/` | Directory with precompiled or other files that are specific to armv8 architecture. |

### tests/

Functional and product testing scripts

| name | Description |
| ---- | ----------- |
| tests/functional/ | Directory with all the files and scripts needed for functional testing of the application |
| tests/functional/tests.sh | Script that runs all functional tests |
| tests/product/ | Directory with all the files and scripts needed for product testing of the application |
| tests/product/tests.sh | Script that runs all product tests |
| `tests/functional/` | Directory with all the files and scripts needed for functional testing of the application |
| `tests/functional/tests.sh` | Script that runs all functional tests |
| `tests/product/` | Directory with all the files and scripts needed for product testing of the application |
| `tests/product/tests.sh` | Script that runs all product tests |

### Makefile

Expand Down Expand Up @@ -198,14 +187,14 @@ If everything is in place you can use the corteca toolchain images to build your
docker run -u "$(id -u):$(id -g)" -v ./:/app ghcr.io/nokia/corteca-toolchain-armv8:23.12.1
```

Check `/app/build/` directory for all the generated artifacts and `/app/dist/` for the container packages.
Check `build/` directory for all the generated artifacts and `dist/` for the container packages.

### Cleaning up

All artifacts generated under `/app/dist/` and `/app/build/` are ignored by git, but you can always clean them up by running the following command
All artifacts generated under `dist/` and `build/` are ignored by git, but you can always clean them up by running the following command

```shell
docker run -u "$(id -u):$(id -g)" -w /app -v ./:/app ghcr.io/nokia/corteca-toolchain-armv8:23.12.1
docker run -u "$(id -u):$(id -g)" -w /app -v ./:/app corteca-toolchain-armv8:23.12.1 nokia_toolchain distclean"
```
## VSCode DevContainers
Expand Down
Empty file removed sample-application/target/armv7/.gitkeep
View file
Empty file.
Empty file removed sample-application/target/armv8/.gitkeep
View file
Empty file.

0 comments on commit d73109c

Please sign in to comment.