Skip to content

Commit

Permalink
Clean up README (onnx#3961)
Browse files Browse the repository at this point in the history 
* Trim trailing space
* Use relative links. Absolute links were needed because of
  <dhimmel/obonet#12>, which is fixed now.
* Fix typos.
* master -> main.

Signed-off-by: Gary Miguel <[email protected]>
  • Loading branch information
@garymm
garymm authored Jan 22, 2022
1 parent 48d2e7c commit bd5883a
Showing 1 changed file with 31 additions and 52 deletions.
83 changes: 31 additions & 52 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,27 +18,27 @@ ONNX is [widely supported](http://onnx.ai/supported-tools) and can be found in m
* [Pre-trained ONNX models](https://github.com/onnx/models)

# Learn about the ONNX spec
* [Overview][overview]
* [ONNX intermediate representation spec][ir]
* [Versioning principles of the spec][versioning]
* [Operators documentation][operators]
* [Python API Overview][python_api]
* [Overview](docs/Overview.md)
* [ONNX intermediate representation spec](docs/IR.md)
* [Versioning principles of the spec](docs/Versioning.md)
* [Operators documentation](docs/Operators.md)
* [Python API Overview](docs/PythonAPIOverview.md)

# Programming utilities for working with ONNX Graphs
* [Shape and Type Inference][shape_inference]
* [Shape and Type Inference](docs/ShapeInference.md)
* [Graph Optimization](https://github.com/onnx/optimizer)
* [Opset Version Conversion][version_converter]
* [Opset Version Conversion](docs/VersionConverter.md)

# NOTICE: ONNX now uses main branch as default branch
Here are the [steps](https://github.com/onnx/onnx/wiki/How-to-migrate-to-main-branch-in-local-repo) from ONNX wiki for migrating to main branch in local repo.

# Contribute
ONNX is a [community project][community]. We encourage you to join the effort and contribute feedback, ideas, and code. You can participate in the [SIGs][sigs] and [Working Groups][wgs] to shape the future of ONNX.
ONNX is a [community project](community/readme.md). We encourage you to join the effort and contribute feedback, ideas, and code. You can participate in the [Special Interest Groups](community/sigs.md) and [Working Groups](community/working-groups.md) to shape the future of ONNX.

Check out our [contribution guide][contributing] to get started.
Check out our [contribution guide](docs/CONTRIBUTING.md) to get started.

If you think some operator should be added to ONNX specification, please read
[this document][new_op].
[this document](docs/AddNewOp.md).

# Discuss
We encourage you to open [Issues](https://github.com/onnx/onnx/issues), or use [Slack](https://slack.lfai.foundation/) for more real-time discussion
Expand Down Expand Up @@ -82,9 +82,9 @@ You can also use the [onnx-dev docker image](https://hub.docker.com/r/onnx/onnx-


## Build ONNX from Source
Before building from source uninstall any existing versions of onnx `pip uninstall onnx`.
Before building from source uninstall any existing versions of onnx `pip uninstall onnx`.

Generally spreaking, you need to install [protobuf C/C++ libraires and tools](https://github.com/protocolbuffers/protobuf) before proceeding forward. Then depending on how you installed protobuf, you need to set environment variable CMAKE_ARGS to "-DONNX_USE_PROTOBUF_SHARED_LIBS=ON" or "-DONNX_USE_PROTOBUF_SHARED_LIBS=OFF". For example, you may need to run the following command:
Generally speaking, you need to install [protobuf C/C++ libraries and tools](https://github.com/protocolbuffers/protobuf) before proceeding forward. Then depending on how you installed protobuf, you need to set environment variable CMAKE_ARGS to "-DONNX_USE_PROTOBUF_SHARED_LIBS=ON" or "-DONNX_USE_PROTOBUF_SHARED_LIBS=OFF". For example, you may need to run the following command:

Linux:
```bash
Expand All @@ -99,7 +99,7 @@ The ON/OFF depends on what kind of protobuf library you have. Shared libraries a


### Windows
If you are building ONNX from source, it is recommended that you also build Protobuf locally as a static library. The version distributed with conda-forge is a DLL, but ONNX expects it to be a static library. Building protobuf locally also lets you control the verison of protobuf. The tested and recommended version is 3.16.0.
If you are building ONNX from source, it is recommended that you also build Protobuf locally as a static library. The version distributed with conda-forge is a DLL, but ONNX expects it to be a static library. Building protobuf locally also lets you control the version of protobuf. The tested and recommended version is 3.16.0.

The instructions in this README assume you are using Visual Studio. It is recommended that you run all the commands from a shell started from "x64 Native Tools Command Prompt for VS 2019" and keep the build system generator for cmake (e.g., cmake -G "Visual Studio 16 2019") consistent while building protobuf as well as ONNX.

Expand All @@ -109,19 +109,19 @@ git clone https://github.com/protocolbuffers/protobuf.git
cd protobuf
git checkout v3.16.0
cd cmake
cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX=<protobug_install_dir> -Dprotobuf_MSVC_STATIC_RUNTIME=OFF -Dprotobuf_BUILD_SHARED_LIBS=OFF -Dprotobuf_BUILD_TESTS=OFF -Dprotobuf_BUILD_EXAMPLES=OFF .
cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX=<protobuf_install_dir> -Dprotobuf_MSVC_STATIC_RUNTIME=OFF -Dprotobuf_BUILD_SHARED_LIBS=OFF -Dprotobuf_BUILD_TESTS=OFF -Dprotobuf_BUILD_EXAMPLES=OFF .
msbuild protobuf.sln /m /p:Configuration=Release
msbuild INSTALL.vcxproj /p:Configuration=Release
```
Then it will be built as a static library and installed to <protobug_install_dir>. Please add the bin directory(which contains protoc.exe) to your PATH.
Then it will be built as a static library and installed to <protobuf_install_dir>. Please add the bin directory(which contains protoc.exe) to your PATH.

```bat
set PATH=<protobug_install_dir>/bin;%PATH%
set PATH=<protobuf_install_dir>/bin;%PATH%
```

Please note: if your protobug_install_dir contains spaces, **do not** add quotation marks around it.
Please note: if your protobuf_install_dir contains spaces, **do not** add quotation marks around it.

Alternative: if you don't want to change your PATH, you can set ONNX_PROTOC_EXECUTABLE instead.
Alternative: if you don't want to change your PATH, you can set ONNX_PROTOC_EXECUTABLE instead.
```bat
set CMAKE_ARGS=-DONNX_PROTOC_EXECUTABLE=<full_path_to_protoc.exe>
```
Expand All @@ -137,7 +137,7 @@ pip install -e .
```
### Linux

First, you need to install protobuf.
First, you need to install protobuf.

Ubuntu users: the quickest way to install protobuf is to run

Expand Down Expand Up @@ -232,25 +232,25 @@ to verify it works.


## Common Build Options
For full list refer to CMakeLists.txt
**Environment variables**
* `USE_MSVC_STATIC_RUNTIME` should be 1 or 0, not ON or OFF. When set to 1 onnx links statically to runtime library.
For full list refer to CMakeLists.txt
**Environment variables**
* `USE_MSVC_STATIC_RUNTIME` should be 1 or 0, not ON or OFF. When set to 1 onnx links statically to runtime library.
**Default**: USE_MSVC_STATIC_RUNTIME=0

* `DEBUG` should be 0 or 1. When set to 1 onnx is built in debug mode. or debug versions of the dependencies, you need to open the [CMakeLists file][CMakeLists] and append a letter `d` at the end of the package name lines. For example, `NAMES protobuf-lite` would become `NAMES protobuf-lited`.
* `DEBUG` should be 0 or 1. When set to 1 onnx is built in debug mode. or debug versions of the dependencies, you need to open the [CMakeLists file](CMakeLists.txt) and append a letter `d` at the end of the package name lines. For example, `NAMES protobuf-lite` would become `NAMES protobuf-lited`.
**Default**: Debug=0

**CMake variables**
* `ONNX_USE_PROTOBUF_SHARED_LIBS` should be ON or OFF.
* `ONNX_USE_PROTOBUF_SHARED_LIBS` should be ON or OFF.
**Default**: ONNX_USE_PROTOBUF_SHARED_LIBS=OFF USE_MSVC_STATIC_RUNTIME=0
`ONNX_USE_PROTOBUF_SHARED_LIBS` determines how onnx links to protobuf libraries.
- When set to ON - onnx will dynamically link to protobuf shared libs, PROTOBUF_USE_DLLS will be defined as described [here](https://github.com/protocolbuffers/protobuf/blob/master/cmake/README.md#dlls-vs-static-linking), Protobuf_USE_STATIC_LIBS will be set to OFF and `USE_MSVC_STATIC_RUNTIME` must be 0.
- When set to OFF - onnx will link statically to protobuf, and Protobuf_USE_STATIC_LIBS will be set to ON (to force the use of the static libraries) and `USE_MSVC_STATIC_RUNTIME` can be 0 or 1.
`ONNX_USE_PROTOBUF_SHARED_LIBS` determines how onnx links to protobuf libraries.
- When set to ON - onnx will dynamically link to protobuf shared libs, PROTOBUF_USE_DLLS will be defined as described [here](https://github.com/protocolbuffers/protobuf/blob/master/cmake/README.md#dlls-vs-static-linking), Protobuf_USE_STATIC_LIBS will be set to OFF and `USE_MSVC_STATIC_RUNTIME` must be 0.
- When set to OFF - onnx will link statically to protobuf, and Protobuf_USE_STATIC_LIBS will be set to ON (to force the use of the static libraries) and `USE_MSVC_STATIC_RUNTIME` can be 0 or 1.

* `ONNX_USE_LITE_PROTO` should be ON or OFF. When set to ON onnx uses lite protobuf instead of full protobuf.
* `ONNX_USE_LITE_PROTO` should be ON or OFF. When set to ON onnx uses lite protobuf instead of full protobuf.
**Default**: ONNX_USE_LITE_PROTO=OFF

* `ONNX_WERROR` should be ON or OFF. When set to ON warnings are treated as errors.
* `ONNX_WERROR` should be ON or OFF. When set to ON warnings are treated as errors.
**Default**: ONNX_WERROR=OFF in local builds, ON in CI and release pipelines.


Expand All @@ -275,33 +275,12 @@ pytest

# Development

Check out the [contributor guide](https://github.com/onnx/onnx/blob/main/docs/CONTRIBUTING.md) for instructions.
Check out the [contributor guide](docs/CONTRIBUTING.md) for instructions.

# License

[Apache License v2.0][license]
[Apache License v2.0](LICENSE)

# Code of Conduct

[ONNX Open Source Code of Conduct](https://onnx.ai/codeofconduct.html)


<!-- links
NOTE: these are absolute rather than repo-relative because we
this document is rendered by PyPI which doesn't seem to handle
relative links properly. See https://github.com/dhimmel/obonet/issues/12.
-->
[overview]: https://github.com/onnx/onnx/blob/main/docs/Overview.md
[ir]: https://github.com/onnx/onnx/blob/main/docs/IR.md
[versioning]: https://github.com/onnx/onnx/blob/main/docs/Versioning.md
[operators]: https://github.com/onnx/onnx/blob/main/docs/Operators.md
[python_api]: https://github.com/onnx/onnx/blob/main/docs/PythonAPIOverview.md
[shape_inference]: https://github.com/onnx/onnx/blob/main/docs/ShapeInference.md
[version_converter]: https://github.com/onnx/onnx/blob/main/docs/VersionConverter.md
[new_op]: https://github.com/onnx/onnx/blob/main/docs/AddNewOp.md
[community]: https://github.com/onnx/onnx/blob/main/community
[sigs]: https://github.com/onnx/onnx/blob/main/community/sigs.md
[wgs]: https://github.com/onnx/onnx/blob/main/community/working-groups.md
[contributing]: https://github.com/onnx/onnx/blob/main/docs/CONTRIBUTING.md
[CMakeLists]: https://github.com/onnx/onnx/blob/main/CMakeLists.txt
[license]: https://github.com/onnx/onnx/blob/main/LICENSE

0 comments on commit bd5883a

Please sign in to comment.