summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md134
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`