From 6a50035b242b972c1d9b659ba63e037a0a8afe71 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Fri, 29 Dec 2017 14:21:20 -0800
Subject: fixes #166 Websocket TLS mapping

This introduces the wss:// scheme, which is available and works like
the ws:// scheme if TLS is enabled in the library.

The library modularization is refactored somewhat, to make it easier
to use.  There is now a single NNG_ENABLE_TLS that enables TLS support
under the hood.

This also adds a new option for the TLS transport, NNG_OPT_TLS_CONFIG
(and a similar one for WSS, NNG_OPT_TLS_WSS_CONFIG) that offer access
to the underlying TLS configuration object, which now has a public API
to go with it as well.

Note that it is also possible to use pure HTTPS using the *private*
API, which will be exposed in a public form soon.
---
 README.adoc | 44 +++++++++++++++++++++++++++-----------------
 1 file changed, 27 insertions(+), 17 deletions(-)

(limited to 'README.adoc')

diff --git a/README.adoc b/README.adoc
index 29c8e1c2..8912d879 100644
--- a/README.adoc
+++ b/README.adoc
@@ -11,10 +11,10 @@ can start using it for development, as we believe we are getting closer
 to release readiness.
 
 Review and testing feedback are appreciated however; but please understand
-that the project is still quite preliminary.
+that the project is still preliminary.
 
-This is a work in progress, and is *not* suitable for production use or
-publication.  When the library is ready for broader consumption, an
+This is a work in progress, and is *not* suitable for production use.
+When the library is ready for broader consumption, an
 announcement will be posted on the nanomsg mailing list and website.
 
 Some https://nanomsg.github.io/nng/man/[manual pages] are posted
@@ -24,26 +24,36 @@ If you are looking for the current production version of nanomsg, please
 see the https://github.com/nanomsg/nanomsg[nanomsg repo].
 
 If you want to build and test yourself, you need CMake version 3.1, and
-you can use standard CMake build recipes.  On a Linux/UNIX system, 
-you can for example do:
+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:
 
 [source,sh]
 ----
   $ mkdir build
-  $ cmake ..
-  $ make
-  $ make test
+  $ cmake -G Ninja ..
+  $ ninja
+  $ ninja test
 ----
 
-If you want to enable the TLS transport, which is not supported by legacy
-nanomsg, use -DNNG_TRANSPORT_TLS=ON in your cmake command line.  You will
-need to have the ARM mbedTLS library installed.  (This is available in
-Xenial Ubuntu as libmbedtls-dev).
-
-The API is not yet documented, but if you want to explore using the newer
-API, pleaes have a look at the `nng.h` header file.  A legacy compatible
-`nng_compat.h` header is available and offers API compatibility with legacy
-_nanomsg_.
+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`.
+
+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.
+
+Documentation is a work in progres -- initial pages are
+https://nanomsg.github.io/nng[online], but there is much missing.
+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_.
 
 == Commercial Support
 
-- 
cgit v1.2.3-70-g09d2

