Let's get started with Prince. We will download and install the software and use it to generate a PDF from a very simple document with a very basic stylesheet. This chapter will get you up and running with Prince as quickly as possible.
Readers should already be familiar with HTML and CSS - many good tutorials are available on the topic. Familiarity with your computer's command line interface is desirable but not essential. Because the chapter is aimed at getting started as quickly as possible we may skip some explanations, don't worry as these will be covered later in the manual.
Prince is available for Windows, MacOS X, Linux (multiple distributions), FreeBSD and Solaris. You can download the relevant file from our downloads page. For Linux, FreeBSD and Solaris you may need to choose based on your distribution type, version and processor type (32/64 bits).
Prince is provided under the terms of the Prince End-User License Agreement.
After downloading and attempting to run the installer you might see a confirmation screen like this. Click "run". Note that the filename for the installer may be different than the one shown in the picture.
The installer will display a welcome screen like the one below. Click next.
Next you will need to accept the license agreement. The text of the license agreement is also available here. Accept the agreement and click Next.
Choose the installation directory for Prince.
The default is recommended unless you have a specific reason to install
Prince elsewhere.
When using Prince from the command line we will use the executable in the
Engine\bin\ subdirectory.
The installation requires only 16MB of disk space.
The installation will confirm the installation details with you before performing the installation. Click Next to continue.
After the installation has completed you have the option to launch the Prince graphical user interface (GUI). The Prince graphical user interface is only available for Microsoft Windows. Your First Document provides more information about how to use both the GUI and the command line interfaces. Click Finish to close the installer.
For the layout of a Prince installation on Windows, see the Windows installation layout section.
For information about using Prince from PHP, Java, .NET, and other server frameworks you will need to install one or more Prince wrappers. See Server Integration for installation and usage information.
MacOS X installation uses a single package which is installed using the
Terminal.app.
Find and launch Terminal.app and enter the following commands.
The $ symbol represents the command prompt and the text that
follows is the command,
you should not type in the $ symbol.
$ cd download_directory
Use the cd command to change to the
directory where the Prince package was downloaded.
Replace download_directory with the
actual location where you downloaded Prince.
Unpack the package. Note that the package name may be different than the example shown here. This will create a new directory containing the Prince files.
Change into the new directory. As before, the directory name may be different from the one in this example.
Run the install.sh script.
If you want to install Prince for multiple users you may need to
execute this command with sudo as shown here.
sudo will execute the given command with `root'
(administrator) privileges.
It may prompt you for your password (your user account's password)
before executing the command.
If you're installing Prince for only one user you can omit
sudo from this command.
The script will prompt you for the installation directory.
You can press enter to accept the default
(/usr/local)
or type in your preferred directory.
In this example the user has typed
/opt/prince.
If you're installing prince for only one user (and not using
sudo you will need to choose a directory that you have
write access to.
If you chose a non-standard location you may need to add the
bin/ subdirectory to your PATH
environment variable.
There are many different types of command interpreters (also called shells),
we cannot possibly document all of them.
However for borne-style shells (the most common type)
the command might look like this:
$ export PATH=/usr/local/prince10/bin:$PATH
You will need to add the appropriate command to your shell's configuration or startup file. See your distribution or shell's documentation for how to do this.
Prince is now ready to use. Your First Document will walk you through generating your first PDF document.
For the layout of a Prince installation on MacOS X, see the MacOS X installation layout section.
For information about using Prince from PHP, Java, .NET, and other server frameworks you will need to install one or more Prince wrappers. See Server Integration for installation and usage information.
Prince is installed using the terminal.
Open a terminal window and change to the directory that you downloaded or
copied the installation package to.
The $ symbol represents the command prompt and the text that
follows is the command,
you should not type in the $ symbol.
$ cd download_directory
Depending on your distribution and the package that you downloaded you may be able to install Price using the tools provided by your distribution.
On Debian and Ubuntu Linux you can use gdebi
to install Prince and its dependencies.
gdebi will automatically download and install any package
dependencies,
therefore it is often easier to use gdebi than
dpkg which will not automatically install dependencies.
If you're not logged in as root (and you shouldn't be), then you can use
sudo to run the gdebi command as root.
$ sudo gdebi prince_10r2-1_debian8.0_amd64.deb
Reading package lists... Done
Building dependency tree
Reading state information... Done
Building data structures... Done
Building data structures... Done
formatter for converting XML and HTML into PDF
This program converts XML and HTML into PDF.
Do you want to install the software package? [y/N]:y
Selecting previously unselected package prince.
(Reading database ... 319168 files and directories currently installed.)
Preparing to unpack prince_10r2-1_debian8.0_amd64.deb ...
Unpacking prince (10r2-1) ...
Setting up prince (10r2-1) ...
Processing triggers for man-db (2.7.0.2-5) ...
If gdebi is not already installed then you can install it using
aptitude as follows.
aptitude cannot be used to install Prince itself as Prince is
not available in a Debian repository.
$ sudo aptitude install gdebi
On RPM based systems, such as Redhat Enterprise Linux and CentOS,
you should use the yum tool to install Prince.
If you're not logged in as root (and you shouldn't be), then you can use
sudo to run the yum command as root.
$ sudo yum install prince-10r2-1.centos6.x86_64.rpm
We have not shown all of yum's output here as there is a lot of
it.
The process should prompt you before installation, which will look
similar to:
================================================================================
Package Arch Version Repository Size
================================================================================
Installing:
prince x86_64 10r2-1 /prince-10r2-1.centos6.x86_64 13 M
Installing for dependencies:
fontconfig x86_64 2.8.0-5.el6 base 186 k
giflib x86_64 4.1.6-3.1.el6 base 37 k
libSM x86_64 1.2.1-2.el6 base 37 k
libX11 x86_64 1.6.0-2.2.el6 base 586 k
libX11-common noarch 1.6.0-2.2.el6 base 192 k
libjpeg-turbo x86_64 1.2.1-3.el6_5 base 174 k
libtiff x86_64 3.9.4-10.el6_5 base 343 k
Transaction Summary
================================================================================
Install 8 Package(s)
Total size: 15 M
Total download size: 1.5 M
Installed size: 18 M
Is this ok [y/N]: y
Downloading Packages:
The process will then end with messages similar to:
Installed:
prince.x86_64 0:10r2-1
Dependency Installed:
fontconfig.x86_64 0:2.8.0-5.el6 giflib.x86_64 0:4.1.6-3.1.el6
libSM.x86_64 0:1.2.1-2.el6 libX11.x86_64 0:1.6.0-2.2.el6
libX11-common.noarch 0:1.6.0-2.2.el6 libjpeg-turbo.x86_64 0:1.2.1-3.el6_5
libtiff.x86_64 0:3.9.4-10.el6_5
Complete!
Prince is now ready to use. Your First Document will walk you through generating your first PDF document.
For information about using Prince from PHP, Java, .NET, and other server frameworks you will need to install one or more Prince wrappers. See Server Integration for installation and usage information.
On OpenSUSE you should use the zypper tool to install Prince.
If you're not logged in as root (and you shouldn't be), then you can use
sudo to run the zypper command as root.
$ sudo zypper install prince-10r2-1.opensuse13.2.x86_64.rpm
The process should prompt you during installation. The installation process should look similar to:
Retrieving repository 'Update Repository (Non-Oss)' metadata .............[done]
Building repository 'Update Repository (Non-Oss)' cache ..................[done]
Retrieving repository 'Main Update Repository' metadata ..................[done]
Building repository 'Main Update Repository' cache .......................[done]
Loading repository data...
Reading installed packages...
Resolving package dependencies...
The following 7 NEW packages are going to be installed:
fontconfig libgif6 libjbig2 libjpeg8 libpng12-0 libtiff5 prince
7 new packages to install.
Overall download size: 4.3 MiB. Already cached: 0 B After the operation,
additional 15.2 MiB will be used.
Continue? [y/n/? shows all options] (y): y
Retrieving package fontconfig-2.11.1-2.1.2.x86_64
(1/7), 335.0 KiB ( 1.2 MiB unpacked)
Retrieving: fontconfig-2.11.1-2.1.2.x86_64.rpm .............[done (469.7 KiB/s)]
Retrieving package libgif6-5.0.5-4.1.2.x86_64
(2/7), 20.6 KiB ( 35.4 KiB unpacked)
Retrieving: libgif6-5.0.5-4.1.2.x86_64.rpm .................[done (239.9 KiB/s)]
Retrieving package libjbig2-2.1-2.1.2.x86_64
(3/7), 28.2 KiB ( 67.2 KiB unpacked)
Retrieving: libjbig2-2.1-2.1.2.x86_64.rpm ................................[done]
Retrieving package libpng12-0-1.2.51-3.1.2.x86_64
(4/7), 75.4 KiB (171.0 KiB unpacked)
Retrieving: libpng12-0-1.2.51-3.1.2.x86_64.rpm ..............[done (19.7 KiB/s)]
Retrieving package libjpeg8-8.0.2-30.5.1.x86_64
(5/7), 102.3 KiB (274.0 KiB unpacked)
Retrieving: libjpeg8-8.0.2-30.5.1.x86_64.rpm .............................[done]
Retrieving package libtiff5-4.0.3-10.7.1.x86_64
(6/7), 147.6 KiB (479.6 KiB unpacked)
Retrieving: libtiff5-4.0.3-10.7.1.x86_64.rpm .............................[done]
Retrieving package prince-10r2-1.x86_64 (7/7), 3.6 MiB ( 13.0 MiB unpacked)
Checking for file conflicts: .............................................[done]
(1/7) Installing: fontconfig-2.11.1-2.1.2 ................................[done]
(2/7) Installing: libgif6-5.0.5-4.1.2 ....................................[done]
(3/7) Installing: libjbig2-2.1-2.1.2 .....................................[done]
(4/7) Installing: libpng12-0-1.2.51-3.1.2 ................................[done]
(5/7) Installing: libjpeg8-8.0.2-30.5.1 ..................................[done]
(6/7) Installing: libtiff5-4.0.3-10.7.1 ..................................[done]
(7/7) Installing: prince-10r2-1 ..........................................[done]
Prince is now ready to use. Your First Document will walk you through generating your first PDF document.
For the layout of a Prince installation on Linux, see the Linux installation layout section.
For information about using Prince from PHP, Java, .NET, and other server frameworks you will need to install one or more Prince wrappers. See Server Integration for installation and usage information.
Prince can be installed onto FreeBSD and Solaris from a
tarball
(a .tar.gz file).
This can also work on Linux and should be used when there was no
.deb or .rpm
package for your system or the package for your system didn't work for some
reason.
In these cases this section contains the relevant installation instructions.
Start by choosing the tarball that is the closest match for your system, take care to match operating system (Linux vs FreeBSD) and processor type (32 vs 64bit - please note that Prince supports only x86 and x86_64 processors). The dynamic packages rely on shared libraries installed you your system. These packages are smaller and they save memory when multiple programs use the same shared libraries. However, some libraries may not be installed or the correct versions might not be available, see Shared library trouble. In these cases the static packages will be more suitable.
To install Prince from a tarball enter these commands.
$ tar xzf prince-10r2-freebsd10.1-amd64.tar.gz
Start by unpacking the package. Note that the package name may be different than the example shown here. This will create a new directory containing the Prince files.
Change into the new directory unpacked by the package. As before, the directory name may be different from the one in this example.
Run the install.sh script.
If you want to install Prince for multiple users you may need to
execute this command with sudo as shown here.
sudo will execute the given command with `root'
(administrator) privileges.
It may prompt you for your password (your user account's password)
before executing the command.
If you're installing Prince for only one user you can omit
sudo from this command.
The script will prompt you for the installation directory.
You can press enter to accept the default
(/usr/local)
or type in your preferred directory.
In this example the user has accepted the default by pressing
ENTER without entering anything.
If you're installing Prince for only one user (and not using
sudo you will need to choose a directory that you have
write access to.
If you chose a non-standard location you may need to add the
bin/ subdirectory to your PATH
environment variable.
There are many different types of command interpreters (also called shells),
we cannot possibly document all of them.
However for borne-style shells (the most common type)
the command might look like this:
export PATH=/usr/local/prince10/bin:$PATH
You will need to add the appropriate command to your shell's configuration or startup file. See your operating system's or shell's documentation for how to do this.
Prince is now ready to use. Your First Document will walk you through generating your first PDF document.
For information about using Prince from PHP, Java, .NET, and other server frameworks you will need to install one or more Prince wrappers. See Server Integration for installation and usage information.
If you've purchased Prince you can install your license file (which you will receive via e-mail) to remove the watermark on generated documents. This section will explain how to install the license file. If instead you're using the free version of Prince then you don't need to install a license file.
On Windows you can install a license by following these steps:
Open the license window by clicking the License icon in the main window (Click the license button).
Click the open button and choose your license file (License window).
The license should be displayed in the lower part of the window, click the accept button to install it then click Ok (License window with license).
On other systems copy the license.dat file
into the lib/prince/license
directory of the Prince installation.
For example, if Prince was installed into the default
/usr/local directory,
the license file should be copied to
/usr/local/lib/prince/license/license.dat
$ cp license.dat /usr/local/lib/prince/license/license.dat
$ prince --version
Prince 10 rev 3
Copyright 2002-2015 YesLogic Pty. Ltd.
Test License
Remember to backup your license file in case you want to reinstall Prince in the future.