• View
• Edit
• Upload
• History
• Print

LyX on Cygwin

This page describes how to use LyX under Cygwin on Windows by building Qt/Win and LyX from source using Cygwin tools. If you don't want or need to compile LyX yourself, you can download an archive from the binary distribution site ftp://ftp.lyx.org/pub/lyx/bin/, un-tar it (using the cygwin tar, not native tools), and follow the instructions. Note that official Cygwin packages for the various Qt4 libraries are available in the Cygwin distribution for the X11 backend, so, if you want a Qt4/X11 version, you can simply install one or more of those. Instead, if you want a cygwin version of Qt4 but using the native Windows graphics backend, you can continue reading.

1.  Building Qt and LyX

Please note that the procedure outlined here applies to Qt 4.8.6 only. It cannot be used with a different version, unless you adapt the provided patches. Also note that this Qt4 port has mainly been tested with LyX but it is believed to be a fairly complete port.

1.1  Cygwin packages

We need quite a slew of tools to build Qt and LyX. Be sure to install at least the cygwin packages listed below. Due to a dependency mechanism, all other tools not listed here should also be marked for installation (I hope I forgot nothing).

• bc
• bison
• cygport
• file-devel
• gcc-g++
• gettext-devel
• libaspell-devel
• libbz2-devel
• libdbus1-devel
• libexpat1-devel
• libiodbc-devel
• libjpeg-devel
• libturbojpeg-devel
• libmng-devel
• libmysqlclient-devel
• libpng-devel
• libpcre-devel
• libpq5
• libpq-devel
• libsqlite3-devel
• libsybdb-devel
• libtiff-devel
• libxml2-devel
• m4
• make
• openssl-devel
• patch
• pkg-config
• python
• wget

Instead of using the setup program, if you've installed wget you can install everything from the command line using the apt-cyg script:

wget https://raw.githubusercontent.com/transcode-open/apt-cyg/master/apt-cyg
install apt-cyg /usr/local/bin
apt-cyg install bc bison cygport file-devel gcc-g++ gettext-devel      \
    libaspell-devel libbz2-devel libdbus1-devel libexpat1-devel        \
    libiodbc-devel libjpeg-devel libturbojpeg-devel libmng-devel       \
    libmysqlclient-devel libpng-devel libpcre-devel libpq5 libpq-devel \
    libsqlite3-devel libsybdb-devel libtiff-devel libxml2-devel m4     \
    make openssl-devel patch pkg-config python

1.2  Cygport

We will be using cygport to build all packages. For not cluttering the main tree, we will be installing things into /usr/local. Unfortunately, cygport is thought for building official Cygwin packages that install into /usr. Thus, we need to apply a small patch. Download cygport.diff and apply it as follows:

cd /usr/share/cygport/lib
wget http://www.lyx.org/images/svnwiki/cygwin/cygport.diff
patch -p0 < cygport.diff

1.3  Cygspawn

LyX uses the Qt4 QProcess class for launching external programs. The Qt4 implementantion of QProcess uses the fork call, which is quite expensive on Cygwin. We will be patching Qt4 such that QProcess will use an efficient and POSIX-compliant user-mode implementation of posix_spawn that improves process-creation performance considerably. Thus, before building the Qt4 libraries, we need to compile and install cygspawn. Download the archive cygspawn.tar.gz and unpack it in /usr/local/src:

mkdir /usr/local/src
cd /usr/local/src
wget http://www.lyx.org/images/svnwiki/cygwin/cygspawn.tar.gz
tar xvf cygspawn.tar.gz

Now build the cygspawn and cygspawn-devel packages by issuing the following commands:

cd /usr/local/src/cygspawn
cygport cygspawn.cygport download  # download the source from github
cygport cygspawn.cygport all       # apply patches and make the cygwin packages

You should now find the cygspawn and cygspawn-devel packages in <workdir>/dist/cygspawn, where <workdir> is the work directory created by cygport, which is typically named as packagename-version.arch. Here, packagename and version are obvious, while arch is i686 for 32-bit, but x86_64 for 64-bit cygwin. Thus, if you are using 32-bit cygwin, the packages will be in cygspawn-1.0.0-3.i686/dist/cygspawn, otherwise you will find them in cygspawn-1.0.0-3.x86_64/dist/cygspawn.

These packages could be installed by simply unpacking their archives from the root directory, but it is more convenient installing them through the cygwin installation tool (either setup-x86.exe or setup-x86_64.exe). This means that we need creating a local repository for cygwin packages. Suppose that we choose /setup/local as the directory of this local repository. If you are using 32-bit cygwin, create the directories

