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