Move build instructions to README.md
[pdfium.git] / README.md
1 # Building 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 Optionally, you may want to install the [Ninja](http://martine.github.io/ninja/)
12 build system (recommended) rather than using your platform-specific build
13 system.
14
15 ## Get the code
16
17 ```
18 mkdir pdfium
19 cd pdfium
20 gclient config --name . --unmanaged https://pdfium.googlesource.com/pdfium.git
21 gclient sync
22 ```
23
24 ## Generate the build files
25
26 Now we use the GYP library to generate the build files.
27
28 At this point, you have two options. The first option is to use the [Ninja]
29 (http://martine.github.io/ninja/) build system. This is the default as of
30 mid-September, 2015. Previously, the second option was the default. Most PDFium
31 developers use Ninja, as does our [continuous build system]
32 (http://build.chromium.org/p/client.pdfium/).
33
34 On Windows: `build\gyp_pdfium
35 ` For all other platforms: `build/gyp_pdfium
36 `
37
38 The second option is to generate platform-specific build files, i.e. Makefiles
39 on Linux, sln files on Windows, and xcodeproj files on Mac. To do so, set the
40 GYP\_GENERATORS environment variable appropriately (e.g. "make", "msvs", or
41 "xcode") before running the above command.
42
43 ## Building the code
44
45 If you used Ninja, you can build the sample program by: `ninja -C out/Debug
46 pdfium_test
47 ` You can build the entire product (which includes a few unit tests) by: `ninja
48 -C out/Debug
49 `
50
51 If you're not using Ninja, then building is platform-specific.
52
53 On Linux: `make pdfium_test
54 `
55
56 On Mac, open build/all.xcodeproj
57
58 On Windows, open build\all.sln
59
60 ## Running the sample program
61
62 The pdfium\_test program supports reading, parsing, and rasterizing the pages of
63 a .pdf file to .ppm output image files (windows supports two other formats, and
64 .png support is available for all platforms in an alternate branch (see branches
65 section below)). For example: `out/Debug/pdfium_test --ppm path/to/myfile.pdf
66 `
67
68 ## Waterfall
69
70 The current health of the source tree can be found at
71 http://build.chromium.org/p/client.pdfium/console
72
73 ## Branches
74
75 There is a branch for a forthcoming feature called XFA that you can get by
76 following the steps above, then: `git checkout origin/xfa build/gyp_pdfium ninja
77 -C out/Debug
78 `
79
80 The XFA version of the sample pdfium\_test program supports rasterizing to .png
81 format files. For example: `out/Debug/pdfium_test --png path/to/myfile.pdf
82 `