mkdir -p /setup/local/x86/dist

otherwise, if you are using 64-bit cygwin, create the directories

mkdir -p /setup/local/x86_64/dist

and then copy there the whole tree under <workdir>/dist/cygspawn, i.e.,

cp -r <workdir>/dist/cygspawn /setup/local/<arch>/dist

where you have to replace <workdir> and <arch> according to the architecture of your cygwin installation (32- or 64-bit). We now need creating an index that will be used by the setup program. Download the genini script in /usr/local/bin, make it executable and then launch it as follows (replace <arch> with x86 for 32-bit or with x86_64 for 64-bit):

cd /usr/local/bin
wget http://www.lyx.org/images/svnwiki/cygwin/genini
chmod a+rx genini
cd /setup/local
genini --recursive --release=local --output=<arch>/setup.ini <arch>

This will create the index file <arch>/setup.ini and we are now ready to launch the cygwin setup installation tool. After doing that, choose "Install from Local Directory", leave the "Root Directory" pointing to your cygwin installation, and then choose as "Local Package Directory" the local repository /setup/local (as the setup tool is a native program, this directory has to be specified in Windows form, probably as C:\cygwin\setup\local). You should now be able to select the cygspawn and cygspawn-devel packages for installation. After installing them, let us remove the work directory created by cygport, as it is not necessary anymore:

cd /usr/local/src/cygspawn
cygport cygspawn.cygport finish

1.4  Hunspell

LyX can use either aspell or hunspell as a spell checker. The aspell package is provided as an official Cygwin package but its selection of dictionaries is limited. Instead, dictionaries and thesauri files for hunspell are provided on the LyX website for a wide range of languages. Unfortunately, hunspell is not provided as an official Cygwin package. It could be installed from the cygwinports site, but it is also easily built from source. Download the archive hunspell.tar.gz and unpack it in /usr/local/src:

cd /usr/local/src
wget http://www.lyx.org/images/svnwiki/cygwin/hunspell.tar.gz
tar xvf hunspell.tar.gz

Now build the hunspell packages by issuing the following commands:

cd /usr/local/src/hunspell
cygport hunspell.cygport download  # download the source from sourceforge
cygport hunspell.cygport all       # apply patches and make the cygwin packages

Copy the whole tree under <workdir>/dist/hunspell to the local repository (again, replace <workdir> and <arch> as appropriate) and then cleanup the work directory:

cp -r <workdir>/dist/hunspell /setup/local/<arch>/dist
cygport hunspell.cygport finish

Afterwards, update the index for the setup installation tool

cd /setup/local
genini --recursive --release=local --output=<arch>/setup.ini <arch>

before launching it to install the libhunspell-devel package (this will also pull in the hunspell library).

We can now proceed to build the Qt4 libraries.

1.5  Qt4 Open Source Edition

The Qt4 libraries we are going to build use the native Windows graphics backend, not X11. Until some time ago, the official Cygwin repositories offered an opengl package to develop portable OpenGL programs that did not require an X server to run. This package was later declared obsoleted when OpenGL support was added to the Cygwin X server. However, we need this package for building a fully functional Qt4 port not relying on X11. So, download the opengl.tar.gz archive and unpack it in /setup/local/<arch>/dist (replace <arch> with x86 or x86_64, as appropriate):

cd /usr/local/src
wget http://www.lyx.org/images/svnwiki/cygwin/opengl.tar.gz
cd /setup/local/<arch>/dist
tar xvf /usr/local/src/opengl.tar.gz

Then, run again the genini script

cd /setup/local
genini --recursive --release=local --output=<arch>/setup.ini <arch>

and install the opengl package through the setup program by using again /setup/local as the "Local Package Directory".

We are now ready to build the Qt4 libraries.

1. Download the archive qt4win.tar.gz and unpack it in /usr/local/src:

   cd /usr/local/src
   wget http://www.lyx.org/images/svnwiki/cygwin/qt4win.tar.gz
   tar xvf qt4win.tar.gz
   
2. Build the Qt4 libraries by issuing the following commands:

   cd /usr/local/src/qt
   cygport qt4win.cygport download  # download the source from qt-project.org
   cygport qt4win.cygport all       # apply patches and make the cygwin packages
   

3. After cygport finished, copy the whole tree under <workdir>/dist/qt4win to the local repository (where, again, you have to replace <workdir> and <arch> according to the architecture of your cygwin installation):

   cp -r <workdir>/dist/qt4win /setup/local/<arch>/dist
   

cd /setup/local
genini --recursive --release=local --output=<arch>/setup.ini <arch>

