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