Merge pull request #28 from JadeMatrix/v0.8.6

v0.8.6
JadeMatrix · May 19, 2019 · 1e46e2f · 1e46e2f
2 parents 6a4c830 + 1399df0
commit 1e46e2f
Show file tree

Hide file tree

Showing 17 changed files with 401 additions and 224 deletions.
diff --git a/.gitignore b/.gitignore
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,76 +1,71 @@
 CMAKE_MINIMUM_REQUIRED( VERSION 3.6 )
 
-SET( CMAKE_CXX_STANDARD          11 )
-SET( CMAKE_CXX_STANDARD_REQUIRED ON )
+SET( CMAKE_CXX_STANDARD          11  )
+SET( CMAKE_CXX_STANDARD_REQUIRED ON  )
+SET( CMAKE_CXX_EXTENSIONS        OFF )
 
 PROJECT(
-    "SHOW Tests & Examples"
-    VERSION 0.8.5
+    "Simple Header-Only Webserver"
+    VERSION 0.8.6
     LANGUAGES CXX
 )
 
-FIND_LIBRARY( UNITTEST_LIBRARY UnitTest++ )
+LIST( APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/CMakeModules/" )
 
-INCLUDE_DIRECTORIES(
-    src
+INCLUDE( CTest )
+INCLUDE( GNUInstallDirs )
+
+STRING( REPLACE "${PROJECT_NAME}" "show"
+    CMAKE_INSTALL_DOCDIR
+    "${CMAKE_INSTALL_DOCDIR}"
 )
 
 
-# Tests ########################################################################
+ADD_LIBRARY( show INTERFACE )
+TARGET_INCLUDE_DIRECTORIES(
+    show
+    INTERFACE
+        "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/src/>"
+        "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
+)
+INSTALL(
+    TARGETS show
+    EXPORT "show-config"
+    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}"
+    LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}"
+    ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}"
+)
+INSTALL(
+    DIRECTORY "src/"
+    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+)
 
-if( UNITTEST_LIBRARY )
-    FIND_LIBRARY( CURL_LIBRARY curl )
-    ADD_EXECUTABLE( tests
-        ../tests/async_utils.cpp
-        ../tests/base64_tests.cpp
-        ../tests/connection_tests.cpp
-        ../tests/multipart_tests.cpp
-        ../tests/request_tests.cpp
-        ../tests/response_tests.cpp
-        ../tests/server_tests.cpp
-        ../tests/tests.cpp
-        ../tests/type_tests.cpp
-        ../tests/url_encode_tests.cpp
-    )
-    TARGET_LINK_LIBRARIES( tests
-        ${UNITTEST_LIBRARY}
-        ${CURL_LIBRARY}
-    )
-endif( UNITTEST_LIBRARY )
 
+# CTest sets `BUILD_TESTING` to "on" by default
+IF( BUILD_TESTING )
+    ADD_SUBDIRECTORY( "tests/" )
+ENDIF()
 
-# Examples #####################################################################
+# All examples are excluded from `ALL` but can be built manually
+ADD_SUBDIRECTORY( "examples/" )
 
