diff --git a/README.md b/README.md index bfcd8b3..038ccd2 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -Introduction ------------- +# JsonCpp [JSON][json-org] is a lightweight data-interchange format. It can represent numbers, strings, ordered sequences of values, and collections of name/value @@ -7,20 +6,29 @@ pairs. [json-org]: http://json.org/ -[JsonCpp][] is a C++ library that allows manipulating JSON values, including +JsonCpp is a C++ library that allows manipulating JSON values, including serialization and deserialization to and from strings. It can also preserve existing comment in unserialization/serialization steps, making it a convenient format to store user input files. -[JsonCpp]: http://open-source-parsers.github.io/jsoncpp-docs/doxygen/index.html + +## Documentation + +[JsonCpp documentation][JsonCpp-documentation] is generated using [Doxygen][]. + +[JsonCpp-documentation]: http://open-source-parsers.github.io/jsoncpp-docs/doxygen/index.html +[Doxygen]: http://www.doxygen.org + ## A note on backward-compatibility + * `1.y.z` is built with C++11. * `0.y.z` can be used with older compilers. * Major versions maintain binary-compatibility. -# Using JsonCpp in your project ------------------------------ + +## Using JsonCpp in your project + The recommended approach to integrating JsonCpp in your project is to include the [amalgamated source](#generating-amalgamated-source-and-header) (a single `.cpp` file and two `.h` files) in your project, and compile and build as you @@ -28,16 +36,15 @@ would any other source file. This ensures consistency of compilation flags and ABI compatibility, issues which arise when building shared or static libraries. See the next section for instructions. -The `include/` should be added to your compiler include path. Jsoncpp headers +The `include/` should be added to your compiler include path. JsonCpp headers should be included as follow: #include -If JsonCpp was built as a dynamic library on Windows, then your project needs to -define the macro `JSON_DLL`. +If JsonCpp was built as a dynamic library on Windows, then your project needs to define the macro `JSON_DLL`. + +### Generating amalgamated source and header -Generating amalgamated source and header ----------------------------------------- JsonCpp is provided with a script to generate a single header and a single source file to ease inclusion into an existing project. The amalgamated source can be generated at any time by running the following command from the @@ -48,6 +55,7 @@ top-directory (this requires Python 2.6): It is possible to specify header name. See the `-h` option for detail. By default, the following files are generated: + * `dist/jsoncpp.cpp`: source file that needs to be added to your project. * `dist/json/json.h`: corresponding header file for use in your project. It is equivalent to including `json/json.h` in non-amalgamated source. This header @@ -56,15 +64,14 @@ By default, the following files are generated: JsonCpp types. The amalgamated sources are generated by concatenating JsonCpp source in the -correct order and defining the macro `JSON_IS_AMALGAMATION` to prevent inclusion -of other headers. +correct order and defining the macro `JSON_IS_AMALGAMATION` to prevent inclusion of other headers. -# Contributing to JsonCpp -Building and testing with CMake -------------------------------- -[CMake][] is a C++ Makefiles/Solution generator. It is usually available on most -Linux system as package. On Ubuntu: +## Contributing to JsonCpp + +### Building and testing with CMake + +[CMake][] is a C++ Makefiles/Solution generator. It is usually available on most Linux system as package. On Ubuntu: sudo apt-get install cmake @@ -75,9 +82,9 @@ missing, the build will skip running those tests. When running CMake, a few parameters are required: -* a build directory where the makefiles/solution are generated. It is also used +* A build directory where the makefiles/solution are generated. It is also used to store objects, libraries and executables files. -* the generator to use: makefiles or Visual Studio solution? What version or +* The generator to use: makefiles or Visual Studio solution? What version or Visual Studio, 32 or 64 bits solution? Steps for generating solution/makefiles using `cmake-gui`: @@ -107,10 +114,10 @@ the `-G` option). By default CMake hides compilation commands. This can be modified by specifying `-DCMAKE_VERBOSE_MAKEFILE=true` when generating makefiles. -Building and testing with SCons -------------------------------- -**Note:** The SCons-based build system is deprecated. Please use CMake; see the -section above. +### Building and testing with SCons + +**Note:** The SCons-based build system is deprecated. Please use CMake (see the +section above). JsonCpp can use [Scons][] as a build system. Note that SCons requires Python to be installed. @@ -137,7 +144,8 @@ If you are building with Microsoft Visual Studio 2008, you need to set up the environment by running `vcvars32.bat` (e.g. MSVC 2008 command prompt) before running SCons. -## Running the tests manually +### Running the tests manually + You need to run tests manually only if you are troubleshooting an issue. In the instructions below, replace `path/to/jsontest` with the path of the @@ -160,21 +168,22 @@ In the instructions below, replace `path/to/jsontest` with the path of the # You can run the tests using valgrind: python rununittests.py --valgrind path/to/test_lib_json -## Running the tests using scons +### Running the tests using SCons + Note that tests can be run using SCons using the `check` target: scons platform=$PLATFORM check -Building the documentation --------------------------- +### Building the documentation + Run the Python script `doxybuild.py` from the top directory: python doxybuild.py --doxygen=$(which doxygen) --open --with-dot See `doxybuild.py --help` for options. -Adding a reader/writer test ---------------------------- +### Adding a reader/writer test + To add a test, you need to create two files in test/data: * a `TESTNAME.json` file, that contains the input document in JSON format. @@ -183,21 +192,19 @@ To add a test, you need to create two files in test/data: The `TESTNAME.expected` file format is as follows: -* each line represents a JSON element of the element tree represented by the +* Each line represents a JSON element of the element tree represented by the input document. -* each line has two parts: the path to access the element separated from the +* Each line has two parts: the path to access the element separated from the element value by `=`. Array and object values are always empty (i.e. represented by either `[]` or `{}`). -* element path: `.` represents the root element, and is used to separate object +* Element path `.` represents the root element, and is used to separate object members. `[N]` is used to specify the value of an array element at index `N`. -See the examples `test_complex_01.json` and `test_complex_01.expected` to better -understand element paths. +See the examples `test_complex_01.json` and `test_complex_01.expected` to better understand element paths. -Understanding reader/writer test output ---------------------------------------- -When a test is run, output files are generated beside the input test files. -Below is a short description of the content of each file: +### Understanding reader/writer test output + +When a test is run, output files are generated beside the input test files. Below is a short description of the content of each file: * `test_complex_01.json`: input JSON document. * `test_complex_01.expected`: flattened JSON element tree used to check if @@ -212,7 +219,7 @@ Below is a short description of the content of each file: * `test_complex_01.process-output`: `jsontest` output, typically useful for understanding parsing errors. -License -------- +## License + See the `LICENSE` file for details. In summary, JsonCpp is licensed under the MIT license, or public domain if desired and recognized in your jurisdiction.