diff --git a/docs/installation.md b/docs/installation.md index b8c26ac3..dd83b1fc 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,5 +1,10 @@ # Installation and Setup +## Table of Contents +1. [Manual Installation](#manual-installation) +1. [Docker Installation](#docker-installation) + +## Manual Installation The ACM can be executed after following these high-level steps: 1. Obtain the necessary build tools. @@ -13,7 +18,7 @@ The ACM can be executed after following these high-level steps: Docker may also be used to run the ACM. The [Docker Container](#docker-installation) instructions have more information. -## 1. Install [Git](https://git-scm.com/) +### 1. Install [Git](https://git-scm.com/) When asked if you wish to continue after running the command below, type 'Y'. @@ -21,7 +26,7 @@ When asked if you wish to continue after running the command below, type 'Y'. $ sudo apt install git ``` -## 2. Install [CMake](https://cmake.org) +### 2. Install [CMake](https://cmake.org) The ACM uses CMake to build. When asked if you wish to continue after running the command below, type 'Y'. @@ -29,7 +34,7 @@ The ACM uses CMake to build. When asked if you wish to continue after running t $ sudo apt install cmake ``` -## 3. Install Requirements for Autotools +### 3. Install Requirements for Autotools The ASN.1 Compiler (asn1c) uses autotools to build. When asked if you wish to continue after running the command below, type 'Y'. @@ -38,7 +43,7 @@ $ sudo apt install autoconf $ sudo apt install libtool ``` -## 4. Install librdkafka +### 4. Install librdkafka Talking to a Kafka instance, subscribing and producting to topics requires the use of a third party library. We use the librdkafka library as a c/c++ implementation. This can be imported as a submodule, or installed in your development machine: @@ -49,13 +54,13 @@ $ sudo apt install libssl-dev $ sudo apt install librdkafka-dev ``` -## 5. Create a base directory from which to install all the necessary components to test the ACM. +### 5. Create a base directory from which to install all the necessary components to test the ACM. ```bash $ export GIT_REPOS=~/some/dir/you/want/to/put/this/stuff ``` -## 6. Install the ACM Code, Submodules, and Documentation +### 6. Install the ACM Code, Submodules, and Documentation ```bash $ cd $GIT_REPOS @@ -74,9 +79,9 @@ $ cd $GIT_REPOS/asn1_codec $ git submodule update --init --recursive ``` -## 7. Build the Submodules +### 7. Build the Submodules -### a. Build the ASN.1 Compiler (asn1c). +#### a. Build the ASN.1 Compiler (asn1c). The documentation for building and installing the [ASN.1 Compiler](https://github.com/vlm/asn1c) (asn1c) is on github. The top level documentation is in the `README.md` file in the root directory of the repository you just pulled and @@ -105,7 +110,7 @@ $ sudo make install Note: If you are having additional problems check the [requirements page](https://github.com/vlm/asn1c/blob/master/REQUIREMENTS.md), although I did not need `bison` or `flex` to get asn1c to build. -### b. Build the pugixml library. +#### b. Build the pugixml library. The ACM uses [pugixml](https://pugixml.org) to process XML (ASN.1 XER); XML is the ACM's human-readable format. The pugixml library is built using CMake. Although the [pugixml quickstart](https://pugixml.org/docs/quickstart.html) @@ -125,7 +130,7 @@ Note: an out of source build is also an option and works. This should install these libraries in the usual locations, i.e., `/usr/local/lib` `/usr/local/include` -## 8. Compile the J2735 and IEEE 1609.2 ASN.1 Specification Files and Build the CV ASN.1 Codec Library +### 8. Compile the J2735 and IEEE 1609.2 ASN.1 Specification Files and Build the CV ASN.1 Codec Library The ACM project's `asn1c_combined` subdirectory is where a library that performs connected vehicle specific ASN.1 encoding and decoding will be built. More specifically, this library decodes various ASN.1 binary encodings (e.g., UPER, @@ -134,7 +139,7 @@ back into other encodings (e.g., XER, or XML). This subdirectory must contain th encode and decode connected vehicle communications. It contains a script to compile the specifications and build the library (and a command line tool that can be used independently to encode and decode ASN.1 files). -### a. Obtain the Necessary ASN.1 Specification Files +#### a. Obtain the Necessary ASN.1 Specification Files The above subdirectory must contain the below specification files; all of these are included except the j2735 specification that needs to be [purchased from SAE](https://saemobilus.sae.org/content/j2735_201603). These @@ -148,7 +153,7 @@ specifications are subject to change and should be updated periodically. - SAE J2735 - `J2735_201603DA.ASN` -### b. Compile the Specifications and Build the Library +#### b. Compile the Specifications and Build the Library ```bash $ cd $GIT_REPOS/asn1_codec/asn1c_combined @@ -159,7 +164,7 @@ During compilation numerous source code files will be generated in or moved into static library, `libasncodec.a`, and the command line tool, `converter-example`. The latter is not needed, but useful. Do not remove the header files that are generated in this directory -## 9. Build the ACM +### 9. Build the ACM Finally, build the ACM. The ACM is build using CMake. @@ -171,7 +176,7 @@ $ cmake .. $ make ``` -## Additional information +### Additional information The following projects are used by the ACM; however, they are header-only and those headers are included in the ACM repository. You can pull fresh headers from the following locations: @@ -180,9 +185,9 @@ ACM repository. You can pull fresh headers from the following locations: - The ACM uses [Catch](https://github.com/philsquared/Catch) for unit testing, but it is a header-only library included in the repository. - Currently, the ACM does not use [RapidJSON](https://github.com/miloyip/rapidjson), but this header-only library may be used in the future. -# Docker Installation +## Docker Installation -## 1. Install [Docker](https://www.docker.com) +### 1. Install [Docker](https://www.docker.com) - When following the website instructions, setup the Docker repos and follow the Linux post-install instructions. - The CE version seems to work fine. @@ -207,24 +212,24 @@ ACM repository. You can pull fresh headers from the following locations: ``` - NOTE: The DNS IP addresses are ORNL specific. -## 2. Restart the docker daemon to consume the new configuration file. +### 2. Restart the docker daemon to consume the new configuration file. ```bash $ service docker stop $ service docker start ``` -## 3. Check the configuration using the command below to confirm the updates above are taken if needed: +### 3. Check the configuration using the command below to confirm the updates above are taken if needed: ```bash $ docker info ``` -## 4. Install Docker Compose +### 4. Install Docker Compose - Comprehensive instructions can be found on this [website](https://www.digitalocean.com/community/tutorials/how-to-install-docker-compose-on-ubuntu-16-04) - Follow steps 1 and 2. -## 5. Install [`kafka-docker`](https://github.com/wurstmeister/kafka-docker) so kafka and zookeeper can run in a separate container. +### 5. Install [`kafka-docker`](https://github.com/wurstmeister/kafka-docker) so kafka and zookeeper can run in a separate container. - Get your host IP address. The address is usually listed under an ethernet adapter, e.g., `en`. @@ -255,7 +260,7 @@ $ cd $GIT_REPOS/kafka-docker $ docker-compose down ``` -## 6. Download and install the Kafka **binary**. +### 6. Download and install the Kafka **binary**. - The Kafka binary provides a producer and consumer tool that can act as surrogates for the ODE (among other items). - [Kafka Binary](https://kafka.apache.org/downloads)