From b9cb718076bf1c408076153e33b5cd7ecc741d26 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 1 Jun 2018 19:20:26 -0700 Subject: fixes #514 Need documentation updates for 1.0 --- README.adoc | 182 ++++++++--- README.html | 715 +++++++++++++++++++++++++++++++++++++++++++ docs/BUILD_ANDROID.adoc | 7 +- docs/BUILD_CROSSCOMPILE.adoc | 4 + docs/BUILD_IOS.adoc | 7 +- docs/BUILD_TLS.adoc | 4 + docs/BUILD_ZEROTIER.adoc | 4 + 7 files changed, 876 insertions(+), 47 deletions(-) create mode 100644 README.html diff --git a/README.adoc b/README.adoc index bac1683c..db63cf90 100644 --- a/README.adoc +++ b/README.adoc @@ -1,44 +1,135 @@ ifdef::env-github[] -:tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: -:caution-caption: :fire: -:warning-caption: :warning: endif::[] = nng - nanomsg-next-gen +// Note: This README is optimized for display with Asciidoctor, or +// on the github status page. An HTML version is in the same directory +// and may be more pleasantly formatted for human readers (when opened +// in a browswer). + +// Note: If you're updating this file, don't forget to re-run asciidoctor +// to update the aforementioned HTML file! + image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License] image:https://img.shields.io/circleci/project/github/nanomsg/nng.svg?label=[Linux Status,link="https://circleci.com/gh/nanomsg/nng"] image:https://img.shields.io/appveyor/ci/nanomsg/nng/master.svg?label=windows[Windows Status,link="https://ci.appveyor.com/project/nanomsg/nng"] image:https://codecov.io/gh/nanomsg/nng/branch/master/graph/badge.svg?label=coverage[Coverage,link="https://codecov.io/gh/nanomsg/nng"] image:https://api.codacy.com/project/badge/Grade/f241cba192974787b66f7e4368777ebf["Codacy code quality", link="https://www.codacy.com/app/gdamore/nng?utm_source=github.com&utm_medium=referral&utm_content=nanomsg/nng&utm_campaign=Badge_Grade"] -This repository represents a rewrite of the SP protocol -library known as https://github.com/nanomsg/nanomsg[libnanomsg]. -This is pre-release, but at this point we believe that the library is -robust enough to use for development and testing, and we are actively -seeing additional testing and review. +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, brokerless 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 comomon 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. -While we have made every reasonable effort to ensure that this library -is robust and safe, it is still a *pre-release*, and details are subject -to change. Caution is advised before depending upon it. +*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. -NOTE: We're getting pretty close to removing this caveat though, -and we'd like help from others in testing to further improve our confidence -before we do. +*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. -When the library is ready for broader consumption, an -announcement will be posted on the nanomsg mailing list and website. +== Compatibility -If you are looking for the current production version of nanomsg, please -see the https://github.com/nanomsg/nanomsg[nanomsg repo]. +This project offers both wire compatibility and API compability, +so most nanomsg users can begin using NNG right away. -If you want to build and test yourself, you need CMake version 3.1, and -you can use standard CMake build recipes. (We highly recommend using -https://ninja-build.org[Ninja] as it is much faster than traditional -build systems.) On a Linux/UNIX system, if you have Ninja already -installed, you can for example do: +Existing nanomsg and github.com/go-mangos/mangos[mangos] applications +can interoperate 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.1 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[mbedTLS]. Seee <> for details. + +== Quick Start + +With a Linux or UNIX environment: [source,sh] ---- @@ -48,33 +139,38 @@ installed, you can for example do: $ ninja test ---- -This library can be compiled with support for TLS, which enables -the use of the "tls+tcp://" and "wss://" schemes. In order to this, -configure with `-DNNG_ENABLE_TLS=ON`. +== API Documentation + +The API documentation is provided in Asciidoc format in the +`docs/man` subdirectory, and also +https://nanomsg.github.io/nng[online]. +The <> page is a good starting point. -NOTE: The `NNG_ENABLE_TLS` library depends on the ARM -https://tls.mbed.org[mbedTLS] library. This library is available -in packaged form for many systems, and can be built for just about -any of the others. However, please be aware of the licensing -implications, because the mbedTLS library carries other licensing -requirements (either Apache or GPL) than _nng_. -either Apache or GPL licenses. +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. -Much of the library, but not all, is documented in the docs/ folder, -and also https://nanomsg.github.io/nng[online]. +== Example Programs -You can also buy a copy of the -https://leanpub.com/nngmanual/[NNG Reference Manual at Leanpub]. -(Purchases from Leanpub help fund our work, and get get a nicer -formatted single PDF or ebook edition.) +Some demonstration programs have been created to help serve as examples. +These are located in the `demo` directory. -You can also explore the `nng.h` header file, which provides the public -API. A legacy compatible `nng_compat.h` header is available and -offers API compatibility with legacy _nanomsg_. +== 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 <> for details. == Commercial Support -Commercial support for _NNG_ is available. +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.html b/README.html new file mode 100644 index 00000000..f2d99b5c --- /dev/null +++ b/README.html @@ -0,0 +1,715 @@ + + + + + + + +nng - nanomsg-next-gen + + + + + +
+
+
+
+

