Add some community and testing info to README.md.
[pdfium.git] / README.md
1 # PDFium
2
3 ## Prerequisites
4
5 Get the chromium depot tools via the instructions at
6 http://www.chromium.org/developers/how-tos/install-depot-tools (this provides
7 the gclient utilty needed below).
8
9 Also install Python, Subversion, and Git and make sure they're in your path.
10
11 ## Get the code
12
13 ```
14 mkdir pdfium
15 cd pdfium
16 gclient config --name . --unmanaged https://pdfium.googlesource.com/pdfium.git
17 gclient sync
18 ```
19
20 ## Generate the build files
21
22 We use the GYP library to generate the build files.
23
24 At this point, you have two options. The first option is to use the [Ninja]
25 (http://martine.github.io/ninja/) build system (also included with the
26 depot\_tools checkout). This is the default as of mid-September, 2015.
27 Previously, the second option (platform-specific build files) was the default.
28 Most PDFium developers use Ninja, as does our [continuous build system]
29 (http://build.chromium.org/p/client.pdfium/).
30
31  * On Windows: `build\gyp\_pdfium`
32  * For all other platforms: `build/gyp\_pdfium`
33
34 The second option is to generate platform-specific build files, i.e. Makefiles
35 on Linux, sln files on Windows, and xcodeproj files on Mac. To do so, set the
36 GYP\_GENERATORS environment variable appropriately (e.g. "make", "msvs", or
37 "xcode") before running the above command.
38
39 ## Building the code
40
41 If you used Ninja, you can build the sample program by: `ninja -C out/Debug
42 pdfium\_test` You can build the entire product (which includes a few unit
43 tests) by: `ninja -C out/Debug`.
44
45 If you're not using Ninja, then building is platform-specific.
46
47  * On Linux: `make pdfium\_test`
48  * On Mac: `open build/all.xcodeproj`
49  * On Windows: open build\all.sln
50
51 ## Running the sample program
52
53 The pdfium\_test program supports reading, parsing, and rasterizing the pages of
54 a .pdf file to .ppm or .png output image files (windows supports two other
55 formats). For example: `out/Debug/pdfium\_test --ppm path/to/myfile.pdf`. Note
56 that this will write output images to `path/to/myfile.pdf.<n>.ppm`.
57
58 ## Testing
59
60 There are currently several test suites that can be run:
61
62  * pdfium\_unittests
63  * pdfium\_embeddertests
64  * testing/tools/run\_corpus\_tests.py
65  * testing/tools/run\_javascript\_tests.py
66  * testing/tools/run\_pixel\_tests.py
67
68 It is possible the tests in the `testing` directory can fail due to font
69 differences on the various platforms. These tests are reliable on the bots. If
70 you see failures, it can be a good idea to run the tests on the tip-of-tree
71 checkout to see if the same failures appear.
72
73 ## Waterfall
74
75 The current health of the source tree can be found at
76 http://build.chromium.org/p/client.pdfium/console
77
78 ## Community
79
80 There are several mailing lists that are setup:
81
82  * [PDFium](https://groups.google.com/forum/#!forum/pdfium)
83  * [PDFium Reviews](https://groups.google.com/forum/#!forum/pdfium-reviews)
84  * [PDFium Bugs](https://groups.google.com/forum/#!forum/pdfium-bugs)
85
86 Note, the Reviews and Bugs lists are typically read-only.
87
88 ## Bugs
89
90  We will be using this
91 [bug tracker](https://code.google.com/p/pdfium/issues/list), but for security
92 bugs, please use [Chromium's security bug template]
93 (https://code.google.com/p/chromium/issues/entry?template=Security%20Bug)
94 and add the "Cr-Internals-Plugins-PDF" label.
95
96 ## Contributing code
97
98 For contributing code, we will follow
99 [Chromium's process](http://dev.chromium.org/developers/contributing-code)
100 as much as possible. The main exceptions are:
101
102 1. Code has to conform to the existing style and not Chromium/Google style.
103 2. There is no commit queue, approved committers can land their changes via
104 `git cl land`
105 3. Changes must be merged to the XFA branch as well (see below).
106
107 ## Branches
108
109 There is a branch for a forthcoming feature called XFA that you can get by
110 following the steps above, then:
111
112 ```
113 git checkout origin/xfa
114 build/gyp_pdfium
115 ninja -C out/Debug
116 ```
117
118 Merging to XFA requires:
119
120 ```
121 git checkout origin/xfa
122 git checkout -b merge_branch
123 git branch --set-upstream-to=origin/xfa
124 git cherry-pick -x <commit hash>
125 git commit --amend # add Merge to XFA
126 git cl upload
127 ```
128
129 Then wait for approval, and `git cl land`