Skip to content

Commit

Permalink
Adjusted headers & added table of contents to installation.md
Browse files Browse the repository at this point in the history
  • Loading branch information
dmccoystephenson committed May 8, 2024
1 parent e321d24 commit 401ffe5
Showing 1 changed file with 26 additions and 21 deletions.
47 changes: 26 additions & 21 deletions docs/installation.md
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -13,23 +18,23 @@ 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'.

```bash
$ 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'.

```bash
$ 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'.

Expand All @@ -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:

Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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:
Expand All @@ -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.
Expand All @@ -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<number>`.

Expand Down Expand Up @@ -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)
Expand Down

0 comments on commit 401ffe5

Please sign in to comment.