From cb3f4fafeba98d9905fc2ca8c5dbc2b314d9d731 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 21:22:24 +0200 Subject: [PATCH 01/12] More gitignore Signed-off-by: Cristian Le --- .gitignore | 163 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 161 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index aceaf81..f20262d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,165 @@ build*/ *.sw? cmake-build-* -venv -env compile_commands.json + +### Python template +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/#use-with-ide +.pdm.toml + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +.idea/ + +### Project specific +CMakeUserPresets.json From 57b2f95e27a71610b438abf3db70551493b3106d Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 21:25:15 +0200 Subject: [PATCH 02/12] Add basic pyproject.toml for dev and docs Signed-off-by: Cristian Le --- pyproject.toml | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 pyproject.toml diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..f9b1eab --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,24 @@ +[build-system] +requires = ["setuptools"] +build-backend = "setuptools.build_meta" + +[project] +name = "json-schema-validator-dev" +version = "0.0.0" +description = "Development environment json-schenma-validator" +readme = "README.md" +license = { file = "LICENSE" } + + +[project.optional-dependencies] +docs = [ + "sphinx >= 6.0", + "sphinx-rtd-theme", + "myst-parser", +] +dev = [ + "pre-commit", +] + +[tool.setuptools] +packages = [] From eee03c0f081db59688ee965039b09804a2491d71 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 21:30:05 +0200 Subject: [PATCH 03/12] Remove dead travis badge Signed-off-by: Cristian Le --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index e9b80ed..5d50806 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ -[![Build Status](https://travis-ci.org/pboettch/json-schema-validator.svg?branch=master)](https://travis-ci.org/pboettch/json-schema-validator) - # JSON schema validator for JSON for Modern C++ # What is it? From e306d7905e8d2c6bcbffba8c1ea877af4adb8e78 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 21:34:29 +0200 Subject: [PATCH 04/12] Bump header levels Signed-off-by: Cristian Le --- README.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 5d50806..0b84f1d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # JSON schema validator for JSON for Modern C++ -# What is it? +## What is it? This is a C++ library for validating JSON documents based on a [JSON Schema](http://json-schema.org/) which itself should validate with @@ -16,7 +16,7 @@ library, hence the name. External documentation is missing as well. However the API of the validator is rather simple. -# New in version 2 +## New in version 2 Although significant changes have been done for the 2nd version (a complete rewrite) the API is compatible with the 1.0.0 release. Except for @@ -31,7 +31,7 @@ is parsed into compiled C++ objects which are then used during validation. There still optimizations to be done, but validation speed has improved by factor 100 or more. -# Design goals +## Design goals The main goal of this validator is to produce *human-comprehensible* error messages if a JSON-document/instance does not comply to its schema. @@ -46,7 +46,7 @@ a validation error occurs and decide what to do (throwing, counting, collecting) Another goal was to use Niels Lohmann's JSON-library. This is why the validator lives in his namespace. -# Thread-safety +## Thread-safety Instance validation is thread-safe and the same validator-object can be used by different threads: @@ -61,13 +61,13 @@ being called: Validator-object creation however is not thread-safe. A validator has to be created in one (main?) thread once. -# Weaknesses +## Weaknesses Numerical validation uses nlohmann-json's integer, unsigned and floating point types, depending on if the schema type is "integer" or "number". Bignum (i.e. arbitrary precision and range) is not supported at this time. -# Building +## Building This library is based on Niels Lohmann's JSON-library and thus has a build-dependency to it. @@ -77,7 +77,7 @@ is required. Various methods using CMake can be used to build this project. -## Build out-of-source +### Build out-of-source Do not run cmake inside the source-dir. Rather create a dedicated build-dir: @@ -92,7 +92,7 @@ make install # if needed ctest # run unit, non-regression and test-suite tests ``` -## Building as shared library +### Building as shared library By default a static library is built. Shared libraries can be generated by using the `BUILD_SHARED_LIBS`-cmake variable: @@ -103,14 +103,14 @@ In your initial call to cmake simply add: cmake [..] -DBUILD_SHARED_LIBS=ON [..] ``` -## nlohmann-json integration +### nlohmann-json integration As nlohmann-json is a dependency, this library tries find it. The cmake-configuration first checks if nlohmann-json is available as a cmake-target. This may be the case, because it is used as a submodule in a super-project which already provides and uses nlohmann-json. Otherwise, it calls `find_package` for nlohmann-json and requires nlohmann-json to be installed on the system. -### Building with Hunter package manager +#### Building with Hunter package manager To enable access to nlohmann json library, Hunter can be used. Just run with `JSON_VALIDATOR_HUNTER=ON` option. No further dependencies needed @@ -118,14 +118,14 @@ To enable access to nlohmann json library, Hunter can be used. Just run with `JS cmake [..] -DJSON_VALIDATOR_HUNTER=ON [..] ``` -### Building as a CMake-subdirectory from within another project +#### Building as a CMake-subdirectory from within another project Adding this library as a subdirectory to a parent project is one way of building it. If the parent project already used `find_package()` to find the CMake-package of nlohmann_json or includes it as a submodule likewise. -### Building directly, finding a CMake-package. (short) +#### Building directly, finding a CMake-package. (short) When nlohmann-json has been installed, it provides files which allows CMake's `find_package()` to be used. @@ -133,7 +133,7 @@ CMake's `find_package()` to be used. This library is using this mechanism if `nlohmann_json::nlohmann_json`-target does not exist. -### Install +#### Install Since version 2.1.0 this library can be installed and CMake-package-files will be created accordingly. If the installation of nlohmann-json and this library @@ -152,7 +152,7 @@ target_link_libraries( [..] nlohmann_json_schema_validator) to build and link. -## Code +### Code See also `app/json-schema-validate.cpp`. @@ -250,7 +250,7 @@ int main() } ``` -# Compliance +## Compliance There is an application which can be used for testing the validator with the [JSON-Schema-Test-Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite). @@ -261,7 +261,7 @@ cmake-variable `JSON_SCHEMA_TEST_SUITE_PATH` will enable the test-target(s). All required tests are **OK**. -# Format +## Format Optionally JSON-schema-validator can validate predefined or user-defined formats. Therefore a format-checker-function can be provided by the user which is called by @@ -285,7 +285,7 @@ json_validator validator(nullptr, // or loader-callback my_format_checker); // create validator ``` -## Default Checker +### Default Checker The library contains a default-checker, which does some checks. It needs to be provided manually to the constructor of the validator: @@ -299,7 +299,7 @@ Supported formats: `date-time, date, time, email, hostname, ipv4, ipv6, uuid, re More formats can be added in `src/string-format-check.cpp`. Please contribute implementions for missing json schema draft formats. -## Default value processing +### Default value processing As a result of the validation, the library returns a json patch including the default values of the specified schema. @@ -353,7 +353,7 @@ The example above will output the specified default values `{"height":10,"width" > Note that the default value specified in a `$ref` may be overridden by the current instance location. Also note that this behavior will break draft-7, but it is compliant to newer drafts (e.g. `2019-09` or `2020-12`). -# Contributing +## Contributing This project uses [`pre-commit`](https://pre-commit.com/) to enforce style-checks. Please install and run it before creating commits and making pull requests. From d73a2f02a7f1bd672ac45b32219145e2137156a7 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 21:37:34 +0200 Subject: [PATCH 05/12] Add basic sphinx/rtd framework Signed-off-by: Cristian Le --- .readthedocs.yaml | 13 +++++++++++++ README.md | 4 ++++ docs/conf.py | 26 ++++++++++++++++++++++++++ docs/index.md | 8 ++++++++ 4 files changed, 51 insertions(+) create mode 100644 .readthedocs.yaml create mode 100644 docs/conf.py create mode 100644 docs/index.md diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..3103d54 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +python: + install: + - path: . + extra_requirements: + - docs +build: + os: ubuntu-22.04 + tools: + python: "3.11" +sphinx: + configuration: docs/conf.py diff --git a/README.md b/README.md index 0b84f1d..d418536 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ ## What is it? + + This is a C++ library for validating JSON documents based on a [JSON Schema](http://json-schema.org/) which itself should validate with [draft-7 of JSON Schema Validation](http://json-schema.org/schema). @@ -362,3 +364,5 @@ creating commits and making pull requests. $ pip install pre-commit $ pre-commit install ``` + + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..2d8add9 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,26 @@ +project = 'Json Schema Validator' +copyright = '2023, Patrick Boettcher' +author = 'Patrick Boettcher' + +extensions = [ + "myst_parser", +] + +templates_path = [] +exclude_patterns = [ + 'build', + '_build', + 'Thumbs.db', + '.DS_Store', + "README.md", +] +source_suffix = [".md"] + + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] + +myst_enable_extensions = [ + "tasklist", + "colon_fence", +] diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..2bd6894 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,8 @@ +# Json-Schema-Validator + +:::{include} ../README.md +--- +start-after: +end-before: +--- +::: From fbbf5343f9fbc46889ff65aed0fc1b7aea069247 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 21:56:16 +0200 Subject: [PATCH 06/12] Add pre-commit for sphinx/myst Signed-off-by: Cristian Le --- .pre-commit-config.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2eaa1a1..aab9b05 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -26,6 +26,18 @@ repos: additional_dependencies: - mdformat-gfm - mdformat-tables + exclude: docs\/.* + - repo: https://github.com/executablebooks/mdformat + # TODO: Temporarily separate docs formatiing + # https://github.com/executablebooks/mdformat/issues/234 + # TODO: Disabled due to lack of colon-fence support + rev: 0.7.16 + hooks: + - id: mdformat + stages: [ manual ] + additional_dependencies: + - mdformat-myst + files: doc\/(?!README).*\.md$ - repo: https://github.com/python-jsonschema/check-jsonschema rev: 0.23.0 hooks: From 25a5d09861c9102a88c6fcd3ae846a718feeef3c Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 21:56:50 +0200 Subject: [PATCH 07/12] Move Contributing section Signed-off-by: Cristian Le --- README.md | 10 ---------- docs/CONTRIBUTING.md | 15 +++++++++++++++ docs/index.md | 11 +++++++++++ 3 files changed, 26 insertions(+), 10 deletions(-) create mode 100644 docs/CONTRIBUTING.md diff --git a/README.md b/README.md index d418536..3383cce 100644 --- a/README.md +++ b/README.md @@ -355,14 +355,4 @@ The example above will output the specified default values `{"height":10,"width" > Note that the default value specified in a `$ref` may be overridden by the current instance location. Also note that this behavior will break draft-7, but it is compliant to newer drafts (e.g. `2019-09` or `2020-12`). -## Contributing - -This project uses [`pre-commit`](https://pre-commit.com/) to enforce style-checks. Please install and run it before -creating commits and making pull requests. - -```console -$ pip install pre-commit -$ pre-commit install -``` - diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..e14b622 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,15 @@ +# Contributing Guidelines + +Pull request are more than welcome on the +[GitHub page](https://github.com/pboettch/json-schema-validator). + +## Development environment + +This project uses [`pre-commit`](https://pre-commit.com/) to enforce style-checks. +These checks are enforced in the GitHub Actions, but it is encouraged to install +a development environment locally as well. + +```console +$ pip install -e .[dev] +$ pre-commit install +``` diff --git a/docs/index.md b/docs/index.md index 2bd6894..2c06ce8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,16 @@ # Json-Schema-Validator +:::{toctree} +--- +maxdepth: 2 +titlesonly: true +caption: Contents +glob: true +hidden: true +--- +CONTRIBUTING +::: + :::{include} ../README.md --- start-after: From 02d11f1cda664c7ee06fa7644d56d890eee3f314 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 22:03:36 +0200 Subject: [PATCH 08/12] Standardize documentation format Signed-off-by: Cristian Le --- README.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/README.md b/README.md index 3383cce..d03c456 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # JSON schema validator for JSON for Modern C++ -## What is it? - This is a C++ library for validating JSON documents based on a @@ -15,9 +13,6 @@ Niels Lohmann et al develop a great JSON parser for C++ called [JSON for Modern C++](https://github.com/nlohmann/json). This validator is based on this library, hence the name. -External documentation is missing as well. However the API of the validator -is rather simple. - ## New in version 2 Although significant changes have been done for the 2nd version From ad3858908f9239ea589edbcc312ba2fb2aad5a3f Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 22:16:32 +0200 Subject: [PATCH 09/12] Move version difference to changelog Signed-off-by: Cristian Le --- README.md | 15 --------------- docs/changelog.md | 16 ++++++++++++++++ docs/index.md | 1 + 3 files changed, 17 insertions(+), 15 deletions(-) create mode 100644 docs/changelog.md diff --git a/README.md b/README.md index d03c456..6088723 100644 --- a/README.md +++ b/README.md @@ -13,21 +13,6 @@ Niels Lohmann et al develop a great JSON parser for C++ called [JSON for Modern C++](https://github.com/nlohmann/json). This validator is based on this library, hence the name. -## New in version 2 - -Although significant changes have been done for the 2nd version -(a complete rewrite) the API is compatible with the 1.0.0 release. Except for -the namespace which is now `nlohmann::json_schema`. - -Version **2** supports JSON schema draft 7, whereas 1 was supporting draft 4 -only. Please update your schemas. - -The primary change in 2 is the way a schema is used. While in version 1 the schema was -kept as a JSON-document and used again and again during validation, in version 2 the schema -is parsed into compiled C++ objects which are then used during validation. There are surely -still optimizations to be done, but validation speed has improved by factor 100 -or more. - ## Design goals The main goal of this validator is to produce *human-comprehensible* error diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..b0c7ba8 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,16 @@ +# Changelog + +## New in version 2 + +Although significant changes have been done for the 2nd version +(a complete rewrite) the API is compatible with the 1.0.0 release. Except for +the namespace which is now `nlohmann::json_schema`. + +Version **2** supports JSON schema draft 7, whereas 1 was supporting draft 4 +only. Please update your schemas. + +The primary change in 2 is the way a schema is used. While in version 1 the schema was +kept as a JSON-document and used again and again during validation, in version 2 the schema +is parsed into compiled C++ objects which are then used during validation. There are surely +still optimizations to be done, but validation speed has improved by factor 100 +or more. diff --git a/docs/index.md b/docs/index.md index 2c06ce8..ef50137 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,6 +9,7 @@ glob: true hidden: true --- CONTRIBUTING +changelog ::: :::{include} ../README.md From 57a4172ee84ef0121b1944658dbddefa8c6de20e Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 22:18:43 +0200 Subject: [PATCH 10/12] Move design details to roadmap Signed-off-by: Cristian Le --- README.md | 36 ------------------------------------ docs/index.md | 1 + docs/roadmap.md | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 38 insertions(+), 36 deletions(-) create mode 100644 docs/roadmap.md diff --git a/README.md b/README.md index 6088723..79d0d4c 100644 --- a/README.md +++ b/README.md @@ -13,42 +13,6 @@ Niels Lohmann et al develop a great JSON parser for C++ called [JSON for Modern C++](https://github.com/nlohmann/json). This validator is based on this library, hence the name. -## Design goals - -The main goal of this validator is to produce *human-comprehensible* error -messages if a JSON-document/instance does not comply to its schema. - -By default this is done with exceptions thrown at the users with a helpful -message telling what's wrong with the document while validating. - -Starting with **2.0.0** the user can pass a `json_schema::basic_error_handler`-derived -object along with the instance to validate to receive a callback each time -a validation error occurs and decide what to do (throwing, counting, collecting). - -Another goal was to use Niels Lohmann's JSON-library. This is why the validator -lives in his namespace. - -## Thread-safety - -Instance validation is thread-safe and the same validator-object can be used by -different threads: - -The validate method is `const` which indicates the object is not modified when -being called: - -```C++ - json json_validator::validate(const json &) const; -``` - -Validator-object creation however is not thread-safe. A validator has to be -created in one (main?) thread once. - -## Weaknesses - -Numerical validation uses nlohmann-json's integer, unsigned and floating point -types, depending on if the schema type is "integer" or "number". Bignum -(i.e. arbitrary precision and range) is not supported at this time. - ## Building This library is based on Niels Lohmann's JSON-library and thus has diff --git a/docs/index.md b/docs/index.md index ef50137..dfa05c5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,6 +10,7 @@ hidden: true --- CONTRIBUTING changelog +roadmap ::: :::{include} ../README.md diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..5af0441 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,37 @@ +# Roadmap + +## Design goals + +The main goal of this validator is to produce *human-comprehensible* error +messages if a JSON-document/instance does not comply to its schema. + +By default this is done with exceptions thrown at the users with a helpful +message telling what's wrong with the document while validating. + +Starting with **2.0.0** the user can pass a `json_schema::basic_error_handler`-derived +object along with the instance to validate to receive a callback each time +a validation error occurs and decide what to do (throwing, counting, collecting). + +Another goal was to use Niels Lohmann's JSON-library. This is why the validator +lives in his namespace. + +## Thread-safety + +Instance validation is thread-safe and the same validator-object can be used by +different threads: + +The validate method is `const` which indicates the object is not modified when +being called: + +```C++ + json json_validator::validate(const json &) const; +``` + +Validator-object creation however is not thread-safe. A validator has to be +created in one (main?) thread once. + +## Weaknesses + +Numerical validation uses nlohmann-json's integer, unsigned and floating point +types, depending on if the schema type is "integer" or "number". Bignum +(i.e. arbitrary precision and range) is not supported at this time. From f5d730fb66f3f044e5855466710b88ec324f3898 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 22:40:09 +0200 Subject: [PATCH 11/12] Simplify cmake documentation Signed-off-by: Cristian Le --- README.md | 97 ++++++++++++--------------------------------- docs/cmake/index.md | 16 ++++++++ docs/index.md | 3 +- 3 files changed, 43 insertions(+), 73 deletions(-) create mode 100644 docs/cmake/index.md diff --git a/README.md b/README.md index 79d0d4c..5794d2a 100644 --- a/README.md +++ b/README.md @@ -13,92 +13,47 @@ Niels Lohmann et al develop a great JSON parser for C++ called [JSON for Modern C++](https://github.com/nlohmann/json). This validator is based on this library, hence the name. -## Building +## Getting started -This library is based on Niels Lohmann's JSON-library and thus has -a build-dependency to it. +Currently, this package only offers a C++ library interface, and is only +available via cmake's `FetchContent` and conan. It is highly recommended +to use cmake to link to this library -Currently at least version **3.6.0** of NLohmann's JSON library -is required. +Dependencies: -Various methods using CMake can be used to build this project. +- NLohmann's Json library: At least **3.6.0** + (See Github actions for officially tested versions) -### Build out-of-source +### CMake configuration -Do not run cmake inside the source-dir. Rather create a dedicated build-dir: + -```Bash -git clone https://github.com/pboettch/json-schema-validator.git -cd json-schema-validator -mkdir build -cd build -cmake [..] -make -make install # if needed -ctest # run unit, non-regression and test-suite tests -``` - -### Building as shared library - -By default a static library is built. Shared libraries can be generated by using -the `BUILD_SHARED_LIBS`-cmake variable: - -In your initial call to cmake simply add: - -```bash -cmake [..] -DBUILD_SHARED_LIBS=ON [..] -``` - -### nlohmann-json integration +Bellow is a minimum cmake configuration file using `FetchContent`: -As nlohmann-json is a dependency, this library tries find it. +```cmake +cmake_minimum_required(VERSION 3.11) -The cmake-configuration first checks if nlohmann-json is available as a cmake-target. This may be the case, because it is used as a submodule in a super-project which already provides and uses nlohmann-json. -Otherwise, it calls `find_package` for nlohmann-json and requires nlohmann-json to be installed on the system. +project(example) -#### Building with Hunter package manager +include(FetchContent) -To enable access to nlohmann json library, Hunter can be used. Just run with `JSON_VALIDATOR_HUNTER=ON` option. No further dependencies needed +FetchContent_Declare(nlohmann_json_schema_validator + GIT_REPOSITORY pboettch/json-schema-validator + # Please use a specific version tag + GIT_TAG main + ) +FetchContent_MakeAvailable(nlohmann_json_schema_validator) -```bash -cmake [..] -DJSON_VALIDATOR_HUNTER=ON [..] +add_executable(example main.cpp) +target_link_libraries(example PRIVATE nlohmann_json_schema_validator::validator) ``` -#### Building as a CMake-subdirectory from within another project - -Adding this library as a subdirectory to a parent project is one way of -building it. - -If the parent project already used `find_package()` to find the CMake-package of nlohmann_json or includes it as a submodule likewise. - -#### Building directly, finding a CMake-package. (short) - -When nlohmann-json has been installed, it provides files which allows -CMake's `find_package()` to be used. - -This library is using this mechanism if `nlohmann_json::nlohmann_json`-target -does not exist. - -#### Install - -Since version 2.1.0 this library can be installed and CMake-package-files will be -created accordingly. If the installation of nlohmann-json and this library -is done into default unix-system-paths CMake will be able to find this -library by simply doing: - -```CMake -find_package(nlohmann_json_schema_validator REQUIRED) -``` - -and - -```CMake -target_link_libraries( [..] nlohmann_json_schema_validator) -``` + -to build and link. +For more details about the available cmake options and recommended configurations +see [docs/cmake](docs/cmake/index.md) -### Code +### Api example See also `app/json-schema-validate.cpp`. diff --git a/docs/cmake/index.md b/docs/cmake/index.md new file mode 100644 index 0000000..99113ad --- /dev/null +++ b/docs/cmake/index.md @@ -0,0 +1,16 @@ +# CMake configuration guide + +:::{toctree} +--- +maxdepth: 2 +glob: true +hidden: true +--- +::: + +:::{include} ../../README.md +--- +start-after: +end-before: +--- +::: diff --git a/docs/index.md b/docs/index.md index dfa05c5..8ae5565 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,14 +3,13 @@ :::{toctree} --- maxdepth: 2 -titlesonly: true -caption: Contents glob: true hidden: true --- CONTRIBUTING changelog roadmap +cmake/index.md ::: :::{include} ../README.md From 3e44edf330d6db38ba31d430ee49707e67b28629 Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Sun, 9 Jul 2023 22:46:18 +0200 Subject: [PATCH 12/12] Add basic cmake documentation structure Signed-off-by: Cristian Le --- docs/cmake/advanced.md | 3 +++ docs/cmake/options.md | 5 +++++ docs/cmake/presets.md | 5 +++++ 3 files changed, 13 insertions(+) create mode 100644 docs/cmake/advanced.md create mode 100644 docs/cmake/options.md create mode 100644 docs/cmake/presets.md diff --git a/docs/cmake/advanced.md b/docs/cmake/advanced.md new file mode 100644 index 0000000..a380e32 --- /dev/null +++ b/docs/cmake/advanced.md @@ -0,0 +1,3 @@ +# Advanced usage + +## Working with `FetchCotent` diff --git a/docs/cmake/options.md b/docs/cmake/options.md new file mode 100644 index 0000000..1c6c9ac --- /dev/null +++ b/docs/cmake/options.md @@ -0,0 +1,5 @@ +# Configuration options + +## Available options + +## Working with CMake options diff --git a/docs/cmake/presets.md b/docs/cmake/presets.md new file mode 100644 index 0000000..ec06b7c --- /dev/null +++ b/docs/cmake/presets.md @@ -0,0 +1,5 @@ +# CMake Presets + +## Available presets + +## Working with presets