diff options
| author | Garrett D'Amore <garrett@damore.org> | 2024-10-06 12:11:19 -0700 |
|---|---|---|
| committer | Garrett D'Amore <garrett@damore.org> | 2024-10-06 12:11:19 -0700 |
| commit | 9edafa33769c5f44a14d2c59d93a6db146ce9b2d (patch) | |
| tree | 4e10a2b6ce5a70f09bebda838efbef2ab8e11af6 | |
| parent | ec33e4259afb8db02cba9a7f6dd08bc6129cfef3 (diff) | |
| download | nng-9edafa33769c5f44a14d2c59d93a6db146ce9b2d.tar.gz nng-9edafa33769c5f44a14d2c59d93a6db146ce9b2d.tar.bz2 nng-9edafa33769c5f44a14d2c59d93a6db146ce9b2d.zip | |
Convert README to markdown
| -rw-r--r-- | README.adoc | 184 | ||||
| -rw-r--r-- | README.md | 200 |
2 files changed, 200 insertions, 184 deletions
diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 6780c780..00000000 --- a/README.adoc +++ /dev/null @@ -1,184 +0,0 @@ -ifdef::env-github[] -:note-caption: :information_source: -:important-caption: :heavy_exclamation_mark: -endif::[] -= nng - nanomsg-next-gen - -// Note: This README is optimized for display with Asciidoctor, or -// on the GitHub project page at https://github.com/nanomsg/nng. - -image:https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg[Stand With Ukraine,link="https://stand-with-ukraine.pp.ua"] -image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/linux.yml?branch=master&logoColor=grey&logo=ubuntu&label=[Linux Status,link="https://github.com/nanomsg/nng/actions"] -image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/windows.yml?branch=master&logoColor=grey&logo=windows&label=[Windows Status,link="https://github.com/nanomsg/nng/actions"] -image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/darwin.yml?branch=master&logoColor=grey&logo=apple&label=[macOS Status,link="https://github.com/nanomsg/nng/actions"] -image:https://img.shields.io/codecov/c/github/nanomsg/nng?logo=codecov&logoColor=grey&label=[Coverage,link="https://codecov.io/gh/nanomsg/nng"] -image:https://img.shields.io/discord/639573728212156478?label=&logo=discord[Discord,link="https://discord.gg/Xnac6b9"] -image:https://img.shields.io/static/v1?label=&message=docs&logo=asciidoctor&logoColor=silver&color=blue[Manual,link="https://nng.nanomsg.org/man"] -image:https://img.shields.io/github/license/nanomsg/nng.svg?logoColor=silver&logo=open-source-initiative&label=&color=blue[MIT License,link="https://github.com/nanomsg/nng/blob/master/LICENSE.txt"] -image:https://img.shields.io/github/v/tag/nanomsg/nng.svg?logo=github&label=[Latest version,link="https://github.com/nanomsg/nng/releases"] - -Please see <<UKRAINE#,here>> for an important message for the people of Russia. - -NOTE: THIS IS THE DEVELOPMENT BRANCH FOR NNG. The content here is -under development and may not be stable. Please use the `stable` branch -for the latest stable release. - -NOTE: If you are looking for the legacy version of nanomsg, please -see the https://github.com/nanomsg/nanomsg[nanomsg] repository. - -This project is a rewrite of the Scalability Protocols -library known as https://github.com/nanomsg/nanomsg[libnanomsg], -and adds significant new capabilities, while retaining -compatibility with the original. - -It may help to think of this as "nanomsg-next-generation". - -== NNG: Lightweight Messaging Library - -NNG, like its predecessors http://nanomsg.org[nanomsg] (and to some extent -http://zeromq.org/[ZeroMQ]), is a lightweight, broker-less library, -offering a simple API to solve common recurring messaging problems, -such as publish/subscribe, RPC-style request/reply, or service discovery. -The API frees the programmer from worrying about details like connection -management, retries, and other common considerations, so that they -can focus on the application instead of the plumbing. - -NNG is implemented in C, requiring only C99 and CMake to build. -It can be built as a shared or a static library, and is readily -embeddable. It is also designed to be easy to port to new platforms -if your platform is not already supported. - -== License - -NNG is licensed under a liberal, and commercial friendly, MIT license. -The goal to the license is to minimize friction in adoption, use, and -contribution. - -== Enhancements (Relative to nanomsg) - -Here are areas where this project improves on "nanomsg": - -[horizontal] -*Reliability*:: NNG is designed for production use from the beginning. Every -error case is considered, and it is designed to avoid crashing except in cases -of gross developer error. (Hopefully we don't have any of these in our own -code.) - -*Scalability*:: NNG scales out to engage multiple cores using a bespoke -asynchronous I/O framework, using thread pools to spread load without -exceeding typical system limits. - -*Maintainability*:: NNG's architecture is designed to be modular and -easily grasped by developers unfamiliar with the code base. The code -is also well documented. - -*Extensibility*:: Because it avoids ties to file descriptors, and avoids -confusing interlocking state machines, it is easier to add new protocols -and transports to NNG. This was demonstrated by the addition of the -TLS and ZeroTier transports. - -*Security*:: NNG provides TLS 1.2 and ZeroTier transports, offering -support for robust and industry standard authentication and encryption. -In addition, it is hardened to be resilient against malicious attackers, -with special consideration given to use in a hostile Internet. - -*Usability*:: NNG eschews slavish adherence parts of the more complex and -less well understood POSIX APIs, while adopting the semantics that are -familiar and useful. New APIs are intuitive, and the optional support -for separating protocol context and state from sockets makes creating -concurrent applications vastly simpler than previously possible. - -== Compatibility - -This project offers both wire compatibility and API compatibility, -so most nanomsg users can begin using NNG right away. - -Existing nanomsg and https://github.com/nanomsg/mangos[mangos] applications -can inter-operate with NNG applications automatically. - -That said, there are some areas where legacy nanomsg still offers -capabilities NNG lacks -- specifically enhanced observability with -statistics, and tunable prioritization of different destinations -are missing, but will be added in a future release. - -Additionally, some API capabilities that are useful for foreign -language bindings are not implemented yet. - -Some simple single threaded, synchronous applications may perform better under -legacy nanomsg than under NNG. (We believe that these applications are the -least commonly deployed, and least interesting from a performance perspective. -NNG's internal design is slightly less efficient in such scenarios, but it -greatly benefits when concurrency or when multiple sockets or network peers -are involved.) - -== Supported Platforms - -NNG supports Linux, macOS, Windows (Vista or better), illumos, Solaris, -FreeBSD, Android, and iOS. Most other POSIX platforms should work out of -the box but have not been tested. Very old versions of otherwise supported -platforms might not work. - -== Requirements - -To build this project, you will need a C99 compatible compiler and -http://www.cmake.org[CMake] version 3.13 or newer. - -We recommend using the https://ninja-build.org[Ninja] build -system (pass "-G Ninja" to CMake) when you can. -(And not just because Ninja sounds like "NNG" -- it's also -blindingly fast and has made our lives as developers measurably better.) - -If you want to build with TLS support you will also need -https://tls.mbed.org[Mbed TLS]. See <<docs/BUILD_TLS.md#>> for details. - -== Quick Start - -With a Linux or UNIX environment: - -[source,sh] ----- - $ mkdir build - $ cd build - $ cmake -G Ninja .. - $ ninja - $ ninja test - $ ninja install ----- - -== API Documentation - -The API documentation is provided in Asciidoc format in the -`docs/man` subdirectory, and also -https://nanomsg.github.io/nng[online]. -The <<docs/man/nng.7.adoc#,nng(7)>> page provides a conceptual overview and links to -manuals for various patterns. -The <<docs/man/libnng.3.adoc#,libnng(3)>> page is a good starting point for the API reference. - -You can also purchase a copy of the -http://staysail.tech/books/nng_reference/index.html[__NNG Reference Manual__]. -(It is published in both electronic and printed formats.) -Purchases of the book help fund continued development of NNG. - -== Example Programs - -Some demonstration programs have been created to help serve as examples. -These are located in the `demo` directory. - -== Legacy Compatibility - -A legacy `libnanomsg` compatible API is available, and while it offers -less capability than the modern NNG API, it may serve as a transition aid. -Please see <<docs/man/nng_compat.3compat.adoc#,nng_compat(3)>> for details. - -== Commercial Support - -Commercial support for NNG is available. - -Please contact mailto:info@staysail.tech[Staysail Systems, Inc.] to -inquire further. - -== Commercial Sponsors - -The development of NNG has been made possible through the generous -sponsorship of https://www.capitar.com[Capitar IT Group BV] and -http://staysail.tech[Staysail Systems, Inc.]. diff --git a/README.md b/README.md new file mode 100644 index 00000000..cc0504a3 --- /dev/null +++ b/README.md @@ -0,0 +1,200 @@ +# nng - nanomsg-next-gen + +[](https://stand-with-ukraine.pp.ua) +[](https://github.com/nanomsg/nng/actions) +[](https://github.com/nanomsg/nng/actions) +[](https://github.com/nanomsg/nng/actions) +[](https://codecov.io/gh/nanomsg/nng) +[](https://discord.gg/Xnac6b9) +[](https://nng.nanomsg.org/man) +[](https://github.com/nanomsg/nng/blob/dev2.0/LICENSE.txt) +[](https://github.com/nanomsg/nng/releases) + +Please see [here](UKRAINE) for an important message for the people of Russia. + +> [!NOTE] > _THIS IS THE DEVELOPMENT BRANCH FOR NNG._ The content here is +> under development and may not be suitable for production use. +> Please use the [`stable`](https://github.com/nanomsg/nng/tree/stable) branch +> for the latest stable release. + +> [!NOTE] +> If you are looking for the legacy version of nanomsg, please +> see the [libnanomsg](https://github.com/nanomsg/nanomsg) repository. + +This project is a rewrite of the Scalability Protocols +library known as [nanomsg](https://github.com/nanomsg/nanomsg), +and adds significant new capabilities, while retaining +compatibility with the original. + +It may help to think of this as "nanomsg-next-generation". + +## NNG: Lightweight Messaging Library + +NNG, like its predecessors [nanomsg](http://nanomsg.org) (and to some extent +[ZeroMQ](http://zeromq.org/)), is a lightweight, broker-less library, +offering a simple API to solve common recurring messaging problems, +such as publish/subscribe, RPC-style request/reply, or service discovery. +The API frees the programmer from worrying about details like connection +management, retries, and other common considerations, so that they +can focus on the application instead of the plumbing. + +NNG is implemented in C, requiring only C99 and CMake to build. +It can be built as a shared or a static library, and is readily +embeddable. It is also designed to be easy to port to new platforms +if your platform is not already supported. + +## License + +NNG is licensed under a liberal, and commercial friendly, MIT license. +The goal to the license is to minimize friction in adoption, use, and +contribution. + +## Enhancements (Relative to nanomsg) + +Here are areas where this project improves on "nanomsg": + +- _Reliability_ + + NNG is designed for production use from the beginning. + Every error case is considered, and it is designed to avoid crashing except + in cases of gross developer error. + (Hopefully we don't have any of these in our own code.) + +- _Scalability_ + + NNG scales out to engage multiple cores using a bespoke asynchronous I/O + framework, using thread pools to spread load without exceeding typical + system limits. + +- _Maintainability_ + + NNG's architecture is designed to be modular and easily grasped by developers + unfamiliar with the code base. The code is also well documented. + +- _Extensibility_ + + Because it avoids ties to file descriptors, and avoids confusing interlocking + state machines, it is easier to add new protocols and transports to NNG. + This was demonstrated by the addition of the TLS and ZeroTier transports. + +- _Security_ + + NNG provides TLS (1.2 and optionally 1.3) and ZeroTier transports, offering + support for robust and industry standard authentication and encryption. + In addition, it is hardened to be resilient against malicious attackers, + with special consideration given to use in a hostile Internet. + +- _Usability_ + + NNG eschews slavish adherence parts of the more complex and less well + understood POSIX APIs, while adopting the semantics that are familiar and + useful. New APIs are intuitive, and the optional support for separating + protocol context and state from sockets makes creating concurrent + applications vastly simpler than previously possible. + +## Compatibility + +This project offers both wire compatibility and API compatibility, +so most nanomsg users can begin using NNG right away. + +Existing nanomsg and https://github.com/nanomsg/mangos[mangos] applications +can inter-operate with NNG applications automatically. + +That said, there are some areas where legacy nanomsg still offers +capabilities NNG lacks -- specifically enhanced observability with +statistics, and tunable prioritization of different destinations +are missing, but will be added in a future release. + +Additionally, some API capabilities that are useful for foreign +language bindings are not implemented yet. + +Some simple single threaded, synchronous applications may perform better under +legacy nanomsg than under NNG. (We believe that these applications are the +least commonly deployed, and least interesting from a performance perspective. +NNG's internal design is slightly less efficient in such scenarios, but it +greatly benefits when concurrency or when multiple sockets or network peers +are involved.) + +## Supported Platforms + +NNG supports Linux, macOS, Windows (Vista or better), illumos, Solaris, +FreeBSD, Android, and iOS. Most other POSIX platforms should work out of +the box but have not been tested. Very old versions of otherwise supported +platforms might not work. + +Officially, NNG only supports operating systems that are supported by +their vendors. For example, Windows versions 8.1 and lower are no longer +officially supported. + +## Requirements + +To build this project, you will need a C99 compatible compiler and +[CMake](http://www.cmake.org) version 3.15 or newer. + +We recommend using the [Ninja](https://ninja-build.org) build +system (pass `-G Ninja` to CMake) when you can. +(And not just because Ninja sounds like "NNG" -- it's also +blindingly fast and has made our lives as developers measurably better.) + +If you want to build with TLS support you will also need +[Mbed TLS](https://tls.mbed.org). +See the [build instructions](docs/BUILD_TLS.md) for details. + +## Quick Start + +With a Linux or UNIX environment: + +```sh +$ mkdir build +$ cd build +$ cmake -G Ninja .. +$ ninja +$ ninja test +$ ninja install +``` + +## API Documentation + +The API documentation is provided in Asciidoc format in the +`docs/man` subdirectory, and also +[online](https://nanomsg.github.io/nng). + +> [!NOTE] +> However, an effort to convert the documentation to Markdown using `mdbook` +> is underway. + +The [_nng_(7)](docs/man/nng.7.adoc) page provides a conceptual overview and links to +manuals for various patterns. +The [_libnng_(3)](docs/man/libnng.3.adoc) page is a good starting point for the API reference. + +You can also purchase a copy of the +[**NNG Reference Manual**](http://staysail.tech/books/nng_reference/index.html). +(It is published in both electronic and printed formats.) +Purchases of the book help fund continued development of NNG. + +## Example Programs + +Some demonstration programs have been created to help serve as examples. +These are located in the `demo` directory. + +## Legacy Compatibility + +A legacy `libnanomsg` compatible API is available, and while it offers +less capability than the modern NNG API, it may serve as a transition aid. +Please see [_nng_compat_(3)](docs/man/nng_compat.3compat.adoc) for details. + +## Commercial Support + +Commercial support for NNG is available. + +Please contact +[Staysail Systems, Inc.](mailto:info@staysail.tech) +to inquire further. + +## Commercial Sponsors + +The development of NNG has been made possible through the generous +sponsorship of +[Capitar IT Group BV](https://www.capitar.com) +and +[Staysail Systems, Inc.](http://staysail.tech). |