facter 2.5.7 → 3.9.6.cfacter.20180606

data/ext/facter/leatherman/CMakeLists.txt

@@ -0,0 +1,143 @@
+cmake_minimum_required(VERSION 3.2.2)
+project(leatherman VERSION 1.2.3)
+
+if (WIN32)
+    link_libraries("-Wl,--nxcompat -Wl,--dynamicbase")
+endif()
+
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" "${PROJECT_BINARY_DIR}/cmake")
+# Populate locale install location
+configure_file(cmake/leatherman.cmake.in "${PROJECT_BINARY_DIR}/cmake/leatherman.cmake" @ONLY)
+include(internal)
+
+# If we're the top-level project, we want to ensure the build type is
+# sane, and flag ourselves as such for later checks
+if ("${CMAKE_PROJECT_NAME}" STREQUAL "${PROJECT_NAME}")
+    if (NOT CMAKE_BUILD_TYPE)
+        message(STATUS "Defaulting to a release build.")
+        set(CMAKE_BUILD_TYPE "Release" CACHE STRING "Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel." FORCE)
+    endif()
+
+    set(LEATHERMAN_TOPLEVEL TRUE)
+else()
+    set(LEATHERMAN_TOPLEVEL FALSE)
+endif()
+
+# If we're the top-level project enable everything by default
+defoption(LEATHERMAN_DEFAULT_ENABLE "Should Leatherman libraries all be built by default" ${LEATHERMAN_TOPLEVEL})
+defoption(LEATHERMAN_DEBUG "Enable verbose logging messages from leatherman macros" FALSE)
+defoption(LEATHERMAN_ENABLE_TESTING "Build the leatherman test binary" ${LEATHERMAN_DEFAULT_ENABLE})
+defoption(LEATHERMAN_INSTALL "Install the leatherman libraries and headers" ${LEATHERMAN_DEFAULT_ENABLE})
+defoption(LEATHERMAN_SHARED "Create shared libraries instead of static" FALSE)
+defoption(LEATHERMAN_USE_ICU "Set when Boost is built with ICU" FALSE)
+
+set(BUILDING_LEATHERMAN TRUE)
+
+#As with most things, we rely on the containing project to set up the
+#common flags
+if (LEATHERMAN_TOPLEVEL)
+    include(options)
+    include(cflags)
+endif()
+
+if (${LEATHERMAN_SHARED} AND (WIN32 OR ${CURL_STATIC}))
+    set(MOCK_CURL FALSE)
+else()
+    set(MOCK_CURL TRUE)
+endif()
+defoption(LEATHERMAN_MOCK_CURL "Use mock curl library for testing Leatherman.curl" ${MOCK_CURL})
+
+add_definitions(${LEATHERMAN_DEFINITIONS})
+if (LEATHERMAN_LOCALE_VAR AND LEATHERMAN_LOCALE_INSTALL)
+    # Add an environment variable to look up install prefix at runtime.
+    add_definitions(-DLEATHERMAN_LOCALE_VAR="${LEATHERMAN_LOCALE_VAR}"
+                    -DLEATHERMAN_LOCALE_INSTALL="${LEATHERMAN_LOCALE_INSTALL}")
+else()
+    # Add install location instead.
+    add_definitions(-DLEATHERMAN_LOCALE_INSTALL="${CMAKE_INSTALL_PREFIX}/share/locale")
+endif()
+
+file(GLOB_RECURSE ALL_LEATHERMAN_SOURCES */src/*.cc */inc/*.hpp)
+add_subdirectory(locales)
+
+add_leatherman_dir(catch EXCLUDE_FROM_VARS)
+add_leatherman_dir(nowide)
+add_leatherman_dir(util)
+add_leatherman_dir(locale)
+add_leatherman_dir(logging)
+add_leatherman_dir(rapidjson)
+add_leatherman_dir(json_container)
+add_leatherman_dir(file_util)
+add_leatherman_dir(curl)
+if (WIN32)
+  add_leatherman_dir(windows)
+endif()
+add_leatherman_dir(dynamic_library)
+add_leatherman_dir(execution)
+add_leatherman_dir(ruby)
+
+# Ensure no LEATHERMAN_LIBS are in LEATHERMAN_DEPS, LEATHERMAN_LIBS should be declared in dependency
+# order above, and we don't want them to come after other dependencies.
+if (LEATHERMAN_LIBS)
+    list(REMOVE_ITEM LEATHERMAN_DEPS ${LEATHERMAN_LIBS})
+endif()
+if (LEATHERMAN_LIBS OR LEATHERRMAN_DEPS)
+    if (LEATHERMAN_SHARED)
+        # When using shared libraries, leave out dependencies as they're already handled in the shared libs.
+        # Including deps after the shared libraries can lead to "multiple definition" errors.
+        list(APPEND LEATHERMAN_LIBRARIES ${LEATHERMAN_LIBS})
+    else()
+        list(APPEND LEATHERMAN_LIBRARIES ${LEATHERMAN_LIBS} ${LEATHERMAN_DEPS})
+    endif()
+endif()
+if (LEATHERMAN_INCLUDE_DIRS)
+    list(REMOVE_DUPLICATES LEATHERMAN_INCLUDE_DIRS)
+endif()
+
+export_var(LEATHERMAN_INCLUDE_DIRS)
+export_var(LEATHERMAN_LIBRARIES)
+
+if(LEATHERMAN_ENABLE_TESTING)
+    enable_testing()
+    add_subdirectory(tests)
+
+    add_cppcheck_dirs(${LEATHERMAN_CPPCHECK_DIRS})
+
+    add_cpplint_files(${ALL_LEATHERMAN_SOURCES})
+
+    # If we're toplevel we want to own these targets. If not we assume
+    # that containing project will set them up for us.
+    if (LEATHERMAN_TOPLEVEL)
+        enable_cppcheck()
+        enable_cpplint()
+    endif()
+endif()
+
+# Install the cmake files we need for consumers
+if (LEATHERMAN_INSTALL)
+    set(CMAKE_FILES
+        cmake/cflags.cmake
+        cmake/GetGitRevisionDescription.cmake
+        cmake/GetGitRevisionDescription.cmake.in
+        cmake/pod2man.cmake
+        cmake/options.cmake
+        cmake/leatherman_config.cmake
+        cmake/normalize_pot.cmake
+        cmake/generate_translations.cmake
+    )
+    set(INSTALL_LOC "lib${LIB_SUFFIX}/cmake/leatherman")
+    install(FILES
+        ${CMAKE_FILES}
+        "${PROJECT_BINARY_DIR}/cmake/leatherman.cmake"
+        DESTINATION "${INSTALL_LOC}/cmake/")
+
+    configure_file(LeathermanConfig.cmake.in "${PROJECT_BINARY_DIR}/LeathermanConfig.cmake" @ONLY)
+    configure_file(LeathermanConfigVersion.cmake.in "${PROJECT_BINARY_DIR}/LeathermanConfigVersion.cmake" @ONLY)
+    install(FILES
+        "${PROJECT_BINARY_DIR}/LeathermanConfig.cmake"
+        "${PROJECT_BINARY_DIR}/LeathermanConfigVersion.cmake"
+        DESTINATION ${INSTALL_LOC})
+    install(EXPORT LeathermanLibraries DESTINATION ${INSTALL_LOC})
+
+    install(FILES "scripts/cpplint.py" DESTINATION "${INSTALL_LOC}/scripts/")
+endif()

data/ext/facter/leatherman/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# How to contribute
+
+Third-party patches are essential for keeping leatherman great. We simply can't
+access the huge number of platforms and myriad configurations for running
+leatherman. We want to keep it as easy as possible to contribute changes that
+get things working in your environment. There are a few guidelines that we
+need contributors to follow so that we can have a chance of keeping on
+top of things.
+
+## Getting Started
+
+* Make sure you have a [Jira account](http://tickets.puppetlabs.com)
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* Submit a ticket for your issue, assuming one does not already exist.
+  * Clearly describe the issue including steps to reproduce when it is a bug.
+  * Make sure you fill in the earliest version that you know has the issue.
+* Fork the repository on GitHub
+
+## New Libraries
+
+All new libraries should include a short section in the README describing how
+to setup and use the library.
+
+## Making Changes
+
+* Create a topic branch from where you want to base your work.
+  * This is usually the master branch.
+  * Only target release branches if you are certain your fix must be on that
+    branch.
+  * To quickly create a topic branch based on master; `git branch
+    fix/master/my_contribution master` then checkout the new branch with `git
+    checkout fix/master/my_contribution`.  Please avoid working directly on the
+    `master` branch.
+* Make commits of logical units.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* If you have python 2 in your path you can run `make cpplint` to ensure your
+  code formatting is clean. The linter runs as part of Travis CI and could fail
+  the CI build.
+* If you have cppcheck in your path you can run `make cppcheck` to ensure your
+  code passes static analysis. cppcheck runs as part of Travis CI and could
+  fail the CI build.
+* Make sure your commit messages are in the proper format.
+
+````
+    (LTH-1234) Make the example in CONTRIBUTING imperative and concrete
+
+    Without this patch applied the example commit message in the CONTRIBUTING
+    document is not a concrete example.  This is a problem because the
+    contributor is left to imagine what the commit message should look like
+    based on a description rather than an example.  This patch fixes the
+    problem by making the example concrete and imperative.
+
+    The first line is a real life imperative statement with a ticket number
+    from our issue tracker.  The body describes the behavior without the patch,
+    why this is a problem, and how the patch fixes the problem when applied.
+````
+
+* Make sure you have added the necessary tests for your changes.
+* Run _all_ the tests to assure nothing else was accidentally broken.
+
+## Making Trivial Changes
+
+### Documentation
+
+For changes of a trivial nature to comments and documentation, it is not
+always necessary to create a new ticket in Jira. In this case, it is
+appropriate to start the first line of a commit with '(doc)' instead of
+a ticket number.
+
+````
+    (doc) Add documentation commit example to CONTRIBUTING
+
+    There is no example for contributing a documentation commit
+    to the Leatherman repository. This is a problem because the contributor
+    is left to assume how a commit of this nature may appear.
+
+    The first line is a real life imperative statement with '(doc)' in
+    place of what would have been the ticket number in a
+    non-documentation related commit. The body describes the nature of
+    the new documentation or comments added.
+````
+
+## Submitting Changes
+
+* Sign the [Contributor License Agreement](http://links.puppetlabs.com/cla).
+* Push your changes to a topic branch in your fork of the repository.
+* Submit a pull request to the repository in the puppetlabs organization.
+* Update your ticket to mark that you have submitted code and are ready for it to be reviewed.
+  * Include a link to the pull request in the ticket
+
+# Additional Resources
+
+* [More information on contributing](http://links.puppetlabs.com/contribute-to-puppet)
+* [Bug tracker (Jira)](https://tickets.puppetlabs.com/browse/LTH)
+* [Contributor License Agreement](http://links.puppetlabs.com/cla)
+* [General GitHub documentation](http://help.github.com/)
+* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
+* #puppet-dev IRC channel on freenode.org

data/ext/facter/leatherman/LICENSE

@@ -0,0 +1,17 @@
+   leatherman - A collection of C++ and CMake utility libraries.
+
+   Copyright (C) 2015 Puppet Labs Inc
+
+   Puppet Labs can be contacted at: info@puppetlabs.com
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/ext/facter/leatherman/LeathermanConfig.cmake.in

@@ -0,0 +1,57 @@
+get_filename_component(current_directory ${CMAKE_CURRENT_LIST_FILE} DIRECTORY)
+list(APPEND CMAKE_MODULE_PATH "${current_directory}/cmake")
+include(leatherman_config)
+include(options)
+include("${current_directory}/LeathermanLibraries.cmake")
+
+get_filename_component(LEATHERMAN_PREFIX "${current_directory}/../../../" ABSOLUTE)
+
+@LEATHERMAN_COMPONENTS@
+
+set(LEATHERMAN_HAVE_LOCALES @LEATHERMAN_USE_LOCALES@)
+
+if (LEATHERMAN_USE_LOCALES AND NOT LEATHERMAN_HAVE_LOCALES)
+    message(SEND_ERROR "You requested locale support, but leatherman was built without it")
+endif()
+
+set(LEATHERMAN_SHARED @LEATHERMAN_SHARED@)
+
+debug("Selected components: ${Leatherman_FIND_COMPONENTS}")
+foreach(component ${Leatherman_FIND_COMPONENTS})
+    string(TOUPPER "${component}" id_upper)
+    set(exclude_var "LEATHERMAN_EXCLUDE_${id_upper}")
+    set(include_var "LEATHERMAN_${id_upper}_INCLUDE")
+    set(lib_var "LEATHERMAN_${id_upper}_LIB")
+    set(deps_var "LEATHERMAN_${id_upper}_DEPS")
+    set(libs_var "LEATHERMAN_${id_upper}_LIBS")
+    debug("Exclude variable ${exclude_var} is ${${exclude_var}}")
+    if(${${exclude_var}})
+        debug("Excluding values for ${id_upper}")
+        debug("* include is ${include_var}: ${${include_var}}")
+        debug("* library is ${libs_var}: ${${libs_var}}")
+    else()
+        debug("Appending values for ${id_upper} to common vars")
+        debug("* include is ${${include_var}}")
+        debug("* library is ${${libs_var}}")
+        list(APPEND LEATHERMAN_INCLUDE_DIRS ${${include_var}})
+        if (NOT "" STREQUAL "${${lib_var}}")
+            # Prepend leatherman libraries, as later libs may depend on earlier libs.
+            list(INSERT LEATHERMAN_LIBS 0 ${${lib_var}})
+        endif()
+        if (${LEATHERMAN_SHARED})
+            # Created with shared libraries, ignore dependencies as they're compiled-in.
+            set(${libs_var} ${${lib_var}})
+        else()
+            append_new(LEATHERMAN_DEPS ${${deps_var}})
+        endif()
+    endif()
+endforeach()
+
+if (LEATHERMAN_LIBS OR LEATHERMAN_DEPS)
+    set(LEATHERMAN_LIBRARIES ${LEATHERMAN_LIBS} ${LEATHERMAN_DEPS})
+endif()
+
+if (LEATHERMAN_INCLUDE_DIRS)
+    list(REMOVE_DUPLICATES LEATHERMAN_INCLUDE_DIRS)
+endif()
+set(LEATHERMAN_MODULE_DIR "${current_directory}/cmake")

data/ext/facter/leatherman/LeathermanConfigVersion.cmake.in

@@ -0,0 +1,11 @@
+set(PACKAGE_VERSION "@PROJECT_VERSION@")
+ 
+# Check whether the requested PACKAGE_FIND_VERSION is compatible
+if("${PACKAGE_VERSION}" VERSION_LESS "${PACKAGE_FIND_VERSION}")
+  set(PACKAGE_VERSION_COMPATIBLE FALSE)
+else()
+  set(PACKAGE_VERSION_COMPATIBLE TRUE)
+  if ("${PACKAGE_VERSION}" VERSION_EQUAL "${PACKAGE_FIND_VERSION}")
+    set(PACKAGE_VERSION_EXACT TRUE)
+  endif()
+endif()

data/ext/facter/leatherman/MAINTAINERS

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "file_format": "This MAINTAINERS file format is described at http://pup.pt/maintainers",
+  "issues": "https://tickets.puppet.com/browse/LTH",
+  "internal_list": "https://groups.google.com/a/puppet.com/forum/?hl=en#!forum/discuss-leatherman-maintainers",
+  "people": [
+    {
+      "github": "MikaelSmith",
+      "email": "michael.smith@puppet.com",
+      "name": "Michael Smith"
+    },
+    {
+      "github": "branan",
+      "email": "branan@puppet.com",
+      "name": "Branan Riley"
+    },
+    {
+      "github": "Magisus",
+      "email": "maggie@puppet.com",
+      "name": "Maggie Dreyer"
+    },
+    {
+      "github": "ahenroid",
+      "email": "andy.henroid@puppet.com",
+      "name": "Andy Henroid"
+    }
+  ]
+}

data/ext/facter/leatherman/README.md

@@ -0,0 +1,416 @@
+# Leatherman - a C++ toolkit
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Usage](#usage)
+  - [Dependencies](#dependencies)
+  - [As a Standalone Library](#as-a-standalone-library)
+    - [Building Leatherman](#building-leatherman)
+    - [Using Leatherman](#using-leatherman)
+  - [As a Submodule](#as-a-submodule)
+  - [Variables Set by Leatherman](#variables-set-by-leatherman)
+  - [CMake Helpers Provided by Leatherman](#cmake-helpers-provided-by-leatherman)
+  - [Internationalization (i18n)](#internationalization-i18n)
+    - [Helper Functions](#helper-functions)
+    - [Enabling i18n](#enabling-i18n)
+    - [Extracting and Translating Text](#extracting-and-translating-text)
+    - [Limitations](#limitations)
+    - [Debugging](#debugging)
+  - [Using Logging](#using-logging)
+  - [Using Catch](#using-catch)
+  - [Using Windows](#using-windows)
+  - [Using JsonContainer](#using-jsoncontainer)
+  - [Using curl](#using-curl)
+- [Extending Leatherman](#extending-leatherman)
+  - [Typical Leatherman Directory Structure](#typical-leatherman-directory-structure)
+  - [Sample Library CMakeLists.txt file](#sample-library-cmakeliststxt-file)
+  - [Vendoring Other Libraries](#vendoring-other-libraries)
+- [How To Release](#how-to-release)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Usage
+
+Leatherman can be used in one of two ways: It can be installed as a
+regular library, and included using the normal CMake `find_package`
+syntax, or it can be setup as a submodule. The recommended method is
+to install Leatherman and use it as a regular system library.
+
+Leatherman is broken up into a number of focused component
+libraries. Both methods of using Leatherman allow you to control which
+components are built and used.
+
+Library install locations can be controlled using the LIB_SUFFIX
+variable, which results in installing libraries to `lib${LIB_SUFFIX}`.
+
+### Dependencies
+
+* Boost, at least version 1.54
+
+### As a Standalone Library
+
+The recommended way to use Leatherman is as a library built and
+installed on your system.
+
+#### Building Leatherman
+
+Leatherman is built like any other cmake project:
+
+    mkdir build
+    cd build
+    cmake ..
+    make
+    sudo make install
+
+By default, all of the component libraries are built when Leatherman
+is used standalone. To disable a component, you can set
+`LEATHERMAN_ENABLE_<LIBRARY>` to any of CMake's falsy values.
+
+#### Using Leatherman
+
+Leatherman's `make install` deploys a standard CMake config file to
+`lib/cmake/leatherman`. This allows the normal CMake `find_package`
+workflow to be used.
+
+    find_package(Leatherman COMPONENTS foo bar baz REQUIRED)
+
+If Leatherman is not installed to a standard system prefix, or on
+Windows where there is no standard prefix, you can set
+`CMAKE_PREFIX_PATH` to the location of Leatherman's install.
+
+### As a Submodule
+
+Leatherman can be included as a git submodule and added as a CMake
+subdirectory. Consider the following:
+
+    CMakeLists.txt
+    lib/
+        CMakeLists.txt
+    vendor/
+        leatherman/
+
+In this setup, your CMakeLists.txt would need to contain the following:
+
+    ...
+    add_subdirectory(vendor/leatherman)
+    ...
+
+To enable individual Leatherman components, you must set
+`LEATHERMAN_ENABLE_<LIBRARY>`. Any libraries not explicitly enabled
+will not be built or available to the containing project.
+
+    ...
+    set(LEATHERMAN_ENABLE_LOCALE TRUE)
+    add_subdirectory(vendor/leatherman)
+    ...
+
+### Variables Set by Leatherman
+
+Leatherman sets two top-level CMake variables:
+
+* `LEATHERMAN_INCLUDE_DIRS` The include paths of all enabled
+  leatherman libraries
+* `LEATHERMAN_LIBRARIES` The library names of all enabled leatherman
+  libraries, as well as their dependencies.
+
+In addition, each enabled library sets a number of library-specific
+variables:
+
+* `LEATHERMAN_<LIBRARY>_INCLUDE` The include directory or directories
+  for the given leatherman library.
+* `LEATHERMAN_<LIBRARY>_LIB` The library name as used by CMake. In the
+  case of header-only leatherman libraries, this will be set to the
+  empty string.
+* `LEATHERMAN_<LIBRARY>_DEPS` Any dependency libraries needed by the
+  given library. This could include other leatherman libraries or
+  3rd-party libraries found via CMake.
+* `LEATHERMAN_<LIBRARY>_LIBS` The contents of both
+  `LEATHERMAN_<LIBRARY>_LIB` and `LEATHERMAN_<LIBRARY>_DEPS`
+
+### CMake Helpers Provided by Leatherman
+
+In addition to the C++ library components, Leatherman provides a few
+CMake helpers. These will be automatically added to your
+`CMAKE_MODULE_PATH` when `find_package` is processed.
+
+* `options`: Common CMake options for leatherman features. Should
+  almost always be used.
+* `cflags`: Sets a `LEATHERMAN_CXX_FLAGS` variable containing the
+  Puppet Labs standard CXXFLAGS for your compiler and platform.
+
+* `leatherman`: Additional functionality provided by Leatherman for
+  consumers. Includes:
+  * Helpers for dealing with variables and scopes
+  * Debugging macros
+  * `cpplint` and `cppcheck` configuration
+  * Logging configuration
+  * Install command with cross-platform defaults
+  * Symbol visibility configuration
+
+* `pod2man`: Adds a `pod2man` macro to generate man files from source.
+
+### Internationalization (i18n)
+
+Leatherman and its components provide support for generating and using
+`gettext`-based message catalogs.
+
+#### Helper Functions
+
+Two helpers are provided for generating message catalogs:
+
+* `gettext_templates <dir> <sources>`: creates a `${PROJECT_NAME}.pot`
+  target (used by `all`) that (re)generates the .pot file from specified
+  source files. If the project is configured with `LEATHERMAN_LOCALES`
+  containing a list of language codes, it will add a target
+  `${PROJECT_NAME}-${LANG}.po` to create or update translation (.po)
+  files matching those codes. Files are put in `dir`. To avoid `make
+  clean` deleting these files, look at how the `locales` directory is
+  structured.
+* `gettext_compile <dir> <inst>`: creates a `translation` target (also
+  used by `all`) to generate the binary message catalogs (.mo files) and
+  configure installing them to the specified install location (`inst`).
+
+`LEATHERMAN_LOCALES` expects a quoted semi-colon separated list, as
+in `LEATHERMAN_LOCALES="en;fr;ja"`.
+
+Normal use of cmake/make should ensure the translation files are up-to-
+date. Translations can be tested by setting the `LC_CTYPE` environment
+variable.
+
+#### Enabling i18n
+
+By default i18n support is disabled. To enable it, define `LEATHERMAN_I18N`
+when compiling your project. To do so, add these two lines to your projects
+CMakeLists.txt file below where you have `find_package(LEATHERMAN ...)` and
+also below where you do `include(cflags)`.
+
+```
+add_definitions(${LEATHERMAN_DEFINITIONS})
+add_definitions(-DLEATHERMAN_I18N)
+```
+
+By default locale files are installed to `${CMAKE_INSTALL_PREFIX}/share/locale`.
+This behavior can be changed to use environment variables for the prefix
+instead by defining `LEATHERMAN_LOCALE_VAR` and `LEATHERMAN_LOCALE_INSTALL`.
+`LEATHERMAN_LOCALE_VAR` should refer to an environment variable pointing to the
+root of the Leatherman install, while `LEATHERMAN_LOCALE_INSTALL` should contain
+a path relative to that location, where locale files should be installed and searched
+for at run time.
+
+For example, if Leatherman is installed to `C:/tools`, and you would like
+to install translation files to `C:/languages/leatherman`, you can create an environment
+variable (e.g. `$LEATHERMAN_LOCATION`) containing `C:\tools`, then set
+`LEATHERMAN_LOCALE_VAR=LEATHERMAN_LOCATION` and 
+`LEATHERMAN_LOCALE_INSTALL=../languages/leatherman`. Then locale files will be installed to
+`C:/tools/../languages/leatherman` and at runtime Leatherman will search for locale
+files there.
+
+To ensure that consuming projects also install their locale files to the right location,
+it is recommended to set `LEATHERMAN_LOCALE_INSTALL` for all projects attempting to use
+Leatherman's i18n tooling.
+
+#### Extracting and Translating Text
+
+The format strings in logging (the first argument) will automatically be
+extracted for the translation template file and translated. Substitution
+arguments will not, and must be explicitly translated.
+
+To translate strings outside of logging, use the `leatherman::locale::translate`
+and `leatherman::locale::format` helpers. Strings passed to the helpers will be
+extracted to .po files. There are several versions of these helpers:
+
+* Basic version (`translate`, `format`) for most standard translations.
+```
+translate("Apple");
+```
+* Pluralized (`translate_n`, `format_n`) when translation depends on number of items.
+```
+// Note the parameter duplication: The first count value `2` selects the appropriate
+// translated message, and the second `2` fills in the `{1}` substitution token.
+format_n("{1} Apple", "{1} Apples", 2, 2);
+```
+* Prefixed-context (`translate_p`, `format_p`) when a word or phrase has multiple meanings.
+```
+translate_p("Fruit", "Apple")
+```
+* Pluralized and prefixed-context (`translate_np`, `format_np`)
+```
+format_np("Fruit", "{1} Apple", "{1} Apples", 3, 3);
+```
+
+`leatherman::locale::format` is a replacement for
+[`boost::locale::format`](http://www.boost.org/doc/libs/1_58_0/libs/locale/doc/html/localized_text_formatting.html),
+which adds locale-aware formatting to `boost::format`, but requires
+different substitution tokens. To support transparently enabling
+`LEATHERMAN_I18N` for only some platforms in a project,
+`leatherman::locale::format` falls-back to using `boost::format`, and
+will convert substitution tokens using the regex `{(\d+)}` to `%\1%`.
+To be safe, assume both formats are special when using `format`, and
+use `{N}` in as the substitution token for your strings. If you need to
+support both modes and use advanced substitution strings, you'll have
+to use an `#ifdef LEATHERMAN_I18N` block to use the correct string.
+
+To use `leatherman::locale::translate` or `leatherman::locale::format`
+in your project, add an include to the top of your cpp file:
+
+```
+#include <leatherman/locale/locale.hpp>
+```
+
+Next, if you would like to use any of the functions, you could do so
+by following this example:
+
+```
+std::cout << leatherman::locale::translate("This is translated") << std::endl;
+std::cout << leatherman::locale::format("This is {1} translated message", 1) << std::endl;
+```
+
+Leatherman also provides format helpers with short names: _(), n_(), p_(), np_().
+These reduce code disruption when adding i18n support, and naming is consistent with
+macros from other i18n libraries.
+
+```
+using namespace leatherman::locale;
+std::cout << _("This is translated") << std::endl;
+std::cout << _("This is {1} translated message", 1) << std::endl;
+```
+
+#### Limitations
+
+Note that on Windows when building Leatherman.Locale as a DLL and
+Boost.Locale statically, you can get some weird behavior from Boost.Locale.
+Avoid using it directly, and ensure all translation operations happen
+as part of the Leatherman.Locale DLL memory space (i.e. in source files).
+
+Translation isn't supported on AIX or Solaris, as GCC on those platforms
+doesn't support `std::locale`. In fact std::locale is buggy, so avoid
+using `get_locale` as well. The CMake option `LEATHERMAN_USE_LOCALES`
+can be used to enable or disable building with Boost.Locale and using
+`std::locale`.
+
+#### Debugging
+
+If output strings are not being translated, [gettext's FAQ](https://www.gnu.org/software/gettext/FAQ.html#integrating_noop)
+has some suggestions for debugging.
+>>>>>>> (maint) Add debugging i18n to README
+
+### Using Logging
+
+Each `.cc` file that uses logging (or includes a header which uses
+logging) needs to know its logging namespace. This can be set by
+defining `LEATHERMAN_LOGGING_NAMESPACE` to a string such as
+"leatherman.logging" or "puppetlabs.facter".
+
+Since typically a large number of files at once will need to use the
+same logging namespace, leatherman provides a CMake macro to set it
+globally. This can be used as follows:
+
+    ...
+    include(leatherman)
+    leatherman_logging_namespace("logging.namespace")
+    ...
+
+Initializing logging via setup\_logging will configure the ostream
+for the default UTF-8 locale (or the specified locale).
+
+### Using Catch
+
+Since [Catch][1] is a testing-only utility, its include directory is
+excluded from LEATHERMAN\_INCLUDE\_DIRS. To use Catch, explicitly add
+
+    include_directories(${LEATHERMAN_CATCH_INCLUDE})
+
+to the CMakeLists.txt file of your testing directory.
+
+### Using Windows
+
+In order to use the Windows libraries, Logging must be set up.
+
+### Using JsonContainer
+
+To use JsonContainer, you must enable [RapidJSON][2] that is included
+as a leatherman component.
+Please refer to the [JsonContainer documentation][3] for API details.
+
+### Using curl
+
+To use the curl wrapper library, libcurl must be installed.
+
+On Ubuntu use the following:
+
+    apt-get install libcurl4-openssl-dev
+    
+On Windows, in Powershell, use:
+
+    (New-Object net.webclient).DownloadFile("http://curl.haxx.se/download/curl-7.42.1.zip", "C:\tools\curl-7.42.1.zip")
+    & 7za x "curl-7.42.1.zip" | FIND /V "ing "
+    cd curl-7.42.1
+    mkdir -Path C:\tools\curl-7.42.1-x86_64_mingw-w64_4.8.4_win32_seh\include
+    cp -r include\curl C:\tools\curl-7.42.1-x86_64_mingw-w64_4.8.4_win32_seh\include
+    mkdir -Path C:\tools\curl-7.42.1-x86_64_mingw-w64_4.8.4_win32_seh\lib
+    cp lib\libcurl.a C:\tools\curl-7.42.1-x86_64_mingw-w64_4.8.4_win32_seh\lib
+    
+On Windows CMake must also be manually pointed to the correct directory by passing the argument 
+`-DCMAKE_PREFIX_PATH="C:\tools\curl-7.42.1-x86_64_mingw-w64_4.8.4_win32_seh`.
+
+## Extending Leatherman
+
+Adding a new library to leatherman is easy!
+
+* Add a new subdirectory with the name of your library
+* Add an appropriate `add_leatherman_dir` invocation to the top-level
+  `CMakeLists.txt`
+* Fill in the headers, sources, and tests of your library. The typical
+  directory structure is below.
+
+The `CmakeLists.txt` file for a library is used both at build time and
+during a `find_package` call for Leatherman. This allows library
+dependencies to be handled identically during both build and find
+operations. Because of this, certain build configuration settings
+might need to be gated on a check for `BUILDING_LEATHERMAN`. See the
+`logging` library for an example of how this is done.
+
+### Typical Leatherman Directory Structure
+
+    leatherman/
+        libname/
+            CMakeLists.txt
+            src/
+                srcfile.cc
+            inc/leatherman/
+                header.hpp
+            tests/
+                testfile.cc
+
+### Sample Library CMakeLists.txt file
+
+    add_leatherman_library("src/srcfile.cc")
+    add_leatherman_test("tests/testfile.cc")
+    add_leatherman_headers("inc/leatherman")
+
+More complex libraries may have dependencies. See the `locale` library
+for a simple example of how dependencies are handled by leatherman
+libraries.
+
+### Vendoring Other Libraries
+
+Sometimes it's necessary to vendor a 3rd-party library in
+Leatherman. In these cases the standard Leatherman macros probably
+won't help you, and you'll need to write a lower-level CMake
+file. This README can't cover all the possible situations here, but
+the `nowide` and `catch` CMake files are both solid examples.
+
+## How To Release
+
+1. Update [CHANGELOG.md](CHANGELOG.md) with release notes based on
+``git log `git describe --abbrev=0 --tags`..HEAD``
+1. Update the version in the project declaration of [CMakeLists.txt](CMakeLists.txt)
+1. Build with gettext to ensure translations are up-to-date
+1. `git tag -s <version> -m '<version>' && git push <puppetlabs> refs/tags/<version>`
+1. Send out an announcement e-mail
+
+[1]: https://github.com/philsquared/Catch
+[2]: https://github.com/miloyip/rapidjson
+[3]: json_container/README.md