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 ### Using goma (Googlers only) 45 46 If you would like to build using goma, pass `use_goma=1` to `gyp_pdfium`. If 47 you installed goma in a non-standard location, you will also need to set 48 `gomadir`. e.g. 49 50 ``` 51 build/gyp_pdfium -D use_goma=1 -D gomadir=path/to/goma 52 ``` 53 54 ## Building the code 55 56 If you used Ninja, you can build the sample program by: `ninja -C out/Debug 57 pdfium_test` You can build the entire product (which includes a few unit 58 tests) by: `ninja -C out/Debug`. 59 60 If 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 68 The pdfium\_test program supports reading, parsing, and rasterizing the pages of 69 a .pdf file to .ppm or .png output image files (windows supports two other 70 formats). For example: `out/Debug/pdfium_test --ppm path/to/myfile.pdf`. Note 71 that this will write output images to `path/to/myfile.pdf.<n>.ppm`. 72 73 ## Testing 74 75 There 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 83 It is possible the tests in the `testing` directory can fail due to font 84 differences on the various platforms. These tests are reliable on the bots. If 85 you see failures, it can be a good idea to run the tests on the tip-of-tree 86 checkout to see if the same failures appear. 87 88 ## Waterfall 89 90 The current health of the source tree can be found at 91 http://build.chromium.org/p/client.pdfium/console 92 93 ## Community 94 95 There 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 101 Note, 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 107 bugs, please use [Chromium's security bug template] 108 (https://code.google.com/p/chromium/issues/entry?template=Security%20Bug) 109 and add the "Cr-Internals-Plugins-PDF" label. 110 111 ## Contributing code 112 113 For contributing code, we will follow 114 [Chromium's process](http://dev.chromium.org/developers/contributing-code) 115 as much as possible. The main exceptions are: 116 117 1. Code has to conform to the existing style and not Chromium/Google style. 118 2. There is no commit queue, approved committers can land their changes via 119 `git cl land` 120 3. Changes must be merged to the XFA branch as well (see below). 121 122 ## Branches 123 124 There is a branch for a forthcoming feature called XFA that you can get by 125 following the steps above, then: 126 127 ``` 128 git checkout origin/xfa 129 build/gyp_pdfium 130 ninja -C out/Debug 131 ``` 132 133 Merging to XFA requires: 134 135 ``` 136 git checkout origin/xfa 137 git checkout -b merge_branch 138 git branch --set-upstream-to=origin/xfa 139 git cherry-pick -x <commit hash> 140 git commit --amend # add Merge to XFA 141 git cl upload 142 ``` 143 144 Then wait for approval, and `git cl land` 145
