{"id":15022715,"url":"https://github.com/puppetlabs/leatherman","last_synced_at":"2025-07-31T00:41:39.408Z","repository":{"id":27738560,"uuid":"31226286","full_name":"puppetlabs/leatherman","owner":"puppetlabs","description":"A collection of C++ and CMake utility libraries.","archived":false,"fork":false,"pushed_at":"2025-01-13T22:50:25.000Z","size":2391,"stargazers_count":59,"open_issues_count":0,"forks_count":78,"subscribers_count":158,"default_branch":"main","last_synced_at":"2025-05-24T19:04:53.166Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-23T19:50:46.000Z","updated_at":"2025-02-06T20:32:15.000Z","dependencies_parsed_at":"2023-10-04T23:31:47.396Z","dependency_job_id":"b0f1bfdb-af58-4b26-a3c6-2924239822c7","html_url":"https://github.com/puppetlabs/leatherman","commit_stats":{"total_commits":504,"total_committers":55,"mean_commits":9.163636363636364,"dds":0.7361111111111112,"last_synced_commit":"456910ecbe905cf226dd7e9fbf575a5559282ad8"},"previous_names":["puppetlabs-toy-chest/leatherman","puppetlabs/leatherman"],"tags_count":102,"template":false,"template_full_name":null,"purl":"pkg:github/puppetlabs/leatherman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fleatherman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fleatherman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fleatherman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fleatherman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/leatherman/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fleatherman/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267967720,"owners_count":24173566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T19:58:18.251Z","updated_at":"2025-07-31T00:41:39.374Z","avatar_url":"https://github.com/puppetlabs.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Leatherman - a C++ toolkit\n\nThis repository is archived and Perforce will no longer be updating this repository. For more information, see [this Puppet blog post](https://www.puppet.com/blog/open-source-puppet-updates-2025).\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [Usage](#usage)\n  - [Dependencies](#dependencies)\n  - [As a Standalone Library](#as-a-standalone-library)\n    - [Building Leatherman](#building-leatherman)\n    - [Using Leatherman](#using-leatherman)\n  - [As a Submodule](#as-a-submodule)\n  - [Variables Set by Leatherman](#variables-set-by-leatherman)\n  - [CMake Helpers Provided by Leatherman](#cmake-helpers-provided-by-leatherman)\n  - [Internationalization (i18n)](#internationalization-i18n)\n    - [Helper Functions](#helper-functions)\n    - [Enabling i18n](#enabling-i18n)\n    - [Extracting and Translating Text](#extracting-and-translating-text)\n    - [Limitations](#limitations)\n    - [Debugging](#debugging)\n  - [Using Logging](#using-logging)\n  - [Using Catch](#using-catch)\n  - [Using Windows](#using-windows)\n  - [Using JsonContainer](#using-jsoncontainer)\n  - [Using curl](#using-curl)\n- [Extending Leatherman](#extending-leatherman)\n  - [Typical Leatherman Directory Structure](#typical-leatherman-directory-structure)\n  - [Sample Library CMakeLists.txt file](#sample-library-cmakeliststxt-file)\n  - [Vendoring Other Libraries](#vendoring-other-libraries)\n- [How To Release](#how-to-release)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Usage\n\nLeatherman can be used in one of two ways: It can be installed as a\nregular library, and included using the normal CMake `find_package`\nsyntax, or it can be setup as a submodule. The recommended method is\nto install Leatherman and use it as a regular system library.\n\nLeatherman is broken up into a number of focused component\nlibraries. Both methods of using Leatherman allow you to control which\ncomponents are built and used.\n\nLibrary install locations can be controlled using the LIB_SUFFIX\nvariable, which results in installing libraries to `lib${LIB_SUFFIX}`.\n\n### Dependencies\n\n* Boost, at least version 1.54\n\n### As a Standalone Library\n\nThe recommended way to use Leatherman is as a library built and\ninstalled on your system.\n\n#### Building Leatherman\n\nLeatherman is built like any other cmake project:\n\n    mkdir build\n    cd build\n    cmake ..\n    make\n    sudo make install\n\nBy default, all of the component libraries are built when Leatherman\nis used standalone. To disable a component, you can set\n`LEATHERMAN_ENABLE_\u003cLIBRARY\u003e` to any of CMake's falsy values.\n\n#### Using Leatherman\n\nLeatherman's `make install` deploys a standard CMake config file to\n`lib/cmake/leatherman`. This allows the normal CMake `find_package`\nworkflow to be used.\n\n    find_package(Leatherman COMPONENTS foo bar baz REQUIRED)\n\nIf Leatherman is not installed to a standard system prefix, or on\nWindows where there is no standard prefix, you can set\n`CMAKE_PREFIX_PATH` to the location of Leatherman's install.\n\n### As a Submodule\n\nLeatherman can be included as a git submodule and added as a CMake\nsubdirectory. Consider the following:\n\n    CMakeLists.txt\n    lib/\n        CMakeLists.txt\n    vendor/\n        leatherman/\n\nIn this setup, your CMakeLists.txt would need to contain the following:\n\n    ...\n    add_subdirectory(vendor/leatherman)\n    ...\n\nTo enable individual Leatherman components, you must set\n`LEATHERMAN_ENABLE_\u003cLIBRARY\u003e`. Any libraries not explicitly enabled\nwill not be built or available to the containing project.\n\n    ...\n    set(LEATHERMAN_ENABLE_LOCALE TRUE)\n    add_subdirectory(vendor/leatherman)\n    ...\n\n### Variables Set by Leatherman\n\nLeatherman sets two top-level CMake variables:\n\n* `LEATHERMAN_INCLUDE_DIRS` The include paths of all enabled\n  leatherman libraries\n* `LEATHERMAN_LIBRARIES` The library names of all enabled leatherman\n  libraries, as well as their dependencies.\n\nIn addition, each enabled library sets a number of library-specific\nvariables:\n\n* `LEATHERMAN_\u003cLIBRARY\u003e_INCLUDE` The include directory or directories\n  for the given leatherman library.\n* `LEATHERMAN_\u003cLIBRARY\u003e_LIB` The library name as used by CMake. In the\n  case of header-only leatherman libraries, this will be set to the\n  empty string.\n* `LEATHERMAN_\u003cLIBRARY\u003e_DEPS` Any dependency libraries needed by the\n  given library. This could include other leatherman libraries or\n  3rd-party libraries found via CMake.\n* `LEATHERMAN_\u003cLIBRARY\u003e_LIBS` The contents of both\n  `LEATHERMAN_\u003cLIBRARY\u003e_LIB` and `LEATHERMAN_\u003cLIBRARY\u003e_DEPS`\n\n### CMake Helpers Provided by Leatherman\n\nIn addition to the C++ library components, Leatherman provides a few\nCMake helpers. These will be automatically added to your\n`CMAKE_MODULE_PATH` when `find_package` is processed.\n\n* `options`: Common CMake options for leatherman features. Should\n  almost always be used.\n* `cflags`: Sets a `LEATHERMAN_CXX_FLAGS` variable containing the\n  Puppet Labs standard CXXFLAGS for your compiler and platform.\n\n* `leatherman`: Additional functionality provided by Leatherman for\n  consumers. Includes:\n  * Helpers for dealing with variables and scopes\n  * Debugging macros\n  * `cpplint` and `cppcheck` configuration\n  * Logging configuration\n  * Install command with cross-platform defaults\n  * Symbol visibility configuration\n\n* `pod2man`: Adds a `pod2man` macro to generate man files from source.\n\n### Internationalization (i18n)\n\nLeatherman and its components provide support for generating and using\n`gettext`-based message catalogs.\n\n#### Helper Functions\n\nTwo helpers are provided for generating message catalogs:\n\n* `gettext_templates \u003cdir\u003e \u003csources\u003e`: creates a `${PROJECT_NAME}.pot`\n  target (used by `all`) that (re)generates the .pot file from specified\n  source files. If the project is configured with `LEATHERMAN_LOCALES`\n  containing a list of language codes, it will add a target\n  `${PROJECT_NAME}-${LANG}.po` to create or update translation (.po)\n  files matching those codes. Files are put in `dir`. To avoid `make\n  clean` deleting these files, look at how the `locales` directory is\n  structured.\n* `gettext_compile \u003cdir\u003e \u003cinst\u003e`: creates a `translation` target (also\n  used by `all`) to generate the binary message catalogs (.mo files) and\n  configure installing them to the specified install location (`inst`).\n\n`LEATHERMAN_LOCALES` expects a quoted semi-colon separated list, as\nin `LEATHERMAN_LOCALES=\"en;fr;ja\"`.\n\nNormal use of cmake/make should ensure the translation files are up-to-\ndate. Translations can be tested by setting the `LC_CTYPE` environment\nvariable.\n\n#### Enabling i18n\n\nBy default i18n support is disabled. To enable it, define `LEATHERMAN_I18N`\nwhen compiling your project. To do so, add these two lines to your projects\nCMakeLists.txt file below where you have `find_package(LEATHERMAN ...)` and\nalso below where you do `include(cflags)`.\n\n```\nadd_definitions(${LEATHERMAN_DEFINITIONS})\nadd_definitions(-DLEATHERMAN_I18N)\n```\n\nBy default locale files are installed to `${CMAKE_INSTALL_PREFIX}/share/locale`.\nThis behavior can be changed to use environment variables for the prefix\ninstead by defining `LEATHERMAN_LOCALE_VAR` and `LEATHERMAN_LOCALE_INSTALL`.\n`LEATHERMAN_LOCALE_VAR` should refer to an environment variable pointing to the\nroot of the Leatherman install, while `LEATHERMAN_LOCALE_INSTALL` should contain\na path relative to that location, where locale files should be installed and searched\nfor at run time.\n\nFor example, if Leatherman is installed to `C:/tools`, and you would like\nto install translation files to `C:/languages/leatherman`, you can create an environment\nvariable (e.g. `$LEATHERMAN_LOCATION`) containing `C:\\tools`, then set\n`LEATHERMAN_LOCALE_VAR=LEATHERMAN_LOCATION` and \n`LEATHERMAN_LOCALE_INSTALL=../languages/leatherman`. Then locale files will be installed to\n`C:/tools/../languages/leatherman` and at runtime Leatherman will search for locale\nfiles there.\n\nTo ensure that consuming projects also install their locale files to the right location,\nit is recommended to set `LEATHERMAN_LOCALE_INSTALL` for all projects attempting to use\nLeatherman's i18n tooling.\n\n#### Extracting and Translating Text\n\nThe format strings in logging (the first argument) will automatically be\nextracted for the translation template file and translated. Substitution\narguments will not, and must be explicitly translated.\n\nTo translate strings outside of logging, use the `leatherman::locale::translate`\nand `leatherman::locale::format` helpers. Strings passed to the helpers will be\nextracted to .po files. There are several versions of these helpers:\n\n* Basic version (`translate`, `format`) for most standard translations.\n```\ntranslate(\"Apple\");\n```\n* Pluralized (`translate_n`, `format_n`) when translation depends on number of items.\n```\n// Note the parameter duplication: The first count value `2` selects the appropriate\n// translated message, and the second `2` fills in the `{1}` substitution token.\nformat_n(\"{1} Apple\", \"{1} Apples\", 2, 2);\n```\n* Prefixed-context (`translate_p`, `format_p`) when a word or phrase has multiple meanings.\n```\ntranslate_p(\"Fruit\", \"Apple\")\n```\n* Pluralized and prefixed-context (`translate_np`, `format_np`)\n```\nformat_np(\"Fruit\", \"{1} Apple\", \"{1} Apples\", 3, 3);\n```\n\n`leatherman::locale::format` is a replacement for\n[`boost::locale::format`](http://www.boost.org/doc/libs/1_58_0/libs/locale/doc/html/localized_text_formatting.html),\nwhich adds locale-aware formatting to `boost::format`, but requires\ndifferent substitution tokens. To support transparently enabling\n`LEATHERMAN_I18N` for only some platforms in a project,\n`leatherman::locale::format` falls-back to using `boost::format`, and\nwill convert substitution tokens using the regex `{(\\d+)}` to `%\\1%`.\nTo be safe, assume both formats are special when using `format`, and\nuse `{N}` in as the substitution token for your strings. If you need to\nsupport both modes and use advanced substitution strings, you'll have\nto use an `#ifdef LEATHERMAN_I18N` block to use the correct string.\n\nTo use `leatherman::locale::translate` or `leatherman::locale::format`\nin your project, add an include to the top of your cpp file:\n\n```\n#include \u003cleatherman/locale/locale.hpp\u003e\n```\n\nNext, if you would like to use any of the functions, you could do so\nby following this example:\n\n```\nstd::cout \u003c\u003c leatherman::locale::translate(\"This is translated\") \u003c\u003c std::endl;\nstd::cout \u003c\u003c leatherman::locale::format(\"This is {1} translated message\", 1) \u003c\u003c std::endl;\n```\n\nLeatherman also provides format helpers with short names: _(), n_(), p_(), np_().\nThese reduce code disruption when adding i18n support, and naming is consistent with\nmacros from other i18n libraries.\n\n```\nusing namespace leatherman::locale;\nstd::cout \u003c\u003c _(\"This is translated\") \u003c\u003c std::endl;\nstd::cout \u003c\u003c _(\"This is {1} translated message\", 1) \u003c\u003c std::endl;\n```\n\n#### Limitations\n\nNote that on Windows when building Leatherman.Locale as a DLL and\nBoost.Locale statically, you can get some weird behavior from Boost.Locale.\nAvoid using it directly, and ensure all translation operations happen\nas part of the Leatherman.Locale DLL memory space (i.e. in source files).\n\nTranslation isn't supported on AIX or Solaris, as GCC on those platforms\ndoesn't support `std::locale`. In fact std::locale is buggy, so avoid\nusing `get_locale` as well. The CMake option `LEATHERMAN_USE_LOCALES`\ncan be used to enable or disable building with Boost.Locale and using\n`std::locale`.\n\n#### Debugging\n\nIf output strings are not being translated, [gettext's FAQ](https://www.gnu.org/software/gettext/FAQ.html#integrating_noop)\nhas some suggestions for debugging.\n\u003e\u003e\u003e\u003e\u003e\u003e\u003e (maint) Add debugging i18n to README\n\n### Using Logging\n\nEach `.cc` file that uses logging (or includes a header which uses\nlogging) needs to know its logging namespace. This can be set by\ndefining `LEATHERMAN_LOGGING_NAMESPACE` to a string such as\n\"leatherman.logging\" or \"puppetlabs.facter\".\n\nSince typically a large number of files at once will need to use the\nsame logging namespace, leatherman provides a CMake macro to set it\nglobally. This can be used as follows:\n\n    ...\n    include(leatherman)\n    leatherman_logging_namespace(\"logging.namespace\")\n    ...\n\nInitializing logging via setup\\_logging will configure the ostream\nfor the default UTF-8 locale (or the specified locale).\n\n### Using Catch\n\nSince [Catch][1] is a testing-only utility, its include directory is\nexcluded from LEATHERMAN\\_INCLUDE\\_DIRS. To use Catch, explicitly add\n\n    include_directories(${LEATHERMAN_CATCH_INCLUDE})\n\nto the CMakeLists.txt file of your testing directory.\n\n### Using Windows\n\nIn order to use the Windows libraries, Logging must be set up.\n\n### Using JsonContainer\n\nTo use JsonContainer, you must enable [RapidJSON][2] that is included\nas a leatherman component.\nPlease refer to the [JsonContainer documentation][3] for API details.\n\n### Using curl\n\nTo use the curl wrapper library, libcurl must be installed.\n\nOn Ubuntu use the following:\n\n    apt-get install libcurl4-openssl-dev\n    \nOn Windows, in Powershell, use:\n\n    (New-Object net.webclient).DownloadFile(\"http://curl.haxx.se/download/curl-7.42.1.zip\", \"C:\\tools\\curl-7.42.1.zip\")\n    \u0026 7za x \"curl-7.42.1.zip\" | FIND /V \"ing \"\n    cd curl-7.42.1\n    mkdir -Path C:\\tools\\curl-7.42.1-x86_64_mingw-w64_4.8.4_win32_seh\\include\n    cp -r include\\curl C:\\tools\\curl-7.42.1-x86_64_mingw-w64_4.8.4_win32_seh\\include\n    mkdir -Path C:\\tools\\curl-7.42.1-x86_64_mingw-w64_4.8.4_win32_seh\\lib\n    cp lib\\libcurl.a C:\\tools\\curl-7.42.1-x86_64_mingw-w64_4.8.4_win32_seh\\lib\n    \nOn Windows CMake must also be manually pointed to the correct directory by passing the argument \n`-DCMAKE_PREFIX_PATH=\"C:\\tools\\curl-7.42.1-x86_64_mingw-w64_4.8.4_win32_seh`.\n\n## Extending Leatherman\n\nAdding a new library to leatherman is easy!\n\n* Add a new subdirectory with the name of your library\n* Add an appropriate `add_leatherman_dir` invocation to the top-level\n  `CMakeLists.txt`\n* Fill in the headers, sources, and tests of your library. The typical\n  directory structure is below.\n\nThe `CmakeLists.txt` file for a library is used both at build time and\nduring a `find_package` call for Leatherman. This allows library\ndependencies to be handled identically during both build and find\noperations. Because of this, certain build configuration settings\nmight need to be gated on a check for `BUILDING_LEATHERMAN`. See the\n`logging` library for an example of how this is done.\n\n### Typical Leatherman Directory Structure\n\n    leatherman/\n        libname/\n            CMakeLists.txt\n            src/\n                srcfile.cc\n            inc/leatherman/\n                header.hpp\n            tests/\n                testfile.cc\n\n### Sample Library CMakeLists.txt file\n\n    add_leatherman_library(\"src/srcfile.cc\")\n    add_leatherman_test(\"tests/testfile.cc\")\n    add_leatherman_headers(\"inc/leatherman\")\n\nMore complex libraries may have dependencies. See the `locale` library\nfor a simple example of how dependencies are handled by leatherman\nlibraries.\n\n### Vendoring Other Libraries\n\nSometimes it's necessary to vendor a 3rd-party library in\nLeatherman. In these cases the standard Leatherman macros probably\nwon't help you, and you'll need to write a lower-level CMake\nfile. This README can't cover all the possible situations here, but\nthe `nowide` and `catch` CMake files are both solid examples.\n\n## How To Release\n\n1. Update [CHANGELOG.md](CHANGELOG.md) with release notes based on\n``git log `git describe --abbrev=0 --tags`..HEAD``\n1. Update the version in the project declaration of [CMakeLists.txt](CMakeLists.txt)\n1. Build with gettext to ensure translations are up-to-date\n1. `git tag -s \u003cversion\u003e -m '\u003cversion\u003e' \u0026\u0026 git push \u003cpuppetlabs\u003e refs/tags/\u003cversion\u003e`\n1. Send out an announcement e-mail\n\n[1]: https://github.com/philsquared/Catch\n[2]: https://github.com/miloyip/rapidjson\n[3]: json_container/README.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fleatherman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fleatherman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fleatherman/lists"}