diff --git a/.github/workflows/cmake-multi-platform.yml b/.github/workflows/cmake-multi-platform.yml index 287ba34b..80879ec8 100644 --- a/.github/workflows/cmake-multi-platform.yml +++ b/.github/workflows/cmake-multi-platform.yml @@ -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 @@ -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' diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 55c20896..eb33d02e 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -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 diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml index 8d805ec6..1239b095 100644 --- a/.github/workflows/create-release.yml +++ b/.github/workflows/create-release.yml @@ -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 diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml index ee85b6b2..397633f2 100644 --- a/.github/workflows/dependency-review.yml +++ b/.github/workflows/dependency-review.yml @@ -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 diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 8a5fe5c4..4f2a65c6 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -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 @@ -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' }} diff --git a/.github/workflows/docker-scout-scan.yml b/.github/workflows/docker-scout-scan.yml index 7a14d409..ef48f6b7 100644 --- a/.github/workflows/docker-scout-scan.yml +++ b/.github/workflows/docker-scout-scan.yml @@ -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 @@ -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 diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml index 6460a957..9cfba09e 100644 --- a/.github/workflows/jekyll-gh-pages.yml +++ b/.github/workflows/jekyll-gh-pages.yml @@ -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 diff --git a/.github/workflows/sbom-generate-submit.yml b/.github/workflows/sbom-generate-submit.yml index 54d416e0..0a51493d 100644 --- a/.github/workflows/sbom-generate-submit.yml +++ b/.github/workflows/sbom-generate-submit.yml @@ -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 diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index f8d84f31..f6149295 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -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 diff --git a/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md similarity index 100% rename from CODE_OF_CONDUCT.md rename to docs/CODE_OF_CONDUCT.md diff --git a/docs/README.md b/docs/README.md index 8ce944cc..fc305254 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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: + +Or you can start a discussion: + ## Key Features OdbDesign ODB++ parser is differentiated from other offerings by these key features: @@ -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\\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. @@ -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 @@ -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\\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. @@ -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++