xref: /aosp_15_r20/external/jsoncpp/CONTRIBUTING.md (revision 4484440890e2bc6e07362b4feaf15601abfe0071)
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