INSTALL.Win32

   1 Compiling LyX 2.4 for Win32 and creating Windows installer
   2 ==========================================================
   3
   4 It's recommended to compile LyX using Microsoft Visual C++ 2017 and CMake.
   5
   6
   7 Compiling with Microsoft Visual C++ (MSVC)
   8 ===================================
   9
  10         The easiest way to install LyX with MSVC is to follow this Wiki page:
  11
  12         http://wiki.lyx.org/Windows/Compilation
  13
  14         If you find there any errors please write a mail to the lyx-devel mailing list.
  15
  16 ----------------------------------------------------------------------------
  17
  18         The following instructions assume the LyX source code is in C:\LyX\repo
  19         You can also use another directory if you prefer.
  20         For repository cloning and version control you can use Git https://git-scm.com/download/win
  21         or the Team Explorer in Visual Studio 2019
  22
  23 1       Install MSVC 2019
  24
  25         If you don't have Visual C++ 2019 installed, get the free Community edition
  26         from https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=16
  27         You will need the Workload "Desktopdevelopment with C++" and you can also install Python 3
  28         (either selecting Python-Development workload or just Python 3 in the individual components tab)
  29         in the Visual Studio installer, so that you don't have to install it separately
  30
  31 2       Install Qt
  32
  33         Download the latest Qt online installer for Open Source development on Windows
  34         from https://qt.io/download-open-source/
  35         Qt 5.12.x is recommended, but 5.9.x or later versions should work as well.
  36         The newest Qt is 5.12.6, in the installer you will need to expand that category and mark MSVC 2017 32-bit and/or
  37         MSVC 2017 64-bit, depending on which versions of LyX you want to build.
  38         Note, you dont need to Install the "old" 2017 build tools in Visual Studio installer,
  39         the 2019 ones are compatible with MSVC 2017 kits installed with Qt.
  40         Qt should install in C:\Qt.
  41
  42 3       Install Python
  43
  44         Install the latest Python 3.x version from
  45         https://www.python.org/downloads/
  46         Assure that you use the installer option "Add Python 3.x to PATH"
  47         If you install Python through Visual Studio installer, just find it under Settings > Apps,
  48         select "Change" and enable the "Add to PATH" option; or add the path, in which the python.exe
  49         is located manually to the PATH environment variable, should be something like:
  50         C:\Program Files (x86)\Microsoft Visual Studio\Shared\Python37_64
  51
  52 4       Install CMake
  53
  54         Install the latest CMake from http://www.cmake.org
  55
  56 5       Download dependencies
  57
  58         Download the LyX for Windows build dependencies from
  59         ftp.lyx.de/LyXWinInstaller/lyx-windows-deps-msvc2017.zip
  60         and extract it e.g. to
  61         C:\LyX\lyx-windows-deps-msvc2017
  62         This is the later needed GNUWIN32 directory
  63
  64 6       Configure
  65
  66         - Open the CMake GUI
  67
  68         - Set the source code path to C:\LyX\repo
  69           Set the build path to e.g. C:\LyX\build
  70           Click Configure and set the generator to "Visual Studio 16 2019".
  71           Select the platform (Win32 or x64) you wish to compile for.
  72
  73         - Click on finish
  74
  75         - You will now get an error about missing GNUWIN32 directory.
  76
  77         - Set GNUWIN32_DIR to the folder that contains the dependencies.
  78           (This alternative does currently not work:
  79            Enable LYX_DEPENDENCIES_DOWNLOAD and click Configure.
  80            Pre-compiled dependencies will automatically be downloaded.)
  81
  82         - Set LYX_USE_QT to QT5.
  83
  84         - set CMAKE_PREFIX_PATH to the path of a Qt-kit
  85           e.g. to C:\Qt\5.12.6\msvc2017_64 or C:\Qt\5.12.6\msvc2017 depending on which platform you have chosen
  86           If you cant find this option, simply add a new entry of type "path" manually
  87
  88         - Enable the LYX_INSTALL option and click Configure.
  89
  90         - Click Generate.
  91
  92 7       Compile
  93
  94         A Microsoft Visual C++ solution should has been generated at
  95         C:\LyX\build\lyx.sln
  96         - Open the lyx.sln by double-clicking on it
  97         - This solution file contains multiple projects in different folders.
  98         - In solution explorer find the project "INSTALL" in the "CMakeTargets" folder, rightlick > Build
  99         - If you get an error, that something has failed, try going Build > Build solution at the top menu bar
 100           and then rebuild the INSTALL project
 101
 102
 103 8       Copy dependencies
 104
 105         - Compiling the INSTALL project creates the folder C:\LyX\build\LYX_INSTALLED containing the files
 106           needed to run LyX
 107
 108         - Copy these folders:
 109         C:\LyX\lyx-windows-deps-msvc2017\bin
 110         C:\LyX\lyx-windows-deps-msvc2017\imagemagick
 111         C:\LyX\lyx-windows-deps-msvc2017\Python
 112         C:\LyX\lyx-windows-deps-msvc2017\ghostscript
 113         C:\LyX\lyx-windows-deps-msvc2017\Resources
 114         to C:\LyX\build\LYX_INSTALLED
 115         (allow the request to overwrite)
 116
 117         - Go to the Qt-kit directory, which you have specified as CMAKE_PREFIX_PATH, enter the bin folder
 118           Copy these files:
 119         Qt5Core.dll
 120         Qt5Gui.dll
 121         Qt5Svg.dll
 122         Qt5Widgets.dll
 123         Qt5WinExtras.dll
 124         Qt5Cored.dll (if compiling Debug version)
 125         Qt5Guid.dll (if compiling Debug version)
 126         Qt5Svgd.dll (if compiling Debug version)
 127         Qt5Widgetsd.dll (if compiling Debug version)
 128         Qt5WinExtrasd.dll (if compiling Debug version)
 129         to C:\LyX\build\LYX_INSTALLED\bin
 130
 131         - Go to the Qt-kit directory, which you have specified as CMAKE_PREFIX_PATH, enter the plugins folder
 132           Copy these subdirectories:
 133         iconengines
 134         imageformats
 135         platforms
 136         styles
 137         to C:\LyX\build\LYX_INSTALLED\bin
 138
 139 9       Start LyX
 140
 141         C:\LyX\build\LYX_INSTALLED\bin\lyx.exe
 142
 143 10      Define path prefix
 144
 145         In LyX use the menu Tools->Preferences
 146         There input the the following the the field "Path prefix":
 147
 148         "$LyXDir\bin;$LyXDir\Python;$LyXDir\imagemagick;$LyXDir\ghostscript"
 149
 150         You may also add the location of your LaTeX installation if it's not on the
 151         system PATH, and the location of JabRef.
 152
 153
 154 Debugging
 155 =========
 156
 157         - Open LyX.sln
 158
 159         - In Solution Explorer open applications\LyX\LyX\main.cpp, the main function is the entry point,
 160           you can e.g. place breakpoints in there.
 161
 162         - On the menu bar in Solution Explorer there is a button "Switch Views", click on that and choose "Folder view"
 163           (to go back to normal view, click Switch Views again and choose "LyX.sln")
 164
 165         - In folder view find "LyX.exe" in "LYX_INSTALLED\bin" folder, rightclick > Set as Startup Item
 166
 167         - Start debugging with F5, clicking the Debug button (it shows now "LyX.exe") or rigchtlicking on LyX.exe in
 168           Solution Explorer - Folder View and choosing "Debug".
 169           (Starting debugging will have to be always with active Folder View. Attempting to start debugging with
 170           normal view active will start LyX.exe located in e.g. C:\LyX\build\bin\Debug, it won't find the dependencies
 171           and will therefore fail. Once debugging has started you can switch back to normal view of the Solution Explorer)
 172
 173
 174 Creating a patch file containing a bugfix
 175 =========================================
 176
 177         If you managed to fix a bug but dont have the rights to push your commits, you will want to create a patch file
 178         and share it with other developers. To do so you will have to do following:
 179
 180         - Make sure you are working on the newest versions, pull from git before you start bugfixing.
 181
 182         - After fixing a bug create a commit (it will be on your local repo and not on server), if there is a bugreport for it
 183           put the Ticket nr. as description.
 184
 185         - Use this command in git bash:
 186         git format-patch -1 HEAD
 187         it will create a patch file in your repository folder, this is what you share.
 188
 189
 190 Creating the Installer
 191 ======================
 192
 193         - Get NSIS from http://nsis.sourceforge.net
 194         - In the LyX source directory, go to development\Win32\packaging\installer
 195         - Follow the steps in the file Readme.txt
 196
 197
 198 Compiling with GCC with MinGW64 + MSYS2 Environment using autotools
 199 ===================================================================
 200 1       Install MSYS2, MINGW64, Qt5+
 201         https://wiki.qt.io/MSYS2
 202 2       Install bc (Bench calculater), which autotools uses for some reason to compile LyX
 203         pacman -S bc
 204 3       Run the standard autotools install (Adapt paths and arguments accordingly)
 205         ./autogen.sh
 206          ./configure --without-x --enable-qt5 --disable-debug --enable-optimization --prefix=/mingw64
 207         make
 208         make install
 209
 210
 211 Cross-Compiling on unix with MXE using autotools
 212 =================================================
 213 1       Install MXE: http://mxe.cc
 214         You can either install from sources, the generic .tar binaries or debian .deb packages.
 215         Installing the following .deb packages will drag in all needed dependencies:
 216                 mxe-x86-64-w64-mingw32.shared-file
 217                 mxe-x86-64-w64-mingw32.shared-gcc
 218                 mxe-x86-64-w64-mingw32.shared-libiconv
 219                 mxe-x86-64-w64-mingw32.shared-qtimageformats
 220                 mxe-x86-64-w64-mingw32.shared-qtsvg
 221                 mxe-x86-64-w64-mingw32.shared-qtwinextras
 222         Of course you can also use the static and/or 32bit versions.
 223 2       Run the standard autotools install (Adapt paths and arguments accordingly)
 224         ./autogen.sh
 225         mkdir builddir-mingw
 226         cd builddir-mingw
 227         PATH="/usr/lib/mxe/usr/bin:$PATH" ../configure --host=x86-64-w64-mingw32.shared --with-qt-dir=/usr/lib/mxe/usr/x86_64-w64-mingw32.shared/qt5 --enable-qt5 --with-included-boost --with-included-hunspell --with-included-mythes --disable-debug --enable-optimization --prefix=/mingw64
 228         PATH="/usr/lib/mxe/usr/bin:$PATH" make
 229         PATH="/usr/lib/mxe/usr/bin:$PATH" DESTDIR=/tmp/lyxinstall make install
 230         This uses the paths from the 64bit shared MXE version installed from .deb packages.
 231 3       If you want to run the resulting lyx.exe from the build directory using wine,
 232         create symlinks for all needed .dlls:
 233         cd builddir-mingw/src
 234         ln -s /usr/lib/mxe/usr/x86_64-w64-mingw32.shared/bin/*.dll .
 235         ln -s /usr/lib/mxe/usr/x86_64-w64-mingw32.shared/qt5/bin/*.dll .
 236         wine64 lyx.exe
 237