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