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         - Disable the LYX_EXTERNAL_DTL option
  93
  94         - Enable the LYX_INSTALL option and click Configure.
  95
  96         - Click Generate.
  97
  98 7       Compile
  99
 100         A Microsoft Visual C++ solution should has been generated at
 101         C:\LyX\build\lyx.sln
 102         - Open the lyx.sln by double-clicking on it
 103         - This solution file contains multiple projects in different folders.
 104         - In solution explorer find the project "INSTALL" in the "CMakeTargets" folder, rightlick > Build
 105         - If you get an error, that something has failed, try going Build > Build solution at the top menu bar
 106           and then rebuild the INSTALL project
 107
 108
 109 8       Copy dependencies
 110
 111         - Compiling the INSTALL project creates the folder C:\LyX\build\LYX_INSTALLED containing the files
 112           needed to run LyX
 113
 114         - Copy these folders:
 115         C:\LyX\lyx-windows-deps-msvc2017\bin
 116         C:\LyX\lyx-windows-deps-msvc2017\imagemagick
 117         C:\LyX\lyx-windows-deps-msvc2017\Python
 118         C:\LyX\lyx-windows-deps-msvc2017\ghostscript
 119         C:\LyX\lyx-windows-deps-msvc2017\Resources
 120         to C:\LyX\build\LYX_INSTALLED
 121         (allow the request to overwrite)
 122
 123         - Go to the Qt-kit directory, which you have specified as CMAKE_PREFIX_PATH, enter the bin folder
 124           Copy these files:
 125         Qt5Core.dll
 126         Qt5Gui.dll
 127         Qt5Svg.dll
 128         Qt5Widgets.dll
 129         Qt5WinExtras.dll
 130         Qt5Cored.dll (if compiling Debug version)
 131         Qt5Guid.dll (if compiling Debug version)
 132         Qt5Svgd.dll (if compiling Debug version)
 133         Qt5Widgetsd.dll (if compiling Debug version)
 134         Qt5WinExtrasd.dll (if compiling Debug version)
 135         to C:\LyX\build\LYX_INSTALLED\bin
 136
 137         - Go to the Qt-kit directory, which you have specified as CMAKE_PREFIX_PATH, enter the plugins folder
 138           Copy these subdirectories:
 139         iconengines
 140         imageformats
 141         platforms
 142         styles
 143         to C:\LyX\build\LYX_INSTALLED\bin
 144
 145 9       Start LyX
 146
 147         C:\LyX\build\LYX_INSTALLED\bin\lyx.exe
 148
 149 10      Define path prefix
 150
 151         In LyX use the menu Tools->Preferences
 152         There input the the following the the field "Path prefix":
 153
 154         "$LyXDir\bin;$LyXDir\Python;$LyXDir\imagemagick;$LyXDir\ghostscript"
 155
 156         You may also add the location of your LaTeX installation if it's not on the
 157         system PATH, and the location of JabRef.
 158
 159
 160 Debugging
 161 =========
 162
 163         - Open LyX.sln
 164
 165         - In Solution Explorer open applications\LyX\LyX\main.cpp, the main function is the entry point,
 166           you can e.g. place breakpoints in there.
 167
 168         - On the menu bar in Solution Explorer there is a button "Switch Views", click on that and choose "Folder view"
 169           (to go back to normal view, click Switch Views again and choose "LyX.sln")
 170
 171         - In folder view find "LyX.exe" in "LYX_INSTALLED\bin" folder, rightclick > Set as Startup Item
 172
 173         - Start debugging with F5, clicking the Debug button (it shows now "LyX.exe") or rigchtlicking on LyX.exe in
 174           Solution Explorer - Folder View and choosing "Debug".
 175           (Starting debugging will have to be always with active Folder View. Attempting to start debugging with
 176           normal view active will start LyX.exe located in e.g. C:\LyX\build\bin\Debug, it won't find the dependencies
 177           and will therefore fail. Once debugging has started you can switch back to normal view of the Solution Explorer)
 178
 179         - Don't forget to build the INSTALL project each time you change the source code.
 180
 181
 182 Creating a patch file containing a bugfix
 183 =========================================
 184
 185         If you managed to fix a bug but dont have the rights to push your commits, you will want to create a patch file
 186         and share it with other developers. To do so you will have to do following:
 187
 188         - Make sure you are working on the newest versions, pull from git before you start bugfixing.
 189
 190         - 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
 191           put the Ticket nr. as description.
 192
 193         - Use this command in git bash:
 194         git format-patch -1 HEAD
 195         it will create a patch file in your repository folder, this is what you share.
 196
 197
 198 Creating the Installer
 199 ======================
 200
 201         - The installer is done with NSIS from http://nsis.sourceforge.net
 202         - In the LyX source directory, go to development\Win32\packaging\installer
 203         - Follow the steps in the file Readme.txt
 204
 205
 206 Compiling with GCC with MinGW64 + MSYS2 Environment using autotools
 207 ===================================================================
 208 1       Install MSYS2, MINGW64, Qt5+
 209         https://wiki.qt.io/MSYS2
 210 2       Install bc (Bench calculater), which autotools uses for some reason to compile LyX
 211         pacman -S bc
 212 3       Run the standard autotools install (Adapt paths and arguments accordingly)
 213         ./autogen.sh
 214          ./configure --without-x --enable-qt5 --disable-debug --enable-optimization --prefix=/mingw64
 215         make
 216         make install
 217
 218
 219 Cross-Compiling on unix with MXE using autotools
 220 =================================================
 221 1       Install MXE: http://mxe.cc
 222         You can either install from sources, the generic .tar binaries or debian .deb packages.
 223         Installing the following .deb packages will drag in all needed dependencies:
 224                 mxe-x86-64-w64-mingw32.shared-file
 225                 mxe-x86-64-w64-mingw32.shared-gcc
 226                 mxe-x86-64-w64-mingw32.shared-libiconv
 227                 mxe-x86-64-w64-mingw32.shared-qtimageformats
 228                 mxe-x86-64-w64-mingw32.shared-qtsvg
 229                 mxe-x86-64-w64-mingw32.shared-qtwinextras
 230         Of course you can also use the static and/or 32bit versions.
 231 2       Run the standard autotools install (Adapt paths and arguments accordingly)
 232         ./autogen.sh
 233         mkdir builddir-mingw
 234         cd builddir-mingw
 235         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
 236         PATH="/usr/lib/mxe/usr/bin:$PATH" make
 237         PATH="/usr/lib/mxe/usr/bin:$PATH" DESTDIR=/tmp/lyxinstall make install
 238         This uses the paths from the 64bit shared MXE version installed from .deb packages.
 239 3       If you want to run the resulting lyx.exe from the build directory using wine,
 240         create symlinks for all needed .dlls:
 241         cd builddir-mingw/src
 242         ln -s /usr/lib/mxe/usr/x86_64-w64-mingw32.shared/bin/*.dll .
 243         ln -s /usr/lib/mxe/usr/x86_64-w64-mingw32.shared/qt5/bin/*.dll .
 244         wine64 lyx.exe
 245