MIT License +Linux Status +Windows Status +Coverage +Codacy code quality

+
+
+ + + + + +
+
Note
+		 +If you are looking for the legacy version of nanomsg, please +see the nanomsg repository. +
+
+
+

This project is a rewrite of the Scalability Protocols +library known as 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 nanomsg (and to some extent +ZeroMQ), is a lightweight, brokerless 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 comomon 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 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 compability, +so most nanomsg users can begin using NNG right away.

+
+
+

Existing nanomsg and github.com/go-mangos/mangos[mangos] applications +can interoperate 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 +CMake version 3.1 or newer.

+
+
+

We recommend using the 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 +mbedTLS. Seee docs/BUILD_TLS.html for details.

+
+
+
+
+

Quick Start

+
+
+

With a Linux or UNIX environment:

+
+
+
+
  $ mkdir build
+  $ cmake -G Ninja ..
+  $ ninja
+  $ ninja test
+
+
+
+
+
+

API Documentation

+
+
+

The API documentation is provided in Asciidoc format in the +docs/man subdirectory, and also +online. +The libnng(3) page is a good starting point.

+
+
+

You can also purchase a copy of the +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 nng_compat(3) for details.

+
+
+
+
+

Commercial Support

+
+
+

Commercial support for NNG is available.

+
+
+

Please contact Staysail Systems, Inc. to +inquire further.

+
+
+
+
+

Commercial Sponsors

+
+
+

The development of NNG has been made possible through the generous +sponsorship of Capitar IT Group BV and +Staysail Systems, Inc..

+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/BUILD_ANDROID.adoc b/docs/BUILD_ANDROID.adoc index 6e210c6d..7cb40339 100644 --- a/docs/BUILD_ANDROID.adoc +++ b/docs/BUILD_ANDROID.adoc @@ -1,7 +1,10 @@ +ifdef::env-github[] +:note-caption: :information_source: +endif::[] + = Building for Android -NOTE: I am not an Android developer, so this work has received only cursory -testing. As always, _caveat emptor_. +NOTE: This work has received only cursory testing. As always, _caveat emptor_. == Pre-Requisites diff --git a/docs/BUILD_CROSSCOMPILE.adoc b/docs/BUILD_CROSSCOMPILE.adoc index 8b57f812..c943f173 100644 --- a/docs/BUILD_CROSSCOMPILE.adoc +++ b/docs/BUILD_CROSSCOMPILE.adoc @@ -1,3 +1,7 @@ +ifdef::env-github[] +:note-caption: :information_source: +endif::[] + = Building for Cross Compilation TIP: Cross-compiling is used when the operating system or process architecure diff --git a/docs/BUILD_IOS.adoc b/docs/BUILD_IOS.adoc index eed23714..80f7c906 100644 --- a/docs/BUILD_IOS.adoc +++ b/docs/BUILD_IOS.adoc @@ -1,7 +1,10 @@ +ifdef::env-github[] +:note-caption: :information_source: +endif::[] + = Building for iOS (and tvOS, watchOS) -NOTE: I am not an iOS developer, so this work has had only minimal validation. -As always, _caveat emptor_! +NOTE: This work has had only minimal validation. As always, _caveat emptor_. == Pre-Requisites diff --git a/docs/BUILD_TLS.adoc b/docs/BUILD_TLS.adoc index 242e7f44..0ffa9c9d 100644 --- a/docs/BUILD_TLS.adoc +++ b/docs/BUILD_TLS.adoc @@ -1,3 +1,7 @@ +ifdef::env-github[] +:important-caption: :heavy_exclamation_mark: +endif::[] + = Building for TLSv1.2 Support If you want to include support for Transport Layer Security diff --git a/docs/BUILD_ZEROTIER.adoc b/docs/BUILD_ZEROTIER.adoc index 28f6098d..a61d065c 100644 --- a/docs/BUILD_ZEROTIER.adoc +++ b/docs/BUILD_ZEROTIER.adoc @@ -1,3 +1,7 @@ +ifdef::env-github[] +:important-caption: :heavy_exclamation_mark: +endif::[] + = Building for ZeroTier Support If you want to include support for the experimental ZeroTier -- cgit v1.2.3-70-g09d2