From aa9912660e08f8d406e74807bab476cc60dd9581 Mon Sep 17 00:00:00 2001 From: Jan-Simon Moeller Date: Mon, 2 Mar 2020 23:02:15 +0100 Subject: Add agl-documentation subfolder into agl repo Signed-off-by: Jan-Simon Moeller --- .../host-configuration/docs/0-Doc-Revisions.md | 6 + .../docs/0-build-microservice-overview.md | 55 +++++ .../host-configuration/docs/0_Abstract.md | 11 + .../host-configuration/docs/1-verify-build-host.md | 24 +++ .../host-configuration/docs/1_Prerequisites.md | 175 ++++++++++++++++ .../host-configuration/docs/2-download-packages.md | 230 +++++++++++++++++++++ .../docs/2_AGL_Application_Framework.md | 43 ++++ .../docs/3-installing-binder-daemon.md | 80 +++++++ .../docs/3_Binding_Build_Example.md | 85 ++++++++ .../docs/4-getting-source-files.md | 65 ++++++ .../host-configuration/docs/4_AGL_XDS.md | 31 +++ .../5-building-and-running-service-natively.md | 110 ++++++++++ .../host-configuration/docs/5_Candevstudio.md | 35 ++++ .../host-configuration/docs/README.md | 20 ++ .../host-configuration/docs/SUMMARY.md | 10 + .../host-configuration/docs/devguides-book.yml | 22 ++ .../docs/pictures/Automotive_grade_linux.png | Bin 0 -> 300093 bytes .../docs/pictures/CANdevStudio.png | Bin 0 -> 52285 bytes .../host-configuration/docs/pictures/HVAC.jpg | Bin 0 -> 54861 bytes .../docs/pictures/Xds-screenshots.jpg | Bin 0 -> 697391 bytes .../docs/pictures/microservice-workflow-native.png | Bin 0 -> 29857 bytes .../docs/resources/iotbzh_logo.png | Bin 0 -> 129625 bytes .../docs/resources/iotbzh_logo_small.png | Bin 0 -> 6989 bytes 23 files changed, 1002 insertions(+) create mode 100644 agl-documentation/host-configuration/docs/0-Doc-Revisions.md create mode 100755 agl-documentation/host-configuration/docs/0-build-microservice-overview.md create mode 100644 agl-documentation/host-configuration/docs/0_Abstract.md create mode 100755 agl-documentation/host-configuration/docs/1-verify-build-host.md create mode 100644 agl-documentation/host-configuration/docs/1_Prerequisites.md create mode 100755 agl-documentation/host-configuration/docs/2-download-packages.md create mode 100644 agl-documentation/host-configuration/docs/2_AGL_Application_Framework.md create mode 100755 agl-documentation/host-configuration/docs/3-installing-binder-daemon.md create mode 100644 agl-documentation/host-configuration/docs/3_Binding_Build_Example.md create mode 100755 agl-documentation/host-configuration/docs/4-getting-source-files.md create mode 100644 agl-documentation/host-configuration/docs/4_AGL_XDS.md create mode 100755 agl-documentation/host-configuration/docs/5-building-and-running-service-natively.md create mode 100644 agl-documentation/host-configuration/docs/5_Candevstudio.md create mode 100644 agl-documentation/host-configuration/docs/README.md create mode 100644 agl-documentation/host-configuration/docs/SUMMARY.md create mode 100644 agl-documentation/host-configuration/docs/devguides-book.yml create mode 100644 agl-documentation/host-configuration/docs/pictures/Automotive_grade_linux.png create mode 100644 agl-documentation/host-configuration/docs/pictures/CANdevStudio.png create mode 100644 agl-documentation/host-configuration/docs/pictures/HVAC.jpg create mode 100644 agl-documentation/host-configuration/docs/pictures/Xds-screenshots.jpg create mode 100755 agl-documentation/host-configuration/docs/pictures/microservice-workflow-native.png create mode 100644 agl-documentation/host-configuration/docs/resources/iotbzh_logo.png create mode 100644 agl-documentation/host-configuration/docs/resources/iotbzh_logo_small.png (limited to 'agl-documentation/host-configuration/docs') diff --git a/agl-documentation/host-configuration/docs/0-Doc-Revisions.md b/agl-documentation/host-configuration/docs/0-Doc-Revisions.md new file mode 100644 index 0000000..3485a4e --- /dev/null +++ b/agl-documentation/host-configuration/docs/0-Doc-Revisions.md @@ -0,0 +1,6 @@ +Document revisions +================== + +| Date | Version | Designation  | Author | +|-------------|---------|--------------------------------------|-------------------------| +| 17 May 1018 | 0.1 | Initial release | C.Benier [ Iot.bzh ] | diff --git a/agl-documentation/host-configuration/docs/0-build-microservice-overview.md b/agl-documentation/host-configuration/docs/0-build-microservice-overview.md new file mode 100755 index 0000000..57d7981 --- /dev/null +++ b/agl-documentation/host-configuration/docs/0-build-microservice-overview.md @@ -0,0 +1,55 @@ +# Overview + +You can develop Microservices on your native Linux machine quickly +by following the workflow in this section. +This workflow takes advantage of RPM or Debian packages,which are available +through the +[OpenSUSE Build Service (OBS)](https://build.opensuse.org/). +You can install these +[packages](https://build.opensuse.org/project/subprojects/isv:LinuxAutomotive) +and bypass the +[Yocto Project](https://yoctoproject.org) build cycles described in the +"[Developing an AGL Image](../../getting_started/reference/getting-started/image-workflow-intro.html)" section. + +Using this workflow, you can start to code, execute, and debug Microservice +bindings directly on your host. This flow works for many cases for which +no specific hardware is required, or when you can plug hardware directly +into your native Linux host's USB port such as a Controller Area Network +([CAN](https://en.wikipedia.org/wiki/CAN_bus)) bus Adapter or a Media +Oriented Systems Transport +([MOST](https://en.wikipedia.org/wiki/MOST_Bus)) Controller. + +The following figure and list overview the Microservice Native Development +process. +You can learn about the steps in the process by reading through the +remaining sections. + +
+ +1. **Verify Your Build Host:** + Make sure you have a native Linux host. + For the example used in this section (i.e. `helloworld-service`), be sure your + Linux distribution is a recent version of Debian, Ubuntu, OpenSUSE, or Fedora. + +2. **Download and Install AGL Packages:** + Download and install the + [near-zero](https://en.wikipedia.org/wiki/Zero_Install) packages + from the OBS. + +3. **Install the Binder Daemon:** + Install the Binder Daemon, which is a part of the + [AGL Application Framework (AFM)](../../apis_services/reference/af-main/0-introduction.html). + The daemon allows you to connect applications to required services. + +4. **Get Your Source Files:** + For this section, you clone the `helloworld-service` binding repository. + You also need to make sure you have some other required packages to build + that specific binding. + +5. **Build and Run Your Service Natively (Optional Tool Use):** + Build your binding on your Linux host using native tools. + Once the binding is built, you can run it to make sure it functions + as expected. + + Optionally use extra tools once your binding is building and running + smoothly in the native environment. diff --git a/agl-documentation/host-configuration/docs/0_Abstract.md b/agl-documentation/host-configuration/docs/0_Abstract.md new file mode 100644 index 0000000..0bb7aca --- /dev/null +++ b/agl-documentation/host-configuration/docs/0_Abstract.md @@ -0,0 +1,11 @@ +# Host Configuration + +## Abstract + +The purpose of this section is to help developers to natively develop and debug +AGL microservices.\ +Thanks to OBS, packages for debian/ubuntu, openSUSE and +fedora distributions are available and can be installed on developer host. + +At first hand, the idea is to easily handle native development of AGL services +and at second hand to run the same services on targets/boards. diff --git a/agl-documentation/host-configuration/docs/1-verify-build-host.md b/agl-documentation/host-configuration/docs/1-verify-build-host.md new file mode 100755 index 0000000..bc7b158 --- /dev/null +++ b/agl-documentation/host-configuration/docs/1-verify-build-host.md @@ -0,0 +1,24 @@ +# Verify Your Build Host + +In order to build a Microservice binding natively, you need to be using a +supported Linux distribution. +In general, a recent version of Debian, Ubuntu, OpenSUSE, and Fedora works. +Following is a specific list of supported distributions: + +* [Debian](https://www.debian.org/releases/) 9.0 +* [Ubuntu](https://wiki.ubuntu.com/Releases) 16.04, 16.10, 17.10, and 18.04 +* [OpenSUSE](https://en.opensuse.org/openSUSE:Roadmap) Leap 15.0 and Tumbleweed +* [Fedora](https://fedoraproject.org/wiki/Releases) 27, 28, 29, and Rawhide. + +Exporting the `DISTRO` environment variable defines the distribution. +Following are examples: + +```bash +export DISTRO="Debian_9.0" +export DISTRO="xUbuntu_16.04" +export DISTRO="xUbuntu_16.10" +export DISTRO="xUbuntu_17.10" +export DISTRO="xUbuntu_18.04" +``` + +Set the `DISTRO` environment appropriately. diff --git a/agl-documentation/host-configuration/docs/1_Prerequisites.md b/agl-documentation/host-configuration/docs/1_Prerequisites.md new file mode 100644 index 0000000..14eacec --- /dev/null +++ b/agl-documentation/host-configuration/docs/1_Prerequisites.md @@ -0,0 +1,175 @@ +# Prerequisites for package installation + +There are different repos for AGL packages depending on the version, it is +possible to install all of them and switching between them. + +To install latest (master) version you must set REVISION variable as follow : + +```bash +export REVISION=Master +``` + +You can find all available repos [here](https://build.opensuse.org/project/subprojects/isv:LinuxAutomotive#). + +For more details about OBS, please visit [LinuxAutomotive page on OBS](https://build.opensuse.org/project/show/isv:LinuxAutomotive). + +## Add repo for debian distro + +Avalable distro values are + +```bash +export DISTRO="Debian_9.0" +export DISTRO="xUbuntu_16.04" +export DISTRO="xUbuntu_16.10" +export DISTRO="xUbuntu_17.10" +export DISTRO="xUbuntu_18.04" +``` + +Install the repository: + +```bash +export REVISION=Master +export DISTRO="xUbuntu_18.04" +wget -O - http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/AGL_${REVISION}/${DISTRO}/Release.key | sudo apt-key add - +sudo bash -c "cat >> /etc/apt/sources.list.d/AGL.list <> /etc/apt/sources.list.d/AGL.list <=0.9.55' +-- No package 'libmicrohttpd' found +CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:415 (message): + A required package was not found +Call Stack (most recent call first): + /usr/share/cmake/Modules/FindPkgConfig.cmake:593 (_pkg_check_modules_internal) + conf.d/app-templates/cmake/cmake.d/01-build_options.cmake:92 (PKG_CHECK_MODULES) + conf.d/app-templates/cmake/common.cmake:77 (include) + conf.d/cmake/config.cmake:184 (include) + CMakeLists.txt:3 (include) +``` + +Open the config.cmake file located in helloworld-service/conf.d/cmake/ +and add a # to the beginning of the "libsystemd>=222" and "libmicrohttpd>=0.9.55". +The end result should look something like this + +```CMake + set (PKG_REQUIRED_LIST + json-c + #libsystemd>=222 + afb-daemon + #libmicrohttpd>=0.9.55 + ) +``` + +Once this is done return to the "Build it!" section of this page. diff --git a/agl-documentation/host-configuration/docs/4-getting-source-files.md b/agl-documentation/host-configuration/docs/4-getting-source-files.md new file mode 100755 index 0000000..5a7563c --- /dev/null +++ b/agl-documentation/host-configuration/docs/4-getting-source-files.md @@ -0,0 +1,65 @@ +# Getting Your Source Files + +Now that you have your host ready, packages installed, and the binder +daemon ready, you can get your source files together. +This example uses the `helloworld-service` binding, which is +a project hosted on GitHub, is written in the C programming language, +depends on the `libjson-c` library, and uses `cmake` for building. + +## Install Programs and Libraries You Need for this Example + +For this example, you need to have the following installed on your host: + +```bash +git +cmake +pkg-config +gcc +g++ +json-c +``` + +**NOTE:** If you are building a different binding, you need to make sure +you have all the programs and libraries needed to build that particular +binding. + +### Installing on Debian + +Use the following commands if your native Linux machine uses the Debian +distribution: + +```bash +sudo apt-get install git cmake pkg-config gcc g++ libjson-c-dev +``` + +### Installing on OpenSUSE + +Use the following commands if your native Linux machine uses the OpenSUSE +distribution: + +```bash +sudo zypper install git cmake pkg-config gcc gcc-c++ libjson-c-devel +``` + +### Installing on Fedora + +Use the following commands if your native Linux machine uses the Fedora +distribution: + +```bash +sudo dnf install git cmake pkg-config gcc gcc-c++ json-c-devel.x86_64 +``` + +## Cloning the helloworld-service repository + +Use Git to create a local repository of the +[helloworld-service](https://github.com/iotbzh/helloworld-service) binding from +[IoT.BZH](https://iot.bzh/en/). +The following command creates a repository named `helloworld-service` in the +current directory. +The "--recurse-submodules" option ensures that all submodules (i.e. repositories +within `helloworld-service`) are initialized and cloned as well. + +```bash +git clone https://github.com/iotbzh/helloworld-service.git --recurse-submodules +``` diff --git a/agl-documentation/host-configuration/docs/4_AGL_XDS.md b/agl-documentation/host-configuration/docs/4_AGL_XDS.md new file mode 100644 index 0000000..5f06c19 --- /dev/null +++ b/agl-documentation/host-configuration/docs/4_AGL_XDS.md @@ -0,0 +1,31 @@ +# AGL XDS + +AGL X(cross) Development System (XDS) provides a multi-platform cross +development tool with near-zero installation. + +* xds-agent: a client/agent that should run on your local / user development machine when you use XDS. +* xds-cli: a command line tool used to control / interface X(cross) Development System, it can be used in addition to XDS DASHBOARD. +* xds-gdb: a wrapper on gdb debugger for X(cross) Development System. + +## AGL XDS for debian + +```bash +sudo apt-get install agl-xds-agent agl-xds-cli agl-xds-gdb +``` + +## AGL XDS for openSUSE + +```bash +sudo zypper install agl-xds-agent agl-xds-cli agl-xds-gdb +``` + +## AGL XDS for fedora + +```bash +sudo dnf install agl-xds-agent agl-xds-cli agl-xds-gdb +``` + +## AGL XDS Documentation + +You can find the XDS documentation + [here](http://docs.automotivelinux.org/master/docs/devguides/en/dev/reference/xds/part-1/0_Abstract.html). diff --git a/agl-documentation/host-configuration/docs/5-building-and-running-service-natively.md b/agl-documentation/host-configuration/docs/5-building-and-running-service-natively.md new file mode 100755 index 0000000..3bde906 --- /dev/null +++ b/agl-documentation/host-configuration/docs/5-building-and-running-service-natively.md @@ -0,0 +1,110 @@ +# Building and Running Your Service Natively + +The next step in the binder development process is to build your +binder and run it using your native Linux system. + +**NOTE:** This section assumes using the `helloworld-service` example +and completion of the previous steps in this +"[Building Microservices Natively](./0-build-microservice-overview.html)" +section. + +## Building the Service + +Move to the cloned `helloworld-service` repository and build the service +using either of the following methods: + +* ```bash + cd helloworld-service + ./conf.d/autobuild/linux/autobuild package + ``` + +* ```bash + cd helloworld-service + mkdir build + cd build + cmake .. + make + ``` + +## Running the Service + +You use the Application Framework Binder Daemon (`afb-daemon`) to +bind one instance of an application or service to the rest of the system. +In this example, you are binding an instance of `helloworld-service` +to the rest of the system: + +```bash +afb-daemon --binding helloworld.so --port 3333 --token '' +``` + +The previous command starts `afb-daemon` and loads the `helloworld.so` +binding. +The daemon is now listening on port 3333 of the `localhost`. + +## Testing the Service + +Refer to the +[AGL Test Framework](../../apis_services/#agl-test-framework) topic in the +"APIs & Services" topic. +You can test your `helloworld-service` binding using the `afm-test` tool. + +Examine the generic example describing how to launch the tests suite +[here](../../apis_services/reference/afb-test/3_Launch_the_tests.html). +This example can help you understand how to test your helloworld binding +instance. + +## Using Optional Tools + +Once you have built and run your micro-service successfully using your +native Linux system, you should consider using some additional +development tools: X(Cross) Development System (XDS) and +the Controller Area Network (CAN) Development Studio (CANdevStudio). + +* **XDS:** Cross-compiles and ports your AGL image to your target hardware. +For information on XDS, see the +"[X(cross) Development System: User's Guide](../reference/xds/part-1/xds-overview.html)" +section. + +* **CANdevStudio:** Simulates CAN signals such as ignition status, +doors status, or reverse gear by every automotive developer. +For information on CANdevStudio, see the +"[CANdevStudio Quickstart](../../apis_services/reference/candevstudio/1_Usage.html)" +section. + +## Troubleshooting + +### systemd and/or libmicrohttpd + +If you encounter an error message similar to the following, +you need to make some changes to your `cmake` file: + +```shell +-- Checking for module 'libmicrohttpd>=0.9.60' +-- No package 'libmicrohttpd' found +CMake Error at /usr/share/cmake/Modules/FindPkgConfig.cmake:415 (message): + A required package was not found +Call Stack (most recent call first): + /usr/share/cmake/Modules/FindPkgConfig.cmake:593 (_pkg_check_modules_internal) + conf.d/app-templates/cmake/cmake.d/01-build_options.cmake:92 (PKG_CHECK_MODULES) + conf.d/app-templates/cmake/common.cmake:77 (include) + conf.d/cmake/config.cmake:184 (include) + CMakeLists.txt:3 (include) +``` + +Open the `config.cmake` file located in `helloworld-service/conf.d/cmake/` directory +and add a hash character (i.e. #) to the beginning of the "libsystemd>=222" +and "libmicrohttpd>=0.9.60" strings. +Following is an example of the edits: + +```CMake + set (PKG_REQUIRED_LIST + json-c + #libsystemd>=222 + afb-daemon + #libmicrohttpd>=0.9.60 + ) +``` + +After making these changes, rebuild the service again as described in the +"[Building the Service](./4-getting-source-files.html#building-the-service)" +section previously on this page. diff --git a/agl-documentation/host-configuration/docs/5_Candevstudio.md b/agl-documentation/host-configuration/docs/5_Candevstudio.md new file mode 100644 index 0000000..6118315 --- /dev/null +++ b/agl-documentation/host-configuration/docs/5_Candevstudio.md @@ -0,0 +1,35 @@ +# CANdevStudio + +CANdevStudio is a CAN bus simulation software.\ +It can work with variety of CAN hardware interfaces (e.g.): + +* Microchip +* Vector +* PEAK-Systems +* even without it (vcan and cannelloni) + +CANdevStudio enables to simulate CAN signals such as +ignition status, doors status or reverse gear by every automotive developer. + +## CANdevStudio for debian + +```bash +sudo apt-get install CANdevStudio +``` + +## CANdevStudio for openSUSE + +```bash +sudo zypper install CANdevStudio +``` + +## CANdevStudio for fedora + +```bash +sudo dnf install CANdevStudio +``` + +## CANdevStudio Quickstart + +The CANdevStudio Quickstart can be found +[here](http://docs.automotivelinux.org/master/docs/apis_services/en/dev/reference/candevstudio/docs/1_Usage.html). diff --git a/agl-documentation/host-configuration/docs/README.md b/agl-documentation/host-configuration/docs/README.md new file mode 100644 index 0000000..b1c50df --- /dev/null +++ b/agl-documentation/host-configuration/docs/README.md @@ -0,0 +1,20 @@ +# Introduction + +AGL Automotive Grade Linux Automotive Grade Linux is a collaborative open +source project that is bringing together automakers, suppliers and technology +companies to accelerate the development and adoption of a fully open software +stack for the connected car. + +![Automotive grade linux screenshot](pictures/Automotive_grade_linux.png) + +| *Meta* | *Data* | +| -- | -- | +| **Title** | {{ config.title }} | +| **Author** | {{ config.author }} | +| **Description** | {{ config.description }} | +| **Keywords** | {{ config.keywords }} | +| **Language** | English | +| **Published** | Published {{ config.published }} as an electronic book | +| **Updated** | {{ gitbook.time }} | +| **Collection** | Open-source | +| **Website** | [{{ config.website }}]({{ config.website }}) | diff --git a/agl-documentation/host-configuration/docs/SUMMARY.md b/agl-documentation/host-configuration/docs/SUMMARY.md new file mode 100644 index 0000000..1d164c0 --- /dev/null +++ b/agl-documentation/host-configuration/docs/SUMMARY.md @@ -0,0 +1,10 @@ +# Summary + +* [Document revisions](0-Doc-Revisions.md) + +* [Abstract](0_Abstract.md) +* [Prerequisites](1_Prerequisites.md) +* [AGL Application Framework Installation](2_AGL_Application_Framework.md) +* [Binding Build Example](3_Binding_Build_Example.md) +* [AGL XDS Installation.md](4_AGL_XDS.md) +* [CanDevStudio Installation](5_Candevstudio.md) diff --git a/agl-documentation/host-configuration/docs/devguides-book.yml b/agl-documentation/host-configuration/docs/devguides-book.yml new file mode 100644 index 0000000..3eacca6 --- /dev/null +++ b/agl-documentation/host-configuration/docs/devguides-book.yml @@ -0,0 +1,22 @@ +type: books +books: +- + id: host-configuration + title: Building Microservices Natively + description: Host Configuration documentation + keywords: + author: "IotBzh" + version: master + chapters: + - url: 0-build-microservice-overview.md + name: Overview + - url: 1-verify-build-host.md + name: Verify Your Build Host + - url: 2-download-packages.md + name: Download Packages + - url: 3-installing-binder-daemon.md + name: Installing the Binder Daemon + - url: 4-getting-source-files.md + name: Getting Your Source Files + - url: 5-building-and-running-service-natively.md + name: Building and Running Your Service Natively diff --git a/agl-documentation/host-configuration/docs/pictures/Automotive_grade_linux.png b/agl-documentation/host-configuration/docs/pictures/Automotive_grade_linux.png new file mode 100644 index 0000000..46291dd Binary files /dev/null and b/agl-documentation/host-configuration/docs/pictures/Automotive_grade_linux.png differ diff --git a/agl-documentation/host-configuration/docs/pictures/CANdevStudio.png b/agl-documentation/host-configuration/docs/pictures/CANdevStudio.png new file mode 100644 index 0000000..c944e02 Binary files /dev/null and b/agl-documentation/host-configuration/docs/pictures/CANdevStudio.png differ diff --git a/agl-documentation/host-configuration/docs/pictures/HVAC.jpg b/agl-documentation/host-configuration/docs/pictures/HVAC.jpg new file mode 100644 index 0000000..79175fb Binary files /dev/null and b/agl-documentation/host-configuration/docs/pictures/HVAC.jpg differ diff --git a/agl-documentation/host-configuration/docs/pictures/Xds-screenshots.jpg b/agl-documentation/host-configuration/docs/pictures/Xds-screenshots.jpg new file mode 100644 index 0000000..1901f4c Binary files /dev/null and b/agl-documentation/host-configuration/docs/pictures/Xds-screenshots.jpg differ diff --git a/agl-documentation/host-configuration/docs/pictures/microservice-workflow-native.png b/agl-documentation/host-configuration/docs/pictures/microservice-workflow-native.png new file mode 100755 index 0000000..1c38d2a Binary files /dev/null and b/agl-documentation/host-configuration/docs/pictures/microservice-workflow-native.png differ diff --git a/agl-documentation/host-configuration/docs/resources/iotbzh_logo.png b/agl-documentation/host-configuration/docs/resources/iotbzh_logo.png new file mode 100644 index 0000000..ae6bc48 Binary files /dev/null and b/agl-documentation/host-configuration/docs/resources/iotbzh_logo.png differ diff --git a/agl-documentation/host-configuration/docs/resources/iotbzh_logo_small.png b/agl-documentation/host-configuration/docs/resources/iotbzh_logo_small.png new file mode 100644 index 0000000..6a98c60 Binary files /dev/null and b/agl-documentation/host-configuration/docs/resources/iotbzh_logo_small.png differ -- cgit