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 the README and on http://code.google.com/p/texworks/w/list, 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). The 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). * 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 qmake. To set a variable VAR1=abc and VAR2=xyz, invoke qmake as qmake-qt4 'VAR1=abc' 'VAR2=xyz' TeXworks.pro 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. 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): INSTALL_PREFIX base prefix [/usr/local] BIN_DIR path to install the main program [INSTALL_PREFIX/bin] TW_PLUGINPATH path to install plugins [INSTALL_PREFIX/lib/texworks] DATA_DIR base prefix for data files [INSTALL_PREFIX/share] TW_HELPPATH path to install help files [DATA_DIR/texworks-help] TW_DICPATH path to look for spell checking files (dictionaries) [/usr/share/myspell/dicts] DOCS_DIR path to install general docs (README, NEWS, COPYING) [DATA_DIR/doc/texworks] ICON_DIR path to install icons [DATA_DIR/pixmaps] MAN_DIR path to install man files [DATA_DIR/man/man1] DESKTOP_DIR path to install .desktop files [DATA_DIR/applications] Note that generated Makefiles still honor the INSTALL_ROOT= directive to take INSTALL_PREFIX as a relative path under INSTALL_ROOT as opposed to an absolute path. Apart from these variables, qmake is controlled primarily by TeXworks.pro and similar .pro files in subdirectories. These contain all definitions and settings that you may need to change under special circumstances. E.g., they contain directives for finding and linking libraries that may need adjustment to suit your needs. Apart from that, the only line you should need to pay attention to is QMAKE_CXXFLAGS += -DHAVE_POPPLER_XPDF_HEADERS which needs to be commented if you don't have the xpdf headers provided by poppler. This entails that no custom poppler data will be supported (used on Windows and the Mac; requires a customized build of the poppler library - see below) and therefore is not recommended. 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 package 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 http://texworks.googlecode.com/svn/trunk/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 http://texworks.googlecode.com/svn/trunk/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: http://code.google.com/p/texworks/ Bugs: http://code.google.com/p/texworks/issues/list Mailing list: http://tug.org/mailman/listinfo/texworks