Skip to content

Commit

Permalink
merge to main (#284)
Browse files Browse the repository at this point in the history
  • Loading branch information
nam20485 committed Apr 22, 2024
2 parents 80f1db7 + 3e19e37 commit d803c6a
Show file tree
Hide file tree
Showing 11 changed files with 85 additions and 16 deletions.
4 changes: 2 additions & 2 deletions .github/workflows/cmake-multi-platform.yml
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ jobs:
egress-policy: audit

- name: Checkout Repository
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2

# add problem matchers by compiler
- name: Add Problem Matchers
Expand Down Expand Up @@ -148,7 +148,7 @@ jobs:
run: cmake --build --preset ${{matrix.preset}}

- name: Checkout OdbDesign Test Data Repository
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
with:
repository: 'nam20485/OdbDesignTestData'
path: 'OdbDesignTestData'
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ jobs:
egress-policy: audit

- name: Checkout repository
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2

# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/create-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ jobs:
fi
- name: Checkout Repository
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2

- name: Download Artifacts
uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/dependency-review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ jobs:
egress-policy: audit

- name: 'Checkout Repository'
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2

- name: Component detection
uses: advanced-security/component-detection-dependency-submission-action@5a8ce4ad8c6fbb9b88f66f672014e44b427d7d54 # v0.0.2
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/docker-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ jobs:
egress-policy: audit

- name: Checkout repository
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2

# add problem matchers
- name: Add Problem Matchers
Expand Down Expand Up @@ -112,7 +112,7 @@ jobs:
# https://github.com/docker/build-push-action
- name: Build and push Docker image
id: build-and-push
uses: docker/build-push-action@af5a7ed5ba88268d5278f7203fb52cd833f66d6e
uses: docker/build-push-action@2cdde995de11925a030ce8070c3d77a52ffcf1c0
with:
context: .
push: ${{ github.event_name != 'pull_request' }}
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/docker-scout-scan.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ jobs:
egress-policy: audit

- name: Checkout repository
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2

# add problem matchers
- name: Add Problem Matchers
Expand Down Expand Up @@ -89,7 +89,7 @@ jobs:
# https://github.com/docker/build-push-action
- name: Build and push Docker image
id: build-and-push
uses: docker/build-push-action@af5a7ed5ba88268d5278f7203fb52cd833f66d6e
uses: docker/build-push-action@2cdde995de11925a030ce8070c3d77a52ffcf1c0
with:
context: .
push: false
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/jekyll-gh-pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ jobs:
egress-policy: audit

- name: Checkout
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2

- name: Install Doxygen
run: sudo apt install -y doxygen
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/sbom-generate-submit.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ jobs:
egress-policy: audit

- name: Checkout Code
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2

- name: SBOM Generate
uses: advanced-security/sbom-generator-action@375dee8e6144d9fd0ec1f5667b4f6fb4faacefed # v0.0.1
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/scorecard.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ jobs:
egress-policy: audit

- name: "Checkout code"
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
with:
persist-credentials: false

Expand Down
File renamed without changes.
77 changes: 73 additions & 4 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,24 @@

A free open source cross-platform C++ library for parsing ODB++ Design archives, accessing their data, and building net list product models. Exposed via a REST API packaged inside of a Docker image.

## Skip to Build and Running Instructions

Sounds great! Now how do I build and run it?

[Run](#running)

[Build](#building-from-source)

Documentation for the currently-released version of the source code is available [here](https://nam20485.github.io/OdbDesign/api).

## Need Help?

Feel free to message me in the project's Gitter chat room: [odbdesign:gitter.im](https://app.gitter.im/#/room/#odbdesign:gitter.im)

You can also create an issue: <https://github.com/nam20485/OdbDesign/issues>

Or you can start a discussion: <https://github.com/nam20485/OdbDesign/discussions>

## Key Features

OdbDesign ODB++ parser is differentiated from other offerings by these key features:
Expand Down Expand Up @@ -96,14 +114,49 @@ The diagram describes the current state of parser implementation and data availa

The OdbDesign parser is built as a C++ shared library on all three platforms. An executable running the server links to the library and provides the REST API for accessing the data the library parses. The REST API server can be run by invoking the executable directly or by running the Docker image. The server executable and library can be run on Windows, Linux, or MacOS and the Docker image can be run on any platform that supports Docker.

Documentation for the currently-released version of the source code is available [here](https://nam20485.github.io/OdbDesign/api).

[Insert Diagram Image]

#### Library

FileModel vs. ProductModel...

## Running

There are three different ways to use the project. You can:

1. Build the C++ shared library and use it in your own application
1. Build the C++ library and REST API server application and then run the application
1. Run the REST API server (which contains the library inside) from the Docker image.

The instructions for building the C++ shared library and application are below in the [Building from Source](#building-from-source) section. The instructions for running the application or REST API server are here.

### Running the C++ Application

The C++ application REST API server can be run by executing the `OdbDesignServer` or `OdbDesignServer.exe` executable (depending on your platform).

The executable can be found in the following directory:

* `~/src/OdbDesign/out/build/x64-release` *(Linux/MacOS)*
* `C:\Users\<YourName>\Source\OdbDesign\out\build\x64-release` *(Windows)*

See the [Building from Source](#building-from-source) section for more details on building the C++ application and the build output directory.

If successful, the REST API server will be running and listening on port 8888. You can access the REST API at `http://localhost:8888`.

### Running the REST API Server

From the root of the source directory run:

`$ docker compose up`

If successful, the REST API server will be running and listening on port 8888. You can access the REST API at `http://localhost:8888`. The Swagger UI is available at `http://localhost:8080/swagger`.

## Building from Source

Documentation for the currently-released version of the source code is available [here](https://nam20485.github.io/OdbDesign/api).

### Build Dependencies

> If you are building on Windows and have a modern version of Visual Studio installed then all of the dependencies listed below are already installed on your system (except for maybe Docker). You can skip to the next section.
Expand All @@ -123,7 +176,7 @@ FileModel vs. ProductModel...
Get the source code by cloning the GitHub repository:

```Bash
$ git clone git@github.com:nam20485/OdbDesign.git
$ git clone https://github.com/nam20485/OdbDesign.git
```

### Build
Expand Down Expand Up @@ -165,22 +218,37 @@ $ cmake --build --preset linux-release

```

This builds the C++ shared library and the REST API server executable. See the [Running the C++ Application](#running-the-c%2b%2b-application) section for more details.

The build output can be found in the following directory:

* `~/src/OdbDesign/out/build/x64-release` *(Linux/MacOS)*
* `C:\Users\<YourName>\Source\OdbDesign\out\build\x64-release` *(Windows)*

>The `x64-release` directory will be different if you selected a different configuration preset (`x64-release` vs. `x64-debug` or `linux-release` vs. `linux-debug`). The `x64-release` directory will contain the shared library and the server executable. Make sure to copy the dependencies (.dll files on Windows, .so files on Linux, .dylib files on MacOS) to the same directory as the executable if you want to copy it somewhere else.
#### Docker Image for REST API Server

From the root of the source directory...

```Bash
$ docker build . -t odbdesign-server
$ docker compose up
```

## Running the REST API Server
This builds the Docker image and runs it. See the [Running the REST API Server](#running-the-rest-api-server) section for more details.

## Integration into Other Applications

There are three interfaces that allow use of the library in other applications.
There are three separate interfaces that allow use of the library in other applications.

### C++ Shared Library

Build the C++ shared library and link it into your own C++ application. See the [Building from Source](#building-from-source) section for more details on building it.

### REST API

Run the REST API server and access the data via the REST API. See the [Running the REST API Server](#running-the-rest-api-server) section for more details on running it.

### Google Protobuf Protocol Buffers

Data objects returned from the parser library support serialization to and from [Google Protobuf protocol buffers](https://protobuf.dev/). This allows the data to be easily shared with other applications and programming languages that support protocol buffers. Google Protobuf is a highly optimized binary encoding so it is fast and small.
Expand Down Expand Up @@ -224,6 +292,7 @@ If you are interested in using the parser in your application or code, or have a
* [GitHub](https://github.com/nam20485/odbdesign)
* [LinkedIn](https://www.linkedin.com/in/namiller/)
* [OdbDesign Website](https://nam20485.github.io/OdbDesign/)
* Gitter chat room: [odbdesign:gitter.im](https://app.gitter.im/#/room/#odbdesign:gitter.im)

## ODB++

Expand Down

0 comments on commit d803c6a

Please sign in to comment.