diff options
author | Dan Sinclair <dsinclair@chromium.org> | 2015-10-22 14:58:54 -0400 |
---|---|---|
committer | Dan Sinclair <dsinclair@chromium.org> | 2015-10-22 14:58:54 -0400 |
commit | bc6c6723c37772b02de9e6e43fa0fd9439874905 (patch) | |
tree | 811c283b321ab80356b122ee855e1a8c602e67e2 /README.md | |
parent | 2bc980424d23d83e0d4b57b248789232709e07b8 (diff) | |
download | pdfium-bc6c6723c37772b02de9e6e43fa0fd9439874905.tar.xz |
XFA: Sync build and documentation differences with master.
This Cl syncs the AUTHORS, and README.md and build scripts in XFA to match master where possible.
R=tsepez@chromium.org
Review URL: https://codereview.chromium.org/1415423002 .
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000000..67d84485ff --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +# PDFium + +## Prerequisites + +Get the chromium depot tools via the instructions at +http://www.chromium.org/developers/how-tos/install-depot-tools (this provides +the gclient utilty needed below). + +Also install Python, Subversion, and Git and make sure they're in your path. + +## Get the code + +The name of the top-level directory does not matter. In our examples, we use +"repo". This directory must not have been used before by `gclient config` as +each directory can only house a single gclient configuration. + +``` +mkdir repo +cd repo +gclient config --unmanaged https://pdfium.googlesource.com/pdfium.git +gclient sync +cd pdfium +``` + +## Generate the build files + +We use the GYP library to generate the build files. + +At this point, you have two options. The first option is to use the [Ninja] +(http://martine.github.io/ninja/) build system (also included with the +depot\_tools checkout). This is the default as of mid-September, 2015. +Previously, the second option (platform-specific build files) was the default. +Most PDFium developers use Ninja, as does our [continuous build system] +(http://build.chromium.org/p/client.pdfium/). + + * On Windows: `build\gyp_pdfium` + * For all other platforms: `build/gyp_pdfium` + +The second option is to generate platform-specific build files, i.e. Makefiles +on Linux, sln files on Windows, and xcodeproj files on Mac. To do so, set the +GYP\_GENERATORS environment variable appropriately (e.g. "make", "msvs", or +"xcode") before running the above command. + +## Building the code + +If you used Ninja, you can build the sample program by: `ninja -C out/Debug +pdfium_test` You can build the entire product (which includes a few unit +tests) by: `ninja -C out/Debug`. + +If you're not using Ninja, then building is platform-specific. + + * On Linux: `make pdfium_test` + * On Mac: `open build/all.xcodeproj` + * On Windows: open build\all.sln + +## Running the sample program + +The pdfium\_test program supports reading, parsing, and rasterizing the pages of +a .pdf file to .ppm or .png output image files (windows supports two other +formats). For example: `out/Debug/pdfium_test --ppm path/to/myfile.pdf`. Note +that this will write output images to `path/to/myfile.pdf.<n>.ppm`. + +## Testing + +There are currently several test suites that can be run: + + * pdfium\_unittests + * pdfium\_embeddertests + * testing/tools/run\_corpus\_tests.py + * testing/tools/run\_javascript\_tests.py + * testing/tools/run\_pixel\_tests.py + +It is possible the tests in the `testing` directory can fail due to font +differences on the various platforms. These tests are reliable on the bots. If +you see failures, it can be a good idea to run the tests on the tip-of-tree +checkout to see if the same failures appear. + +## Waterfall + +The current health of the source tree can be found at +http://build.chromium.org/p/client.pdfium/console + +## Community + +There are several mailing lists that are setup: + + * [PDFium](https://groups.google.com/forum/#!forum/pdfium) + * [PDFium Reviews](https://groups.google.com/forum/#!forum/pdfium-reviews) + * [PDFium Bugs](https://groups.google.com/forum/#!forum/pdfium-bugs) + +Note, the Reviews and Bugs lists are typically read-only. + +## Bugs + + We will be using this +[bug tracker](https://code.google.com/p/pdfium/issues/list), but for security +bugs, please use [Chromium's security bug template] +(https://code.google.com/p/chromium/issues/entry?template=Security%20Bug) +and add the "Cr-Internals-Plugins-PDF" label. + +## Contributing code + +For contributing code, we will follow +[Chromium's process](http://dev.chromium.org/developers/contributing-code) +as much as possible. The main exceptions are: + +1. Code has to conform to the existing style and not Chromium/Google style. +2. There is no commit queue, approved committers can land their changes via +`git cl land` +3. Changes must be merged to the XFA branch as well (see below). + +## Branches + +There is a branch for a forthcoming feature called XFA that you can get by +following the steps above, then: + +``` +git checkout origin/xfa +build/gyp_pdfium +ninja -C out/Debug +``` + +Merging to XFA requires: + +``` +git checkout origin/xfa +git checkout -b merge_branch +git branch --set-upstream-to=origin/xfa +git cherry-pick -x <commit hash> +git commit --amend # add Merge to XFA +git cl upload +``` + +Then wait for approval, and `git cl land` |