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 utility needed below).
8
9 Also install Python, Subversion, and Git and make sure they're in your path.
10
11
12 ### Windows development
13
14 PDFium uses a similar Windows toolchain as Chromium:
15
16 #### Open source contributors
17 Visual Studio 2015 Update 2 or later is highly recommended.
18
19 Run `set DEPOT_TOOLS_WIN_TOOLCHAIN=0`, or set that variable in your global
20 environment.
21
22 Compilation is done through ninja, **not** Visual Studio.
23
24 ### CPU Architectures supported
25
26 The default architecture for Windows, Linux, and Mac is "`x64`". On Windows,
27 "`x86`" is also supported. GN parameter "`target_cpu = "x86"`" can be used to
28 override the default value. If you specify Android build, the default CPU
29 architecture will be "`arm`".
30
31
32 #### Google employees
33
34 Run: `download_from_google_storage --config` and follow the
35 authentication instructions. **Note that you must authenticate with your
36 @google.com credentials**. Enter "0" if asked for a project-id.
37
38 Once you've done this, the toolchain will be installed automatically for
39 you in [the step](#GenBuild) below.
40
41 The toolchain will be in `depot_tools\win_toolchain\vs_files\<hash>`, and windbg
42 can be found in `depot_tools\win_toolchain\vs_files\<hash>\win_sdk\Debuggers`.
43
44 If you want the IDE for debugging and editing, you will need to install
45 it separately, but this is optional and not needed for building PDFium.
46
47 ## Get the code
48
49 The name of the top-level directory does not matter. In our examples, we use
50 "repo". This directory must not have been used before by `gclient config` as
51 each directory can only house a single gclient configuration.
52
53 ```
54 mkdir repo
55 cd repo
56 gclient config --unmanaged https://pdfium.googlesource.com/pdfium.git
57 gclient sync
58 cd pdfium
59 ```
60
61 ##<a name="GenBuild"></a> Generate the build files
62
63 We use GN to generate the build files and
64 [Ninja](http://martine.github.io/ninja/) (also included with the depot\_tools
65 checkout) to execute the build files.
66
67 ```
68 gn gen <directory>
69 ```
70
71 ### Selecting build configuration
72
73 PDFium may be built either with or without JavaScript support, and with
74 or without XFA forms support. Both of these features are enabled by
75 default. Also note that the XFA feature requires JavaScript.
76
77 Configuration is done by executing `gn args <directory>` to configure the build.
78 This will launch an editor in which you can set the following arguments.
79
80 ```
81 use_goma = true # Googlers only.
82 is_debug = true # Enable debugging features.
83
84 pdf_use_skia = false # Set true to enable experimental skia backend.
85 pdf_use_skia_paths = false # Set true to enable experimental skia backend (paths only).
86
87 pdf_enable_xfa = true # Set false to remove XFA support (implies JS support).
88 pdf_enable_v8 = true # Set false to remove Javascript support.
89 pdf_is_standalone = true # Set for a non-embedded build.
90 is_component_build = false # Disable component build (must be false)
91
92 clang_use_chrome_plugins = false # Currently must be false.
93 use_sysroot = false # Currently must be false on Linux.
94 ```
95
96 Note, you must set `pdf_is_standalone = true` if you want the sample
97 applications like `pdfium_test` to build.
98
99 When complete the arguments will be stored in `<directory>/args.gn`.
100
101 ## Building the code
102
103 If you used Ninja, you can build the sample program by:
104 `ninja -C <directory>/pdfium_test` You can build the entire product (which
105 includes a few unit tests) by: `ninja -C <directory>`.
106
107 ## Running the sample program
108
109 The pdfium\_test program supports reading, parsing, and rasterizing the pages of
110 a .pdf file to .ppm or .png output image files (windows supports two other
111 formats). For example: `<directory>/pdfium_test --ppm path/to/myfile.pdf`. Note
112 that this will write output images to `path/to/myfile.pdf.<n>.ppm`.
113
114 ## Testing
115
116 There are currently several test suites that can be run:
117
118 * pdfium\_unittests
119 * pdfium\_embeddertests
120 * testing/tools/run\_corpus\_tests.py
121 * testing/tools/run\_javascript\_tests.py
122 * testing/tools/run\_pixel\_tests.py
123
124 It is possible the tests in the `testing` directory can fail due to font
125 differences on the various platforms. These tests are reliable on the bots. If
126 you see failures, it can be a good idea to run the tests on the tip-of-tree
127 checkout to see if the same failures appear.
128
129 ## Waterfall
130
131 The current health of the source tree can be found at
132 http://build.chromium.org/p/client.pdfium/console
133
134 ## Community
135
136 There are several mailing lists that are setup:
137
138 * [PDFium](https://groups.google.com/forum/#!forum/pdfium)
139 * [PDFium Reviews](https://groups.google.com/forum/#!forum/pdfium-reviews)
140 * [PDFium Bugs](https://groups.google.com/forum/#!forum/pdfium-bugs)
141
142 Note, the Reviews and Bugs lists are typically read-only.
143
144 ## Bugs
145
146 We use this
147 [bug tracker](https://code.google.com/p/pdfium/issues/list), but for security
148 bugs, please use [Chromium's security bug template]
149 (https://code.google.com/p/chromium/issues/entry?template=Security%20Bug)
150 and add the "Cr-Internals-Plugins-PDF" label.
151
152 ## Contributing code
153
154 For contributing code, we will follow
155 [Chromium's process](http://dev.chromium.org/developers/contributing-code)
156 as much as possible. The main exceptions is:
157
158 1. Code has to conform to the existing style and not Chromium/Google style.
159
160