1*44844408SAndroid Build Coastguard Worker# Contributing to JsonCpp 2*44844408SAndroid Build Coastguard Worker 3*44844408SAndroid Build Coastguard Worker## Building 4*44844408SAndroid Build Coastguard Worker 5*44844408SAndroid Build Coastguard WorkerBoth CMake and Meson tools are capable of generating a variety of build environments for you preferred development environment. 6*44844408SAndroid Build Coastguard WorkerUsing cmake or meson you can generate an XCode, Visual Studio, Unix Makefile, Ninja, or other environment that fits your needs. 7*44844408SAndroid Build Coastguard Worker 8*44844408SAndroid Build Coastguard WorkerAn example of a common Meson/Ninja environment is described next. 9*44844408SAndroid Build Coastguard Worker 10*44844408SAndroid Build Coastguard Worker## Building and testing with Meson/Ninja 11*44844408SAndroid Build Coastguard WorkerThanks to David Seifert (@SoapGentoo), we (the maintainers) now use 12*44844408SAndroid Build Coastguard Worker[meson](http://mesonbuild.com/) and [ninja](https://ninja-build.org/) to build 13*44844408SAndroid Build Coastguard Workerfor debugging, as well as for continuous integration (see 14*44844408SAndroid Build Coastguard Worker[`./.travis_scripts/meson_builder.sh`](./.travis_scripts/meson_builder.sh) ). Other systems may work, but minor 15*44844408SAndroid Build Coastguard Workerthings like version strings might break. 16*44844408SAndroid Build Coastguard Worker 17*44844408SAndroid Build Coastguard WorkerFirst, install both meson (which requires Python3) and ninja. 18*44844408SAndroid Build Coastguard WorkerIf you wish to install to a directory other than /usr/local, set an environment variable called DESTDIR with the desired path: 19*44844408SAndroid Build Coastguard Worker DESTDIR=/path/to/install/dir 20*44844408SAndroid Build Coastguard Worker 21*44844408SAndroid Build Coastguard WorkerThen, 22*44844408SAndroid Build Coastguard Worker```sh 23*44844408SAndroid Build Coastguard Worker cd jsoncpp/ 24*44844408SAndroid Build Coastguard Worker BUILD_TYPE=debug 25*44844408SAndroid Build Coastguard Worker #BUILD_TYPE=release 26*44844408SAndroid Build Coastguard Worker LIB_TYPE=shared 27*44844408SAndroid Build Coastguard Worker #LIB_TYPE=static 28*44844408SAndroid Build Coastguard Worker meson --buildtype ${BUILD_TYPE} --default-library ${LIB_TYPE} . build-${LIB_TYPE} 29*44844408SAndroid Build Coastguard Worker ninja -v -C build-${LIB_TYPE} 30*44844408SAndroid Build Coastguard Worker 31*44844408SAndroid Build Coastguard Worker ninja -C build-static/ test 32*44844408SAndroid Build Coastguard Worker 33*44844408SAndroid Build Coastguard Worker # Or 34*44844408SAndroid Build Coastguard Worker #cd build-${LIB_TYPE} 35*44844408SAndroid Build Coastguard Worker #meson test --no-rebuild --print-errorlogs 36*44844408SAndroid Build Coastguard Worker 37*44844408SAndroid Build Coastguard Worker sudo ninja install 38*44844408SAndroid Build Coastguard Worker``` 39*44844408SAndroid Build Coastguard Worker 40*44844408SAndroid Build Coastguard Worker## Building and testing with other build systems 41*44844408SAndroid Build Coastguard WorkerSee https://github.com/open-source-parsers/jsoncpp/wiki/Building 42*44844408SAndroid Build Coastguard Worker 43*44844408SAndroid Build Coastguard Worker## Running the tests manually 44*44844408SAndroid Build Coastguard Worker 45*44844408SAndroid Build Coastguard WorkerYou need to run tests manually only if you are troubleshooting an issue. 46*44844408SAndroid Build Coastguard Worker 47*44844408SAndroid Build Coastguard WorkerIn the instructions below, replace `path/to/jsontest` with the path of the 48*44844408SAndroid Build Coastguard Worker`jsontest` executable that was compiled on your platform. 49*44844408SAndroid Build Coastguard Worker 50*44844408SAndroid Build Coastguard Worker cd test 51*44844408SAndroid Build Coastguard Worker # This will run the Reader/Writer tests 52*44844408SAndroid Build Coastguard Worker python runjsontests.py path/to/jsontest 53*44844408SAndroid Build Coastguard Worker 54*44844408SAndroid Build Coastguard Worker # This will run the Reader/Writer tests, using JSONChecker test suite 55*44844408SAndroid Build Coastguard Worker # (http://www.json.org/JSON_checker/). 56*44844408SAndroid Build Coastguard Worker # Notes: not all tests pass: JsonCpp is too lenient (for example, 57*44844408SAndroid Build Coastguard Worker # it allows an integer to start with '0'). The goal is to improve 58*44844408SAndroid Build Coastguard Worker # strict mode parsing to get all tests to pass. 59*44844408SAndroid Build Coastguard Worker python runjsontests.py --with-json-checker path/to/jsontest 60*44844408SAndroid Build Coastguard Worker 61*44844408SAndroid Build Coastguard Worker # This will run the unit tests (mostly Value) 62*44844408SAndroid Build Coastguard Worker python rununittests.py path/to/test_lib_json 63*44844408SAndroid Build Coastguard Worker 64*44844408SAndroid Build Coastguard Worker # You can run the tests using valgrind: 65*44844408SAndroid Build Coastguard Worker python rununittests.py --valgrind path/to/test_lib_json 66*44844408SAndroid Build Coastguard Worker 67*44844408SAndroid Build Coastguard Worker## Building the documentation 68*44844408SAndroid Build Coastguard Worker 69*44844408SAndroid Build Coastguard WorkerRun the Python script `doxybuild.py` from the top directory: 70*44844408SAndroid Build Coastguard Worker 71*44844408SAndroid Build Coastguard Worker python doxybuild.py --doxygen=$(which doxygen) --open --with-dot 72*44844408SAndroid Build Coastguard Worker 73*44844408SAndroid Build Coastguard WorkerSee `doxybuild.py --help` for options. 74*44844408SAndroid Build Coastguard Worker 75*44844408SAndroid Build Coastguard Worker## Adding a reader/writer test 76*44844408SAndroid Build Coastguard Worker 77*44844408SAndroid Build Coastguard WorkerTo add a test, you need to create two files in test/data: 78*44844408SAndroid Build Coastguard Worker 79*44844408SAndroid Build Coastguard Worker* a `TESTNAME.json` file, that contains the input document in JSON format. 80*44844408SAndroid Build Coastguard Worker* a `TESTNAME.expected` file, that contains a flatened representation of the 81*44844408SAndroid Build Coastguard Worker input document. 82*44844408SAndroid Build Coastguard Worker 83*44844408SAndroid Build Coastguard WorkerThe `TESTNAME.expected` file format is as follows: 84*44844408SAndroid Build Coastguard Worker 85*44844408SAndroid Build Coastguard Worker* Each line represents a JSON element of the element tree represented by the 86*44844408SAndroid Build Coastguard Worker input document. 87*44844408SAndroid Build Coastguard Worker* Each line has two parts: the path to access the element separated from the 88*44844408SAndroid Build Coastguard Worker element value by `=`. Array and object values are always empty (i.e. 89*44844408SAndroid Build Coastguard Worker represented by either `[]` or `{}`). 90*44844408SAndroid Build Coastguard Worker* Element path `.` represents the root element, and is used to separate object 91*44844408SAndroid Build Coastguard Worker members. `[N]` is used to specify the value of an array element at index `N`. 92*44844408SAndroid Build Coastguard Worker 93*44844408SAndroid Build Coastguard WorkerSee the examples `test_complex_01.json` and `test_complex_01.expected` to better understand element paths. 94*44844408SAndroid Build Coastguard Worker 95*44844408SAndroid Build Coastguard Worker## Understanding reader/writer test output 96*44844408SAndroid Build Coastguard Worker 97*44844408SAndroid Build Coastguard WorkerWhen a test is run, output files are generated beside the input test files. Below is a short description of the content of each file: 98*44844408SAndroid Build Coastguard Worker 99*44844408SAndroid Build Coastguard Worker* `test_complex_01.json`: input JSON document. 100*44844408SAndroid Build Coastguard Worker* `test_complex_01.expected`: flattened JSON element tree used to check if 101*44844408SAndroid Build Coastguard Worker parsing was corrected. 102*44844408SAndroid Build Coastguard Worker* `test_complex_01.actual`: flattened JSON element tree produced by `jsontest` 103*44844408SAndroid Build Coastguard Worker from reading `test_complex_01.json`. 104*44844408SAndroid Build Coastguard Worker* `test_complex_01.rewrite`: JSON document written by `jsontest` using the 105*44844408SAndroid Build Coastguard Worker `Json::Value` parsed from `test_complex_01.json` and serialized using 106*44844408SAndroid Build Coastguard Worker `Json::StyledWritter`. 107*44844408SAndroid Build Coastguard Worker* `test_complex_01.actual-rewrite`: flattened JSON element tree produced by 108*44844408SAndroid Build Coastguard Worker `jsontest` from reading `test_complex_01.rewrite`. 109*44844408SAndroid Build Coastguard Worker* `test_complex_01.process-output`: `jsontest` output, typically useful for 110*44844408SAndroid Build Coastguard Worker understanding parsing errors. 111*44844408SAndroid Build Coastguard Worker 112*44844408SAndroid Build Coastguard Worker## Versioning rules 113*44844408SAndroid Build Coastguard Worker 114*44844408SAndroid Build Coastguard WorkerConsumers of this library require a strict approach to incrementing versioning of the JsonCpp library. Currently, we follow the below set of rules: 115*44844408SAndroid Build Coastguard Worker 116*44844408SAndroid Build Coastguard Worker* Any new public symbols require a minor version bump. 117*44844408SAndroid Build Coastguard Worker* Any alteration or removal of public symbols requires a major version bump, including changing the size of a class. This is necessary for 118*44844408SAndroid Build Coastguard Workerconsumers to do dependency injection properly. 119*44844408SAndroid Build Coastguard Worker 120*44844408SAndroid Build Coastguard Worker## Preparing code for submission 121*44844408SAndroid Build Coastguard Worker 122*44844408SAndroid Build Coastguard WorkerGenerally, JsonCpp's style guide has been pretty relaxed, with the following common themes: 123*44844408SAndroid Build Coastguard Worker 124*44844408SAndroid Build Coastguard Worker* Variables and function names use lower camel case (E.g. parseValue or collectComments). 125*44844408SAndroid Build Coastguard Worker* Class use camel case (e.g. OurReader) 126*44844408SAndroid Build Coastguard Worker* Member variables have a trailing underscore 127*44844408SAndroid Build Coastguard Worker* Prefer `nullptr` over `NULL`. 128*44844408SAndroid Build Coastguard Worker* Passing by non-const reference is allowed. 129*44844408SAndroid Build Coastguard Worker* Single statement if blocks may omit brackets. 130*44844408SAndroid Build Coastguard Worker* Generally prefer less space over more space. 131*44844408SAndroid Build Coastguard Worker 132*44844408SAndroid Build Coastguard WorkerFor an example: 133*44844408SAndroid Build Coastguard Worker 134*44844408SAndroid Build Coastguard Worker```c++ 135*44844408SAndroid Build Coastguard Workerbool Reader::decodeNumber(Token& token) { 136*44844408SAndroid Build Coastguard Worker Value decoded; 137*44844408SAndroid Build Coastguard Worker if (!decodeNumber(token, decoded)) 138*44844408SAndroid Build Coastguard Worker return false; 139*44844408SAndroid Build Coastguard Worker currentValue().swapPayload(decoded); 140*44844408SAndroid Build Coastguard Worker currentValue().setOffsetStart(token.start_ - begin_); 141*44844408SAndroid Build Coastguard Worker currentValue().setOffsetLimit(token.end_ - begin_); 142*44844408SAndroid Build Coastguard Worker return true; 143*44844408SAndroid Build Coastguard Worker} 144*44844408SAndroid Build Coastguard Worker``` 145*44844408SAndroid Build Coastguard Worker 146*44844408SAndroid Build Coastguard WorkerBefore submitting your code, ensure that you meet the versioning requirements above, follow the style guide of the file you are modifying (or the above rules for new files), and run clang format. Meson exposes clang format with the following command: 147*44844408SAndroid Build Coastguard Worker``` 148*44844408SAndroid Build Coastguard Workerninja -v -C build-${LIB_TYPE}/ clang-format 149*44844408SAndroid Build Coastguard Worker``` 150*44844408SAndroid Build Coastguard Worker 151*44844408SAndroid Build Coastguard WorkerFor convenience, you can also run the `reformat.sh` script located in the root directory. 152*44844408SAndroid Build Coastguard Worker 153