4. Launch the cygwin setup program and install the required libraries for building LyX. You only need to install the libqt4-core-devel and libqt4-gui-devel packages and their dependencies (which are automatically pulled in).

After removing the work directory used for building the Qt4 libraries:

cd /usr/local/src/qt
cygport qt4win.cygport finish

we can move to building LyX.

1.6  LyX

1. Download the archive lyxwin.tar.gz and unpack it in /usr/local/src:

   cd /usr/local/src
   wget http://www.lyx.org/images/svnwiki/cygwin/lyxwin.tar.gz
   tar xvf lyxwin.tar.gz
   
2. Choose the LyX version you want to package by replacing the X below with the last digit in the version string (e.g., if you want LyX 2.1.2, replace X with 2):

   cd /usr/local/src/lyxwin
   sed -i -e 's/VERSION=.*/VERSION=2.1.X/' lyxwin.cygport
   

sed -i -e 's/running.patch/running.patch\n\t64bit.patch/' lyxwin.cygport

3. Download the sources and compile and package LyX

   cygport lyxwin.cygport download
   cygport lyxwin.cygport all
   
4. Copy the package directory to the local repository and cleanup the work directory:

   cp -r <workdir>/dist/LyXwin /setup/local/<arch>/dist
   cygport lyxwin.cygport finish
   
5. Update the index for the setup program:

   cd /setup/local
   genini --recursive --release=local --output=<arch>/setup.ini <arch>
   
6. Launch the cygwin setup program and install the LyXwin package.
7. As a finishing touch, download dictionaries and thesauri files for your language from http://www.lyx.org/trac/browser/dictionaries/trunk/dicts and http://www.lyx.org/trac/browser/dictionaries/trunk/thes (you need four files per language, those with extensions .aff and .dic for the dictionaries and .dat and .idx for the thesauri) and put them into the /usr/local/share/dict/ and /usr/local/share/thes/ directories, respectively. However, these locations can be configured in the preferences.

2.  Reverse DVI/PDF search

The reverse search feature (also called inverse search) allows the cursor in LyX to automatically jump to the point corresponding to a given position in the DVI or PDF file being previewed. When a reverse search is started (xdvi uses ctrl-click, whereas yap and SumatraPDF use double click), the viewer calls an external program or script with two arguments, a filename and a line number. The called program should pass this info to a running instance of LyX. This can be done through the LyX server either by using a named pipe (lyxpipe), or the unix domain socket (lyxsocket) that lyx creates in its temporary directory (this is the way the lyxclient program communicates with LyX).

The reverse search feature can be enabled in LyX as follows:

• For enabling reverse DVI search, change the LaTeX (plain)->DVI or LaTeX (plain)->DraftDVI converter in Tools->Preferences->File Handling->Converters to latex -src-specials $$i. As an alternative to redefining the converter, insert \usepackage[active]{srcltx} in the preamble of the LyX file.
• For enabling reverse PDF search, change the LaTeX (pdflatex)->PDF (pdflatex) converter in Tools->Preferences->File Handling->Converters to pdflatex --synctex=-1 $$i. As an alternative to redefining the converter, insert \usepackage{pdfsync} in the preamble. Note that only SumatraPDF supports reverse PDF search, currently. In order to allow both DVI and PDF reverse search, you can also insert in the preamble the following lines:

  \usepackage{ifpdf}
  \ifpdf
    \usepackage{pdfsync}
  \else
    \usepackage[active]{srcltx}
  \fi
  

  In this way, you can preview the file as either DVI or PDF (pdflatex) and the right package will be used.
• If you use xdvi, you don't need do anything else, as LyX already provides the necessary hooks for automatically using the lyxclient program. However, if for whatever reason you want to use the lyxpipe instead of the lyxsocket for communicating with LyX, simply change the DVI viewer in Tools->Preferences->File Handling->File formats to xdvi -editor 'lyxeditor %f %l', and be sure to specify the LyXServer pipe path in Tools->Preferences->Paths (a good choice is $HOME/.lyx/lyxpipe). You should find the lyxeditor.exe program in /usr/local/bin, as it is installed by default on Cygwin.
• If you use yap as a DVI viewer, you should make sure that it is your default DVI viewer in the Windows environment and then set the name of the program that communicates with LyX directly in yap as follows. After launching yap, choose its "View->Options" menu and select the "Inverse DVI Search" tab. Click on the "New..." button and, in the window which opens, enter "LyX Editor" (or any other name you like) in the "Name:" field. Now click on the button labeled "..." to open a filedialog and navigate to the directory containing the lyxeditor.exe program (most likely it is C:\cygwin\usr\local\bin). Select lyxeditor.exe and then specify the program arguments as -g %f %l. In this way you will be using the lyxsocket for communicating with LyX. If, for whatever reason, you want to use the lyxpipe, omit -g, and be sure to specify the LyXServer pipe path in the LyX preferences.
• In order to use SumatraPDF for inverse search, provided that SumatraPDF is in the PATH, enter SumatraPDF -inverse-search "lyxeditor -g %f %l" in the viewer setting in Tools->Preferences->File Handling->File formats->PDF (pdflatex). The -g enables communication via the lyxsocket (recommended); omit the -g option if you want to use the lyxpipe, and be sure to specify the LyXServer pipe path in the LyX preferences.

