improve install experience (#154)

Install documentation lacked detail on several topics and did not cover a
number of scenarios that might arise, particularly in Cygwin. In addition
to the documentation updates, the packaging and C++ bindings have also been
updated so that they are more complete and functional.

.github/workflows/build.yml

@@ -29,7 +29,6 @@ jobs:
         run: |
           wget -q https://sonarcloud.io/static/cpp/build-wrapper-linux-x86.zip
           unzip build-wrapper-linux-x86.zip
-          cmake .
           ./build-wrapper-linux-x86/build-wrapper-linux-x86-64 --out-dir bw-output make all
           wget -q https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-4.5.0.2216-linux.zip
           unzip -qq -o sonar-scanner-cli-4.5.0.2216-linux.zip
@@ -171,6 +170,10 @@ jobs:
       - name: Test
         run: |
           make check-cpp
+      - name: Run Example
+        run: |
+          make example-cpp
+          ./example-cpp
       - name: Install
         run: |
           sudo make install
@@ -305,6 +308,10 @@ jobs:
       - name: Test
         run: |
           make check-cpp
+      - name: Run Example
+        run: |
+          make example-cpp
+          ./example-cpp
       - name: Install
         run: |
           sudo make install
@@ -387,3 +394,6 @@ jobs:
       - name: Test
         run: |
           cmake --build . --config Release --target check-cpp
+      - name: Run Example
+        run: |
+          cmake --build . --config Release --target run-example-cpp

CMakeLists.txt

@@ -1,6 +1,7 @@
 cmake_minimum_required(VERSION 3.2.3)
 
 project(stumpless VERSION 2.0.0)
+set(CMAKE_PROJECT_HOMEPAGE_URL "https://goatshriek.github.io/stumpless/")
 
 string(CONCAT enable_cpp_help_string
   "Build the C++ language binding library. The library will be added to the "
@@ -664,8 +665,11 @@ if(MINGW)
   set_target_properties(stumpless PROPERTIES PREFIX "")
 endif()
 
-if(HAVE_STDATOMIC_H AND NOT APPLE)
-  target_link_libraries(stumpless PRIVATE atomic)
+if(HAVE_STDATOMIC_H)
+  find_library(LIBATOMIC_FOUND atomic)
+  if(LIBATOMIC_FOUND)
+    target_link_libraries(stumpless PRIVATE atomic)
+  endif()
 endif()
 
 if(HAVE_WINSOCK2_H)

INSTALL.md

@@ -1,9 +1,99 @@
-# Building Stumpless
+# Installing a Stumpless package
+If you just want to use stumpless and aren't looking to modify or otherwise
+develop it, the easiest path is to use one of the release packages. These are
+available for a few common platforms, and are attached to each
+[release](https://github.com/goatshriek/stumpless/releases) of stumpless. If you
+need a package format that is not available here, please submit an issue with a
+request for the format and the project team will see if this can be added.
 
-In order to compile Stumpless you will need cmake and a compatible build system
-such as the GNU toolchain or Microsoft Visual Studio. Given these dependencies
-building the library is very straightforward. The examples below show how to do
-this in a build environment using `make` from a fresh clone.
+Stumpless is not currently registered in any online package repositories such
+as Chocolatey or Debian. If you need the library in a location like this, please
+open an issue and the project team will see what we can do.
+
+
+## Debian Package
+A `.deb` package is provided for use in environments that support them, like
+Debian and Ubuntu. The package can be installed with the usual command:
+
+```sh
+# you might need sudo (or root privileges) to install
+dpkg -i stumpless-2.0.0-amd64.deb
+```
+
+
+## RPM Package
+A `.rpm` package is provided for use in Red Hat Linux environments. It can be
+installed in the traditional way as well:
+
+```sh
+# again, make sure you have the correct permissions
+rpm -i stumpless-2.0.0-x86_64.rpm
+```
+
+
+## Generic Shell Installer
+CMake generates a shell script that can be used to install the library on
+systems lacking a more traditional package manager, for example Cygwin. Simply
+execute the script from the prefix where you want to install the library. The
+script is a self-extracting TGZ archive that provides the headers and library
+files.
+
+```sh
+# you might need to do this with sudo!
+# make sure your permissions allow you to write to the install locations
+cd /usr
+./stumpless-2.0.0.sh
+```
+
+
+## Windows Installer
+A simple `.msi` installer is provided that puts the DLL, `.lib`, and include
+headers into a Program Files folder. Note that you may need to update search
+paths to locate these resources after installation, as the installer does not
+currently handle this.
+
+
+## C++ Installers
+For each provided package, there is also a C++ package (`stumpless-cpp`)
+that includes the C++ library. These packages also include the C library, so
+if you think you might need the C++ library at some point down the road you
+can use this one to install it at the same time as the base library.
+
+
+# Building Stumpless from the source
+In order to compile Stumpless you will at a bare minimum cmake and a compatible
+build system such as the GNU toolchain or Microsoft Visual Studio. While the
+source itself can be downloaded using a number of tools (wget, a browser, etc.)
+git is the recommended way to do this if you need to get specific release tags,
+branches, or make any changes yourself.
+
+
+## Prepping your System
+Since there are so many possible ways to set up an environment, stumpless does
+not provide any single way to do this. However, here are some one-liners that
+can get everything installed for you in some common environments.
+
+For Linux systems with a package manager like `apt`, you can install the needed
+tools (for a GNU toolchain) with something like the following:
+
+```sh
+sudo apt-get install git cmake make gcc g++ doxygen
+```
+
+Cygwin lacks a package manager in the environment itself, requiring packges to
+be installed using the setup script. You can install the needed packages in the
+GUI, or if you want to just do it via command line, you can do something like
+this:
+
+```sh
+setup-x86_64.exe -q -P git,cmake,make,gcc-core,gcc-g++,doxygen
+```
+
+
+## Building
+Once all of the build dependencies are available, actually building the library
+is straightforward. The examples below show how to do this in an environment
+using `make` from a fresh clone.
 
 ```sh
 # cloning the latest version of the source tree
@@ -21,7 +111,51 @@ make all
 ```
 
 Other environments should be built according to their normal style. For example
-Visual Studio provides a CMake menu that will display all available targets.
+Visual Studio provides a CMake menu in the IDE that will display all available
+targets.
+
+If you're unsure of the build commands for the toolchain on your system, then
+cmake can run these commands for you if you invoke it in build mode.
+
+```sh
+# build the `all` target using whatever toolchain cmake detected during the
+# configuration stage
+# the argument to the `--build` parameter is the root of the folder where we
+# ran the original cmake configuration command
+cmake --build . --target all
+
+# build and run the test suite the same way
+cmake --build . --target all
+```
+
+The type of build can be changed at configuation time by defining the
+`CMAKE_BUILD_TYPE` symbol during configuration.
+
+```sh
+# benchmark testing should always be done using Release builds
+cmake -DCMAKE_BUILD_TYPE=Release ../stumpless
+```
+
+However, some environments (Visual Studio being one) require the configuration
+to be passed in during build steps. In the above example, builds would still use
+the default build type, effectively ignoring the configuration step. To specify
+the build type you will need to provide a config to use during build:
+
+```sh
+# explicitly use the Release configuration we have in our toolchain
+cmake --build . --config x64-Release --target bench
+```
+
+In systems like this, it is easiest to use an IDE that does this work for you,
+for example Visual Studio. For more information on these build topics, refer to
+the CMake documentation on
+[build mode](https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project)
+and
+[multi-config generators](https://cmake.org/cmake/help/latest/prop_gbl/GENERATOR_IS_MULTI_CONFIG.html).
+
+The rest of this documentation uses make commands for simplicity, but for any
+target you can build it using cmake build mode if you need truly portable
+command line invocation.
 
 ## Verifying your Build
 
@@ -45,7 +179,7 @@ will download and build the Google Benchmark library in order to run.
 make bench
 ```
 
-## Installing
+## Installing your Build
 
 You can use the install target to install the library on your machine after the
 build.
@@ -58,10 +192,74 @@ make install
 sudo make install
 ```
 
-There is not currently an uninstall target supported, so removal of the library
+A simple way to make sure that your install is working as you expected is to
+compile one of the examples without using the built-in targets. If the target
+builds but your own compilation doesn't, then there is something wrong with
+your install.
+
+```sh
+# first we use the build target to make sure it works
+make example-entry && ./example-entry
+
+# next, we compile the same example manually
+gcc docs/examples/entry/entry_example.c -lstumpless -omanual_entry_example
+# this should work if everything was correct
+./manual_entry_example
+```
+
+If you do have issues, there are a few simple things for you to check. An easy
+issue is if the installed library is not in the system's library search path,
+which will usually lead to an error message of `cannot find -lstumpless` or
+similar. If you see this, check the current search path and if needed set
+appropriate environment variables or add compilation flags to add the location
+that stumpless was installed to the search path. Some examples are gcc's `-L`
+option, the `LD_LIBRARY_PATH` environment variable on many Linux systems, and
+the environment variable `LIBRARY_PATH` in Cygwin.
+
+If you find that stumpless has installed to unexpected locations and you want
+to modify this, use the `CMAKE_INSTALL_PREFIX` definition during the
+configuration step of the build. You can always re-run cmake to update this in
+an existing build tree if you need to change it.
+
+```sh
+# our initial build installed to /usr/local locations, which we didn't want
+cat install_manifest.txt
+# /usr/local/include/stumpless/target/network.h
+# /usr/local/include/stumpless/target/socket.h
+# /usr/local/lib/libstumpless.so.2.0.0
+# /usr/local/lib/libstumpless.so
+# /usr/local/include/stumpless.h
+# <output truncated>
+
+# re-run the configuration
+cmake -DCMAKE_INSTALL_PREFIX=/usr ../stumpless
+
+# re-do the install
+sudo make install
+
+# now we see things in the right place!
+cat install_manifest.txt
+# /usr/include/stumpless/target/network.h
+# /usr/include/stumpless/target/socket.h
+# /usr/lib/libstumpless.so.2.0.0
+# /usr/lib/libstumpless.so
+# /usr/include/stumpless.h
+# /usr/include/stumpless/config.h
+# <output truncated>
+```
+
+### Uninstalling
+
+There is currently no uninstall target supported, so removal of the library
 and its include files must be done manually if it is no longer needed. Please
 submit an issue on the project's Github site if you feel that you need a build
-target providing this feature.
+target providing this feature. For the time being, you can run the contents
+of the `install_manifest.txt` file (generated during the install) through `rm`
+like this:
+
+```sh
+xargs rm < install_manifest.txt
+```
 
 ## C++ Library
 
@@ -73,8 +271,13 @@ gem installed for this to work. This can be done with a simple
 `gem install wrapture`, or you can use the `Gemfile` included in stumpless and
 simply do a `bundle install` to pull it in.
 
-After you have wrapture available, building and testing the C++ library can
-be done like this:
+If you need a ruby environment, we recommend using `rvm` to manage versions and
+gemsets. You can find more information on rvm on the
+[project website](https://rvm.io/). Other options are `rbenv`, your package
+manager's distribution of ruby, or RubyInstaller (for Windows).
+
+After you have a ruby environment and wrapture is available, building and
+testing the C++ library can be done like this:
 
 ```sh
 # in the build directory, modify the cmake to enable c++

README.md

@@ -55,8 +55,9 @@ make -j 4 all
 sudo make install
 ```
 
-Check out the [Installation Instructions](INSTALL.md) for more detail on building
-and installing stumpless.
+Check out the [Installation Instructions](INSTALL.md) for more detail on
+building and installing stumpless in different environments and/or with other
+toolchains.
 
 ## Basic Usage
 

docs/cpp.md

@@ -17,9 +17,11 @@ Targets and entries can be created by instantiating the appropriate class, just
 as you might expect:
 
 ```cpp
-FileTarget myLogFile( "logfile.log",
-                      STUMPLESS_OPTION_NONE,
-                      Facility::USER );
+#include <stumpless.hpp>
+
+// ...
+
+FileTarget myLogFile( "logfile.log" );
 
 Entry processStarting( Facility::USER,
                        Severity::INFO,

docs/examples/cpp/README.md

@@ -20,18 +20,12 @@ target types from the C library. The constructors take the same parameters as
 the matching open target function in the C library. This example shows how to
 open a file target.
 
-Note that you will need to include the header for the class in order to use it.
-There is currently no roll-up header for the entire C++ library, though this is
-planned for an upcoming release in the project roadmap (see `docs/roadmap.md`).
-
 ```cpp
-#include <FileTarget.hpp>
+#include <stumpless.hpp>
 
 // ...
 
-FileTarget file_logger( "logfile.log",
-                        STUMPLESS_OPTION_NONE,
-                        Facility::USER );
+FileTarget file_logger( "logfile.log" );
 ```
 
 Logging to the target is done with the `Log` function, which has a few forms
@@ -123,19 +117,20 @@ library, you can check the same constants as before for them, though you will
 need to include the C header to do so.
 
 ```cpp
-if( STUMPLESS_SOCKET_TARGETS_SUPPORTED ) {
+#ifdef STUMPLESS_SOCKET_TARGETS_SUPPORTED
   std::stdout << "logging to " << STUMPLESS_DEFAULT_SOCKET << " by default" << std::endl;
-}
+#endif
 ```
 
 However, for some (but not all) constants there is a matching constant that puts
 these constants into a namespace:
 
 ```cpp
 // this check still has to use the C #define
-if( STUMPLESS_SOCKET_TARGETS_SUPPORTED ) {
+#ifdef STUMPLESS_SOCKET_TARGETS_SUPPORTED
+  // this one has a constant that can be used instead
   std::stdout << "logging to " << SocketTarget::DEFAULT_SOCKET << " by default" << std::endl;
-}
+#endif
 ```
 
 ## Running this Example