-ADD_EXECUTABLE( echo
-    ../examples/echo.cpp
-)
-ADD_EXECUTABLE( fileserve
-    ../examples/fileserve.cpp
-)
-ADD_EXECUTABLE( hello_world
-    ../examples/hello_world.cpp
-)
-ADD_EXECUTABLE( http_1_1
-    ../examples/http_1_1.cpp
-)
-ADD_EXECUTABLE(
-    multipart_form_handling
-    ../examples/multipart_form_handling.cpp
-)
-ADD_EXECUTABLE( multiple_clients
-    ../examples/multiple_clients.cpp
+ADD_SUBDIRECTORY( "doc/" )
+
+
+INCLUDE( CMakePackageConfigHelpers )
+WRITE_BASIC_PACKAGE_VERSION_FILE(
+    "${CMAKE_BINARY_DIR}/show-config-version.cmake"
+    COMPATIBILITY SameMinorVersion
 )
-ADD_EXECUTABLE( streaming_echo
-    ../examples/streaming_echo.cpp
+INSTALL(
+    FILES "${CMAKE_BINARY_DIR}/show-config-version.cmake"
+    DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/show/"
 )
 
-ADD_CUSTOM_TARGET( examples )
-ADD_DEPENDENCIES( examples
-    echo
-    fileserve
-    hello_world
-    http_1_1
-    multipart_form_handling
-    multiple_clients
-    streaming_echo
+INSTALL(
+    EXPORT "show-config"
+    NAMESPACE "SHOW::"
+    DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/show/"
 )
+
+EXPORT( EXPORT "show-config" FILE "show-config.cmake" )
diff --git a/CMakeModules/FindSphinx.cmake b/CMakeModules/FindSphinx.cmake
@@ -0,0 +1,34 @@
+INCLUDE( FindPackageHandleStandardArgs )
+
+FOREACH( PROGRAM
+    "apidoc"
+    "autogen"
+    "build"
+    "quickstart"
+)
+    FIND_PROGRAM(
+        SPHINX_${PROGRAM}_LOCATION
+        NAMES "sphinx-${PROGRAM}"
+        HINTS "${SPHINX_DIR}" "$ENV{SPHINX_DIR}"
+        PATH_SUFFIXES "bin/"
+        DOC "Sphinx executable sphinx-${PROGRAM}"
+    )
+    MARK_AS_ADVANCED( SPHINX_${PROGRAM}_LOCATION )
+    IF( SPHINX_${PROGRAM}_LOCATION )
+        ADD_EXECUTABLE( Sphinx::${PROGRAM} IMPORTED )
+        SET_TARGET_PROPERTIES(
+            Sphinx::${PROGRAM}
+            PROPERTIES
+                IMPORTED_LOCATION "${SPHINX_${PROGRAM}_LOCATION}"
+        )
+        SET(Sphinx_${PROGRAM}_FOUND TRUE)
+    ENDIF ()
+ENDFOREACH()
+
+# FPHSA will set this to false if it wasn't actually found
+SET( Sphinx_FOUND TRUE )
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(
+    Sphinx
+    HANDLE_COMPONENTS
+    REQUIRED_VARS Sphinx_FOUND
+)
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -0,0 +1,26 @@
+FIND_PACKAGE( Sphinx COMPONENTS build )
+
+IF( TARGET Sphinx::build )
+    SET(SHOW_DOC_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/show/")
+    ADD_CUSTOM_TARGET( doc ALL )
+
+    FOREACH( BUILDER "html" )
+        FILE(MAKE_DIRECTORY "${SHOW_DOC_OUTPUT_DIR}/${BUILDER}/")
+        ADD_CUSTOM_TARGET(
+            doc_${BUILDER}
+            Sphinx::build
+                -b "${BUILDER}"
+                -d "${CMAKE_CURRENT_BINARY_DIR}"
+                "${CMAKE_CURRENT_SOURCE_DIR}"
+                "${SHOW_DOC_OUTPUT_DIR}/${BUILDER}/"
+        )
+        ADD_DEPENDENCIES( doc doc_${BUILDER} )
+    ENDFOREACH()
+
+    INSTALL(
+        DIRECTORY "${SHOW_DOC_OUTPUT_DIR}"
+        DESTINATION "${CMAKE_INSTALL_DOCDIR}"
+    )
+ELSE ()
+    MESSAGE( WARNING "Sphinx not found, not building documentation" )
+ENDIF ()
diff --git a/doc/Tutorial.rst b/doc/Tutorial.rst
@@ -9,20 +9,23 @@ This shows the basic usage of SHOW; see the `examples <https://github.com/JadeMa
 Including & Compiling
 =====================
 
-For GCC and Clang, you can either link `show.hpp` to one of your standard include search paths, or use the ``-I`` flag to tell the compiler where too find the header::
+The preferred method of including SHOW is via the `CMake <https://cmake.org/>`_ package.  Once installed somewhere CMake can find it, import and use SHOW in your *CMakeLists.txt* with::
     
-    clang++ -I "SHOW/src/" ...
-
-SHOW is entirely contained in a single header file, you have to do then is include SHOW using ``#include <show.hpp>``.  With either compiler you'll also need to specify C++11 support with ``-std=c++11``.
+    FIND_PACKAGE( SHOW REQUIRED COMPONENTS show )
+    ADD_EXECUTABLE( my_server my_server.cpp )
+    TARGET_LINK_LIBRARIES( my_server PRIVATE SHOW::show )
 
-If you use `CMake <https://cmake.org/>`_ and don't have SHOW linked to said include path, you'll need to include the following in your *CMakeLists.txt*::
+You should also switch your compiler to C++11 mode with::
     
-    include_directories( "SHOW/src/" )
+    SET( CMAKE_CXX_STANDARD 11 )
+    SET( CMAKE_CXX_STANDARD_REQUIRED ON )
+    SET( CMAKE_CXX_EXTENSIONS OFF )
 
-replacing ``"SHOW/src/"`` with wherever you've cloned or installed SHOW.  Switch to C++11 mode with::
+For GCC and Clang, you can either link `show.hpp` to one of your standard include search paths, or use the ``-I`` flag to tell the compiler where too find the header::
     
-    set( CMAKE_CXX_STANDARD 11 )
-    set( CMAKE_CXX_STANDARD_REQUIRED ON )
+    clang++ -I "SHOW/src/" ...
+
+SHOW is entirely contained in a single header file, you have to do then is include SHOW using ``#include <show.hpp>``.  With either compiler you'll also need to specify C++11 support with ``-std=c++11``.
 
 Creating a Server
 =================

diff --git a/doc/Classes.rst → doc/Types.rst b/doc/Classes.rst → doc/Types.rst
@@ -1,9 +1,9 @@
-===============
-Classes & Types
-===============
+=====
+Types
+=====
 
-Classes
-=======
+Main Types
+==========
 
 The public interfaces to the main SHOW classes are documented on the following pages:
 
@@ -15,14 +15,14 @@ The public interfaces to the main SHOW classes are documented on the following p
     Request
     Response
 
-Types
-=====
+Support Types
+=============
 
 .. cpp:namespace-push:: show
 
 .. cpp:enum:: http_protocol
     
-    Symbolizes the possibly HTTP protocols understood by SHOW.  The enum members are:
+    Symbolizes the HTTP protocols understood by SHOW.  The enum members are:
 
     +--------------+---------------------------------------------------------+
     | ``HTTP_1_0`` | HTTP/1.0                                                |

diff --git a/doc/Utilities.rst b/doc/Utilities.rst
@@ -21,10 +21,12 @@ These are utilities for handling `base64 <https://en.wikipedia.org/wiki/Base64>`
 
         * :cpp:var:`base64_chars_urlsafe`
 
-.. cpp:function:: std::string base64_decode( const std::string& o, const char* chars = base64_chars_standard )
+.. cpp:function:: std::string base64_decode( const std::string& o, const char* chars = base64_chars_standard, show::base64_flags flags = 0x00 )
     
     Decode a base64-encoded string ``o`` using the character set ``chars``, which must point to a ``char`` array of length 64.  Throws a :cpp:class:`base64_decode_error` if the input is not encoded against ``chars`` or has incorrect padding.
 
+    Incorrect padding can be ignored by passing ``show::base64_ignore_padding`` as the ``flags`` argument.
+
     .. seealso::
 
         * :cpp:var:`base64_chars_standard`

diff --git a/doc/conf.py b/doc/conf.py
@@ -53,10 +53,21 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = u'0.8'
-# The full version, including alpha/beta/rc tags.
-release = u'0.8.5'
+import os, re
+with open( os.path.join(
+    os.path.dirname( os.path.dirname( __file__ ) ),
+    "src",
+    "show.hpp"
+) ) as show_hpp:
+    for line in show_hpp:
+        if "static const std::string string" in line:
+            match = re.search( r"\d+\.\d+\.\d+", line )
+            if match is not None:
+                # The full version, including alpha/beta/rc tags.
+                release = match.group( 0 )
+                # The short X.Y version.
+                version = ".".join( release.split( "." )[ : 2 ] )
+                break
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/doc/index.rst b/doc/index.rst
@@ -15,7 +15,7 @@ SHOW is released under the `zlib license <https://github.com/JadeMatrix/SHOW/blo
     :caption: Contents:
 
     Tutorial
-    Classes
+    Types
     Functions
     Constants
     Utilities

diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
@@ -0,0 +1,18 @@
+SET(
+    SHOW_EXAMPLES
+    echo
+    fileserve
+    hello_world
+    http_1_1
+    multipart_form_handling
+    multiple_clients
+    streaming_echo
+)
+
+FOREACH( EXAMPLE IN LISTS SHOW_EXAMPLES )
+    ADD_EXECUTABLE( ${EXAMPLE} EXCLUDE_FROM_ALL "${EXAMPLE}.cpp" )
+    TARGET_LINK_LIBRARIES( ${EXAMPLE} show )
+ENDFOREACH()
+
+ADD_CUSTOM_TARGET( examples )
+ADD_DEPENDENCIES( examples ${SHOW_EXAMPLES} )
diff --git a/examples/README.md b/examples/README.md
@@ -1,15 +1,16 @@
-There are two easy ways to build the examples in this directory.  If you have [`cmake`](https://cmake.org/) installed, there are build instructions in the supplied *CMakeLists.txt*.  To use it, first run 
+There are two easy ways to build the examples in this directory.  If you have [CMake](https://cmake.org/) installed, make a build directory somewhere and `cd` to it.  Then run
 
 ```sh
-mkdir -p make
-cd make
-cmake ..
+cmake $SHOW_REPO_DIR
 ```
 
-then either run `make examples` to build all examples, or `make $NAME` to build a specific example.  The other way to build any of the examples is manually with Clang (`clang++`) or GCC (`g++`).  Assuming you're running this in the "make" directory from above:
+where `$SHOW_REPO_DIR` is where you cloned SHOW.  Then either run `make examples` to build all examples, or `make $NAME` to build a specific example.  The other way to build any of the examples is manually with Clang (`clang++`) or GCC (`g++`):
 
 ```sh
-clang++ -std=c++11 -I ../src ../examples/$NAME.cpp -o $NAME
+clang++ -std=c++11 \
+    -I $SHOW_REPO_DIR/src \
+    $SHOW_REPO_DIR/examples/$NAME.cpp \
+    -o $NAME
 ```
 
 Each of these servers can be tested from a second terminal window.

diff --git a/examples/echo.cpp b/examples/echo.cpp
@@ -54,7 +54,7 @@ void handle_POST_request( show::request& request )
             headers[ "Content-Type" ] = { "application/octet-stream" };
 
         // This is just the simplest way to read a whole streambuf into a
-        // string, not the most the fastest; see
+        // string, not the fastest; see
         // https://stackoverflow.com/questions/3203452/how-to-read-entire-stream-into-a-stdstring
         std::string message{ std::istreambuf_iterator< char >{ &request }, {} };