Introduction
============

This file describes do's and don'ts, good practices, and requirements when
packaging TeXworks.

When you have read this far, you are probably interested in packaging TeXworks.
First of all, thank you for your commitment, it is very welcome. Before you
start, however, you should check that no packages for the system you intend to
target exist already. Currently, packages for Windows, Mac OS X, and Ubuntu are
provided by the project maintainers, and packages for several other Linux
distributions have been contributed by members of the community.

If you package TeXworks successfully, please drop by the mailing list and tell
us about it :).


General guidelines
==================

This section describes how TeXworks should be packaged. It does not deal with
the building process itself, however. Building in general is documented in
README.md and on https://github.com/TeXworks/texworks/wiki, while special
considerations concerning packaging are discussed in the following sections.
This section deals with the principal decisions.

 * TeXworks consists of the core program and plugins. If possibly, the plugins
   should be made available separately (unless noted otherwise). They are to be
   considered optional (Debian policy: they are suggested, not recommended,
   meaning that running TeXworks without them is perfectly reasonable).

 * All plugins that can be built should be built.

 * Stable releases feature a copy of the manual. Like the plugins, this should
   be packaged, preferably as a separate, optional package (Debian policy: a
   suggested package, meaning that you don't need it to run TeXworks, but
   typical installations will have it).

 * It is strongly recommended to distribute TeXworks with the poppler encoding
   data as well as the 14 PDF base fonts or suitable (i.e., metrically
   equivalent) replacements. On Linux, these are typically provided by the
   system and/or packages which the TeXworks package should depend on. Note that
   this is not a strict dependence, as TeXworks will run without poppler-data or
   the base-14 fonts, but some files may not be displayed correctly (Debian
   policy: the packages are recommended, meaning that they are found on all but
   the most unusual systems). Note that when providing poppler-data and/or fonts
   yourself in the package, you most likely will need to patch the poppler
   library itself as well.
   See below for further information on this issue and how to test proper
   functionality.


Building specialties
====================
When building TeXworks for packaging, you will probably face special
requirements, like installing in special locations to suit your packaging
process. This section discusses where and how such modifications to the default
behavior can be implemented.

The TeXworks build process supports several variables that can be set when
invoking CMake. To set a variable VAR1=abc and VAR2=xyz, invoke CMake as
   cmake -DVAR1=abc -DVAR2=xyz ..

The most important variable you must always set is TW_BUILD_ID. This ID should
uniquely identify the build process (who built it, for what platform, etc.) so
that packaging-related problems that are reported to the general mailing list
can be passed on to you, the packager.

Other variables that may be useful for packaging include:
   BUILD_SHARED_PLUGINS      flag to indicate whether plugins should be built
                             as separate shared libraries [true]
   PREFER_BUNDLED_SYNCTEX    set this flag to use SyncTeX is bundled with
                             TeXworks even if a system-wide installation is
                             found [false]
   DESIRED_QT_VERSION        set to 4 or 5 to indicate which Qt version to use;
                             useful only if you have several versions of Qt
                             installed
   TeXworks_PLUGIN_DIR       place to install plugin libraries to [OS specific]
   TEXWORKS_ADDITIONAL_LIBS  additional libraries that need to be passed to the
                             linker; useful only if CMake does not pick up all
                             dependencies automatically; separate multiple
                             libraries by a semicolon

In addition, several directory variables can be set on *nix (on Windows and the
Mac, packages are self-contained and don't usually install into (separate)
system directories):
   TeXworks_HELP_DIR     Path where TeXworks looks for help files
                         [share/doc/texworks-help]
   TeXworks_DIC_DIR      Path where TeXworks looks for spellchecking
                         dictionaries [/usr/share/myspell/dicts]
   TeXworks_DOCS_DIR     Path in which documentation files are installed
                         [share/doc/texworks]
   TeXworks_ICON_DIR     Path in which icons are installed [share/pixmaps]
   TeXworks_MAN_DIR      Path in which manpages are installed [share/man/man1]
   TeXworks_DESKTOP_DIR  Path in which .desktop files are installed
                         [share/applications]
   TeXworks_APPDATA_DIR  Path in which .appdata.xml files are installed
                         [share/appdata]
Unless an absolute paths are specified, paths are relative to
CMAKE_INSTALL_PREFIX.

Other than that, CMake should take care of most of your needs. For details about
how to tweak general CMake settings, please refer to the CMake documentation
(http://www.cmake.org/documentation/). A variables that you might find useful is
CMAKE_PREFIX_PATH.

Note that generated Makefiles still honor the DESTDIR= directive to take
CMAKE_INSTALL_PREFIX as a relative path under DESTDIR as opposed to an absolute
path.


Poppler
=======

As mentioned in the guidelines, there are several intricacies concerning the
poppler library.

In order to properly display PDF files without embedded fonts - and to conform
to the PDF standard - TeXworks packages must ensure that the base 14 fonts are
available on the system. The preferable way to do that is to pull in system
packages and/or use alternative fonts found on the system. The remaining files
can be obtained, e.g., from http://www.ctan.org/tex-archive/fonts/urw/base35
(note that those fonts have been renamed according to
http://www.tug.org/fontname/html/URW-fonts.html which must be undone as poppler
expects the original filenames). The following pfb files are needed:
d050000l.pfb, n019003l.pfb, n019004l.pfb, n019023l.pfb, n019024l.pfb,
n021003l.pfb, n021004l.pfb, n021023l.pfb, n021024l.pfb, n022003l.pfb,
n022004l.pfb, n022023l.pfb, n022024l.pfb, s050000l.pfb.

If you provide the base 14 fonts yourself, you need to make sure poppler picks
them up. To achieve that, you most likely will need to patch poppler
accordingly. See lib-patches/poppler-win32-font-handling.patch for an example
for poppler-0.16 on Windows.

To check if the fonts are picked up correctly, use the base14-fonts testcase
from https://github.com/TeXworks/texworks/tree/master/testcases.

Moreover, the poppler library needs the poppler-data from
http://poppler.freedesktop.org/ (this particularly affects displaying CJK
documents). By default, TeXworks looks for a folder named "poppler-data"
alongside the main application on Windows and Mac (see src/TWApp.cpp -
TWApp::init()). It only sets this directory once while starting up, however, so
you need ensure poppler doesn't mess with it by building poppler with the
lib-patches/poppler-qt4-globalparams.patch patch.

To check if poppler-data is picked up properly, use the poppler-data testcase
from https://github.com/TeXworks/texworks/tree/master/testcases.


Other libraries and patches
===========================

 * Qt 4.7.0 and 4.7.1 have a bug crashing TeXworks occasionally when using the
   "Highlight current line" feature together with "Wrap Lines" due to a memory
   overflow. Use lib-patches/qt-4_7-qpathclipper.patch to fix that.


Further information and help
============================

Homepage:     http://www.tug.org/texworks/
Development:  https://github.com/TeXworks/texworks
Bugs:         https://github.com/TeXworks/texworks/issues
Mailing list: http://tug.org/mailman/listinfo/texworks
