summaryrefslogtreecommitdiff
path: root/README.md
blob: 6fa829122860e5b6450bcde6b7537a9fa1246bd3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
# 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

```
mkdir pdfium
cd pdfium
gclient config --name . --unmanaged https://pdfium.googlesource.com/pdfium.git
gclient sync
```

## 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`