If you did no mistakes, and if src-specials are activated as previously described, whenever you ctrl-click in xdvi, or double click in yap or SumatraPDF, the cursor in LyX should jump to the desired location.

3.  Forward DVI/PDF search

The forward search feature allows you to let a dvi/pdf viewer jump (near) to a position corresponding to the cursor position in LyX. Forward search is enabled in the same way as reverse search is (see the previous section) but you also need to specify in the preferences a proper command for the used viewer. If you use one of the already supported viewers, you can do this by selecting one of the predefined commands in Tools->Preferences->Output->General. There, you will find the commands to be used with xdvi, yap, and SumatraPDF (if you don't have SumatraPDF 1.9 or a later version, you need the external command CMCDDE, downloadable from ftp://ftp2.commence.com/pub/freebies/). If you use a different viewer, you will have to check whether it supports forward search and manually enter the required command in Tools->Preferences->Output->General.

After positioning the cursor in LyX, a forward search is initiated by either the Navigate->Forward search main menu entry or the Forward search context menu entry.

If you use the cygwin texlive package, you will notice that forward search doesn't seem to work with SumatraPDF. Indeed, SumatraPDF is a native Windows program and thus it does not understand the posix paths that texlive inserts in the produced synctex file. However, the synctex file is a simple text file and thus can be easily modified with the sed program. In this case, you can use the following script as your pdf viewer. Give it the name SumatraPDF.sh, make it executable and place it in the PATH, for example, in /usr/local/bin. Then enter SumatraPDF.sh in the viewer setting in Tools->Preferences->File Handling->File formats->PDF (pdflatex). The script simply converts all paths in the synctex file to the Windows format before calling the real SumatraPDF program. It also takes care of the reverse search setting.

#!/bin/bash
pdfname=$(basename "$1")
stem=$(basename "$1" .pdf)
compressed=no
cd $(dirname "$1")
if [ -f "$stem.synctex.gz" ]; then
    compressed=yes
    gunzip "$stem.synctex.gz"
fi
if [ -f "$stem.synctex" ]; then
    sed -i -e '/^Input:/{h;s,^Input:.*:\(.*\)$,cygpath -m "\1",e;x;
        s,:\(.*\):.*$,:\1:,;G;s,\n,,;}' "$stem.synctex"
   if [ "$compressed" = "yes" ]; then
       gzip "$stem.synctex"
   fi
fi
SumatraPDF -inverse-search "lyxeditor -g %f %l" "$pdfname"

4.  Contributors

• Enrico Forestieri

5.  History

• 13 Feb 2006 - Created.
• 22 Feb 2006 - Updated lyxconfig-cygwin and qt3-cygwin.patch. Added a new patch for path_prefix handling.
• 23 Feb 2006 - Updated list of required cygwin packages.
• 24 Feb 2006 - Added a warning about the qt3-devel cygwin package and corrected a typo.
• 26 Feb 2006 - Added a fix for empty "TeX Information" dialog when using the tetex cygwin package.
• 12 Apr 2006 - Updated patches and build procedure.
• 13 Jan 2007 - Updated to cover changes in LyX 1.4.3 and added the winpaths patch.
• 14 Aug 2007 - Updated for LyX 1.5 and Qt4.
• 11 Jan 2008 - Updated for Qt 4.3.3.
• 08 May 2009 - Updated for LyX 1.6 and Qt 4.5.1.
• 04 July 2009 - Updated for Qt 4.5.2.
• 08 Oct 2009 - Updated for LyX 1.6.5 and Qt 4.5.3.
• 15 Jan 2010 - Updated for Qt 4.6.0.
• 06 Mar 2010 - Updated for Qt 4.6.2.
• 22 May 2011 - Updated for LyX 2.0 and Qt 4.7.3.
• 28 Feb 2012 - Updated for Qt 4.7.4.
• 15 Aug 2014 - Updated for LyX 2.1 and Qt 4.8.6.

Cygwin