Skip to content

Commit 57ee0e3

Browse files
blepblep
committed
- Documentation generation is no longer handled by SCons. The script doxybuild.py is used to generate the documentation on demand.
- Added file 'version' that contains jsoncpp version number. It is used by both SConstruct and doxybuild.py. - Updated README.txt with documentation build instruction, and instructions to add a test case.
1 parent 8d3790d commit 57ee0e3

7 files changed

Lines changed: 1600 additions & 284 deletions

File tree

‎README.txt‎

Lines changed: 69 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,21 @@
11
* Introduction:
2+
=============
23

34
JSON (JavaScript Object Notation) is a lightweight data-interchange format.
45
It can represent integer, real number, string, an ordered sequence of
56
value, and a collection of name/value pairs.
67

7-
JsonCpp is a simple API to manipulate JSON value, and handle serialization
8+
JsonCpp is a simple API to manipulate JSON value, handle serialization
89
and unserialization to string.
910

1011
It can also preserve existing comment in unserialization/serialization steps,
1112
making it a convenient format to store user input files.
1213

1314
Unserialization parsing is user friendly and provides precise error reports.
1415

16+
1517
* Building/Testing:
18+
=================
1619

1720
JsonCpp uses Scons (http://www.scons.org) as a build system. Scons requires
1821
python to be installed (http://www.python.org).
@@ -39,15 +42,76 @@ to do so.
3942

4043
and TARGET may be:
4144
check: build library and run unit tests.
42-
doc: build documentation
43-
doc-dist: build documentation tarball
4445

45-
To run the test manually:
46+
47+
* Running the test manually:
48+
==========================
49+
4650
cd test
4751
# This will run the Reader/Writer tests
4852
python runjsontests.py "path to jsontest.exe"
53+
54+
# This will run the Reader/Writer tests, using JSONChecker test suite
55+
# (http://www.json.org/JSON_checker/).
56+
# Notes: not all tests pass: JsonCpp is too lenient (for example,
57+
# it allows an integer to start with '0'). The goal is to improve
58+
# strict mode parsing to get all tests to pass.
59+
python runjsontests.py --with-json-checker "path to jsontest.exe"
60+
4961
# This will run the unit tests (mostly Value)
5062
python rununittests.py "path to test_lib_json.exe"
5163

52-
You can run the tests using valgrind using:
64+
You can run the tests using valgrind:
5365
python rununittests.py --valgrind "path to test_lib_json.exe"
66+
67+
68+
* Building the documentation:
69+
===========================
70+
71+
Run the python script doxybuild.py from the top directory:
72+
73+
python doxybuild.py --open --with-dot
74+
75+
See doxybuild.py --help for options.
76+
77+
78+
* Adding a reader/writer test:
79+
============================
80+
81+
To add a test, you need to create two files in test/data:
82+
- a TESTNAME.json file, that contains the input document in JSON format.
83+
- a TESTNAME.expected file, that contains a flatened representation of
84+
the input document.
85+
86+
TESTNAME.expected file format:
87+
- each line represents a JSON element of the element tree represented
88+
by the input document.
89+
- each line has two parts: the path to access the element separated from
90+
the element value by '='. Array and object values are always empty
91+
(e.g. represented by either [] or {}).
92+
- element path: '.' represented the root element, and is used to separate
93+
object members. [N] is used to specify the value of an array element
94+
at index N.
95+
See test_complex_01.json and test_complex_01.expected to better understand
96+
element path.
97+
98+
99+
* Understanding reader/writer test output:
100+
========================================
101+
102+
When a test is run, output files are generated aside the input test files.
103+
Below is a short description of the content of each file:
104+
105+
- test_complex_01.json: input JSON document
106+
- test_complex_01.expected: flattened JSON element tree used to check if
107+
parsing was corrected.
108+
109+
- test_complex_01.actual: flattened JSON element tree produced by
110+
jsontest.exe from reading test_complex_01.json
111+
- test_complex_01.rewrite: JSON document written by jsontest.exe using the
112+
Json::Value parsed from test_complex_01.json and serialized using
113+
Json::StyledWritter.
114+
- test_complex_01.actual-rewrite: flattened JSON element tree produced by
115+
jsontest.exe from reading test_complex_01.rewrite.
116+
test_complex_01.process-output: jsontest.exe output, typically useful to
117+
understand parsing error.

‎SConstruct‎

Lines changed: 6 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,17 @@
11
"""
2-
Build system can be clean-up by sticking to a few core production factory, with automatic dependencies resolution.
3-
4 basic project productions:
4-
- library
5-
- binary
6-
- documentation
7-
- tests
2+
Notes:
3+
- shared library support is buggy: it assumes that a static and dynamic library can be build from the same object files. This is not true on many platforms. For this reason it is only enabled on linux-gcc at the current time.
84
9-
* Library:
10-
Input:
11-
- dependencies (other libraries)
12-
- headers: include path & files
13-
- sources
14-
- generated sources
15-
- resources
16-
- generated resources
17-
Production:
18-
- Static library
19-
- Dynamic library
20-
- Naming rule
21-
Life-cycle:
22-
- Library compilation
23-
- Compilation as a dependencies
24-
- Run-time
25-
- Packaging
26-
Identity:
27-
- Name
28-
- Version
29-
* Binary:
30-
Input:
31-
- dependencies (other libraries)
32-
- headers: include path & files (usually empty)
33-
- sources
34-
- generated sources
35-
- resources
36-
- generated resources
37-
- supported variant (optimized/debug, dll/static...)
38-
Production:
39-
- Binary executable
40-
- Manifest [on some platforms]
41-
- Debug symbol [on some platforms]
42-
Life-cycle:
43-
- Compilation
44-
- Run-time
45-
- Packaging
46-
Identity:
47-
- Name
48-
- Version
49-
* Documentation:
50-
Input:
51-
- dependencies (libraries, binaries)
52-
- additional sources
53-
- generated sources
54-
- resources
55-
- generated resources
56-
- supported variant (public/internal)
57-
Production:
58-
- HTML documentation
59-
- PDF documentation
60-
- CHM documentation
61-
Life-cycle:
62-
- Documentation
63-
- Packaging
64-
- Test
65-
Identity:
66-
- Name
67-
- Version
5+
To add a platform:
6+
- add its name in options allowed_values below
7+
- add tool initialization for this platform. Search for "if platform == 'suncc'" as an example.
688
"""
699

70-
71-
7210
import os
7311
import os.path
7412
import sys
7513

76-
JSONCPP_VERSION = '0.2'
14+
JSONCPP_VERSION = open(File('#version').abspath,'rt').read().strip()
7715
DIST_DIR = '#dist'
7816

7917
options = Variables()
@@ -174,8 +112,6 @@ else:
174112
print "UNSUPPORTED PLATFORM."
175113
env.Exit(1)
176114

177-
env.Tool('doxygen')
178-
env.Tool('substinfile')
179115
env.Tool('targz')
180116
env.Tool('srcdist')
181117
env.Tool('globtool')
@@ -295,6 +231,5 @@ env.Alias( 'src-dist', srcdist_cmd )
295231
buildProjectInDirectory( 'src/jsontestrunner' )
296232
buildProjectInDirectory( 'src/lib_json' )
297233
buildProjectInDirectory( 'src/test_lib_json' )
298-
buildProjectInDirectory( 'doc' )
299234
#print env.Dump()
300235

0 commit comments

Comments
 (0)