From eefc3ab6cbb8a5901632f46d99e13c8d90b2415d Mon Sep 17 00:00:00 2001 From: growupboron Date: Fri, 9 Oct 2020 00:19:18 +0530 Subject: rewrote quickstart, build-process Revamped and updated documentation to install and build AGL images. (removed whitespaces, added contribution guide, corrected rcar-gen3 section 7, added aglsetup.h flags to hardware support, some minor changes) Bug-AGL: [SPEC-3633] Signed-off-by: Shankho Boron Ghosh Change-Id: Iedb6c7dc1661f4bc58b5f25ea5d188778c7ff908 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/25407 Reviewed-by: Jan-Simon Moeller Tested-by: Jan-Simon Moeller --- .../0_build-microservice-overview.md | 64 ------ .../1_verify-build-host.md | 33 --- .../2_download-packages.md | 239 --------------------- .../3_installing-binder-daemon.md | 89 -------- .../4_getting-source-files.md | 74 ------- .../5_building-and-running-service-natively.md | 119 ---------- .../pictures/microservice-workflow-native.png | Bin 29857 -> 0 bytes 7 files changed, 618 deletions(-) delete mode 100644 docs/3_Developer_Guides/2_Building_Microservices_Natively/0_build-microservice-overview.md delete mode 100644 docs/3_Developer_Guides/2_Building_Microservices_Natively/1_verify-build-host.md delete mode 100644 docs/3_Developer_Guides/2_Building_Microservices_Natively/2_download-packages.md delete mode 100644 docs/3_Developer_Guides/2_Building_Microservices_Natively/3_installing-binder-daemon.md delete mode 100644 docs/3_Developer_Guides/2_Building_Microservices_Natively/4_getting-source-files.md delete mode 100644 docs/3_Developer_Guides/2_Building_Microservices_Natively/5_building-and-running-service-natively.md delete mode 100644 docs/3_Developer_Guides/2_Building_Microservices_Natively/pictures/microservice-workflow-native.png (limited to 'docs/3_Developer_Guides/2_Building_Microservices_Natively') diff --git a/docs/3_Developer_Guides/2_Building_Microservices_Natively/0_build-microservice-overview.md b/docs/3_Developer_Guides/2_Building_Microservices_Natively/0_build-microservice-overview.md deleted file mode 100644 index a1c6edc..0000000 --- a/docs/3_Developer_Guides/2_Building_Microservices_Natively/0_build-microservice-overview.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -edit_link: '' -title: Overview -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/host-configuration/docs/0-build-microservice-overview.md ---- - - - -# 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/docs/3_Developer_Guides/2_Building_Microservices_Natively/1_verify-build-host.md b/docs/3_Developer_Guides/2_Building_Microservices_Natively/1_verify-build-host.md deleted file mode 100644 index 401a5bc..0000000 --- a/docs/3_Developer_Guides/2_Building_Microservices_Natively/1_verify-build-host.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -edit_link: '' -title: Verify Your Build Host -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/host-configuration/docs/1-verify-build-host.md ---- - - - -# 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/docs/3_Developer_Guides/2_Building_Microservices_Natively/2_download-packages.md b/docs/3_Developer_Guides/2_Building_Microservices_Natively/2_download-packages.md deleted file mode 100644 index c1502d2..0000000 --- a/docs/3_Developer_Guides/2_Building_Microservices_Natively/2_download-packages.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -edit_link: '' -title: Download Packages -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/host-configuration/docs/2-download-packages.md ---- - - - -# Download Packages - -Different repositories exist for different AGL releases.\ -You need to download and install the packages based on your version -of AGL. - -## Set the `REVISION` Environment Variable - -All the packages reside in repositories managed by the -[OpenSUSE Build Service (OBS)](https://build.opensuse.org/).\ -You can see the packages -[here](https://build.opensuse.org/project/subprojects/isv:LinuxAutomotive#). - -Currently, support exists for the following AGL releases: - -* ElectricEel -* FunkyFlounder -* GrumpyGuppy -* HappyHalibut -* Master - -You need to set the `REVISION` environment variable to the AGL release you -are using.\ -For this example, set and export `REVISION` as "Master". - -```bash -export REVISION=Master -``` - -For additional details about OBS, see -[LinuxAutomotive page on OBS](https://build.opensuse.org/project/show/isv:LinuxAutomotive). - -## Make Sure Your `DISTRO` Environment Variable is Set - -The `DISTRO` environment variable needs to be correctly set for your -Linux distribution.\ -See the -"[Verify Your Build Host](./1-verify-build-host.html)" -section for information on how to set this variable. - -## Install the Repository - -```bash -Hit:1 https://deb.nodesource.com/node_10.x xenial InRelease -Hit:2 https://download.docker.com/linux/ubuntu xenial InRelease -Hit:3 http://security.ubuntu.com/ubuntu xenial-security InRelease -Hit:4 http://us.archive.ubuntu.com/ubuntu xenial InRelease -Ign:5 http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/AGL_FunkyFlounder/xUbuntu_16.04 ./ InRelease -Hit:6 http://us.archive.ubuntu.com/ubuntu xenial-updates InRelease -Hit:7 http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/AGL_FunkyFlounder/xUbuntu_16.04 ./ Release -Hit:8 http://us.archive.ubuntu.com/ubuntu xenial-backports InRelease -Reading package lists... Done -``` - -Not sure why you get the `Ign` on line 5.\ -I guess InRelease does not exist. - -If you don't have a `/etc/apt/sources.list.d/AGL.list` file to even start with, -and you run through the whole thing, you get the following output: - -```bash -$ sudo apt-get update -Hit:1 https://deb.nodesource.com/node_10.x xenial InRelease -Hit:2 https://download.docker.com/linux/ubuntu xenial InRelease -Hit:3 http://us.archive.ubuntu.com/ubuntu xenial InRelease -Get:4 http://us.archive.ubuntu.com/ubuntu xenial-updates InRelease [109 kB] -Get:5 http://security.ubuntu.com/ubuntu xenial-security InRelease [107 kB] -Ign:6 http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/AGL_FunkyFlounder/xUbuntu_16.04 ./ InRelease -Hit:7 http://download.opensuse.org/repositories/isv:/LinuxAutomotive:/AGL_FunkyFlounder/xUbuntu_16.04 ./ Release -Get:9 http://us.archive.ubuntu.com/ubuntu xenial-backports InRelease [107 kB] -Get:10 http://us.archive.ubuntu.com/ubuntu xenial-updates/main amd64 Packages [902 kB] -Fetched 1,225 kB in 1s (803 kB/s) -Reading package lists... Done -``` - -Following are example commands that show how to install the package repository -based on various values of `DISTRO` and `REVISION`: - -### Ubuntu and "Master" - -```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 <- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/host-configuration/docs/3-installing-binder-daemon.md ---- - - - -# Installing the Binder Daemon - -The Application Framework Binder Daemon (`afb-daemon`), which is a part of -the AGL Application Framework, provides a way to connect applications to -required services.\ -It provides a fast way to securely offer APIs to applications that are -written in any language and that can run almost anywhere. - -You can learn more about the AGL Application Framework in the -"[AGL Framework Overview](../../apis_services/reference/af-main/0-introduction.html)" -section.\ -You can learn more about the `aft-daemon` in the -"[Binder Overview](../../apis_services/reference/af-binder/afb-overview.html)" -section. - -## Installing on Debian - -Use the following commands if your native Linux machine uses the Debian -distribution: - -```bash -sudo apt-get install agl-app-framework-binder-dev -``` - -## Installing on OpenSUSE - -Use the following commands if your native Linux machine uses the OpenSUSE -distribution: - -```bash -sudo zypper install agl-app-framework-binder-devel -``` - -## Installing on Fedora - -Use the following commands if your native Linux machine uses the Fedora -distribution: - -```bash -sudo dnf install agl-app-framework-binder-devel -``` - -## Setting Your Environment Variables - -Regardless of your system's distribution, you need to set certain environment -variables correctly in order to use the daemon (i.e. `app-framework-binder`). - -Commands that define and export these environment variables exist in the -`agl-app-framework-binder.sh` file, which is created when -you install the daemon: - -```bash -#---------- AGL %{name} options Start ---------" -# Object: AGL cmake option for binder/bindings -export LD_LIBRARY_PATH=/opt/AGL/lib64:${LD_LIBRARY_PATH} -export LIBRARY_PATH=/opt/AGL/lib64:${LIBRARY_PATH} -export PKG_CONFIG_PATH=/opt/AGL/lib64/pkgconfig:${PKG_CONFIG_PATH} -export PATH=/opt/AGL/bin:$PATH -#---------- AGL options End --------- -``` - -You can make sure these environment variables are correctly set by doing -one of the following: - -* **Logout and Log Back In:** - - Logging out and then logging back in correctly sets the environment - variables. - -* **Manually Source the `agl-app-framework-binder.sh` File:** - - Source the following command: - - ```bash - source /etc/profile.d/agl-app-framework-binder.sh - ``` - - **NOTE:** - Creating a new session automatically sources the `agl-app-framework-binder.sh` - file. diff --git a/docs/3_Developer_Guides/2_Building_Microservices_Natively/4_getting-source-files.md b/docs/3_Developer_Guides/2_Building_Microservices_Natively/4_getting-source-files.md deleted file mode 100644 index b59cec0..0000000 --- a/docs/3_Developer_Guides/2_Building_Microservices_Natively/4_getting-source-files.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -edit_link: '' -title: Getting Your Source Files -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/host-configuration/docs/4-getting-source-files.md ---- - - - -# 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/docs/3_Developer_Guides/2_Building_Microservices_Natively/5_building-and-running-service-natively.md b/docs/3_Developer_Guides/2_Building_Microservices_Natively/5_building-and-running-service-natively.md deleted file mode 100644 index 3768037..0000000 --- a/docs/3_Developer_Guides/2_Building_Microservices_Natively/5_building-and-running-service-natively.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -edit_link: '' -title: Building and Running Your Service Natively -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/host-configuration/docs/5-building-and-running-service-natively.md ---- - - - -# 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/docs/3_Developer_Guides/2_Building_Microservices_Natively/pictures/microservice-workflow-native.png b/docs/3_Developer_Guides/2_Building_Microservices_Natively/pictures/microservice-workflow-native.png deleted file mode 100644 index 1c38d2a..0000000 Binary files a/docs/3_Developer_Guides/2_Building_Microservices_Natively/pictures/microservice-workflow-native.png and /dev/null differ -- cgit 1.2.3-korg