lyx_mirror/INSTALL.Win32

Compiling LyX 2.4 for Win32 and creating Windows installer
==========================================================

It's recommended to compile LyX using Microsoft Visual C++ 2017 and CMake.


Compiling with Microsoft Visual C++ (MSVC)
===================================

	The easiest way to install LyX with MSVC is to follow this Wiki page:
	
	http://wiki.lyx.org/Windows/Compilation
	
	If you find there any errors please write a mail to the lyx-devel mailing list.
	
----------------------------------------------------------------------------
	
	The following instructions assume the LyX source code is in C:\LyX\repo
	You can also use another directory if you prefer.
	For repository cloning and version control you can use Git https://git-scm.com/download/win
	or the Team Explorer in Visual Studio 2019

1	Install MSVC 2019

	If you don't have Visual C++ 2019 installed, get the free Community edition
	from https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=16
	You will need the Workload "Desktopdevelopment with C++" and you can also install Python 3
	(either selecting Python-Development workload or just Python 3 in the individual components tab)
	in the Visual Studio installer, so that you don't have to install it separately

	You may also want to install following extensions:
	- Qt Visual Studio Tools: enables preview of some Qt variables, like QString, while debugging
	- Concurrency Visualizer for Visual Studio: graphically shows which thread does what and when

2	Install Qt

	Download the latest Qt online installer for Open Source development on Windows
	from https://qt.io/download-open-source/
	Qt 5.12.x is recommended, but 5.9.x or later versions should work as well.
	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
	MSVC 2017 64-bit, depending on which versions of LyX you want to build.
	Qt6 only delivers prebuild 64 bit binaries. If you install Qt6, you will also need to check
	"Qt 5 Compatiblity Module"
	Note, you dont need to Install the "old" 2017 build tools in Visual Studio installer,
	the 2019 ones are compatible with MSVC 2017 kits installed with Qt.
	Qt should install in C:\Qt.

3	Install Python

	Install the latest Python 3.x version from
	https://www.python.org/downloads/
	Assure that you use the installer option "Add Python 3.x to PATH"
	If you install Python through Visual Studio installer, just find it under Settings > Apps,
	select "Change" and enable the "Add to PATH" option; or add the path, in which the python.exe
	is located manually to the PATH environment variable, should be something like:
	C:\Program Files (x86)\Microsoft Visual Studio\Shared\Python37_64

4	Install CMake

	Install the latest CMake from http://www.cmake.org

5	Download dependencies

	Download the LyX for Windows build dependencies from
	http://ftp.lyx.org/pub/lyx/devel/win_deps/
	there are 64 (lyx-windows-deps-msvc2019_64.zip) and 32 (lyx-windows-deps-msvc2019_32.zip) bit dependencies
	and extract it e.g. to 
	C:\LyX
	This is the later needed GNUWIN32 directory

6	Configure

	- Open the CMake GUI
	
	- Set the source code path to C:\LyX\repo
	  Set the build path to e.g. C:\LyX\build
	  Click Configure and set the generator to "Visual Studio 16 2019".
	  Select the platform (Win32 or x64) you wish to compile for.

	- Click on finish
	
	- You will now get an error about missing GNUWIN32 directory.

	- Set GNUWIN32_DIR to the folder that contains the dependencies (keep the bit version in mind).
	  (This alternative does currently not work:
	   Enable LYX_DEPENDENCIES_DOWNLOAD and click Configure.
	   Pre-compiled dependencies will automatically be downloaded.)

	- Set LYX_USE_QT to QT5 or Qt6 depending with which one you want to compile.
	
	- set CMAKE_PREFIX_PATH to the path of a Qt-kit
	  e.g. to C:\Qt\5.12.6\msvc2017_64 or C:\Qt\5.12.6\msvc2017 or C:\Qt\6.1.0\msvc2019_64
	  depending on which platform you have chosen
	  If you cant find this option, simply add a new entry of type "path" manually

	- Disable the LYX_EXTERNAL_DTL option

	- Enable the LYX_INSTALL option and click Configure.

	- Click Generate.

7	Compile

	A Microsoft Visual C++ solution should has been generated at
	C:\LyX\build\lyx.sln
	- Open the lyx.sln by double-clicking on it
	- This solution file contains multiple projects in different folders.
	- In solution explorer find the project "INSTALL" in the "CMakeTargets" folder, rightlick > Build
	- If you get an error, that something has failed, try going Build > Build solution at the top menu bar
	  and then rebuild the INSTALL project
	  

8	Copy dependencies

	- Compiling the INSTALL project creates the folder C:\LyX\build\LYX_INSTALLED containing the files 
	  needed to run LyX

	- Copy these folders:
	C:\LyX\lyx-windows-deps-msvc2017\bin
	C:\LyX\lyx-windows-deps-msvc2017\imagemagick
	C:\LyX\lyx-windows-deps-msvc2017\Python
	C:\LyX\lyx-windows-deps-msvc2017\ghostscript
	C:\LyX\lyx-windows-deps-msvc2017\Resources
	to C:\LyX\build\LYX_INSTALLED
	(allow the request to overwrite)

	- Go to the Qt-kit directory, which you have specified as CMAKE_PREFIX_PATH, enter the bin folder
	  Copy these files:
	Qt5Core.dll
	Qt5Gui.dll
	Qt5Svg.dll
	Qt5Widgets.dll
	Qt5WinExtras.dll
	Qt6Core5Compat.dll (if compiling with Qt6)
	Qt5Cored.dll (if compiling Debug version)
	Qt5Guid.dll (if compiling Debug version)
	Qt5Svgd.dll (if compiling Debug version)
	Qt5Widgetsd.dll (if compiling Debug version)
	Qt5WinExtrasd.dll (if compiling Debug version)
	Qt6Core5Compatd.dll (if compiling with Qt6 and debug version)
	to C:\LyX\build\LYX_INSTALLED\bin
	
	- Go to the Qt-kit directory, which you have specified as CMAKE_PREFIX_PATH, enter the plugins folder
	  Copy these subdirectories: 
	iconengines
	imageformats
	platforms
	styles
	to C:\LyX\build\LYX_INSTALLED\bin

9	Start LyX

	C:\LyX\build\LYX_INSTALLED\bin\lyx.exe

10	Define path prefix

	In LyX use the menu Tools->Preferences
	There input the the following the the field "Path prefix":

	"$LyXDir\bin;$LyXDir\Python;$LyXDir\imagemagick;$LyXDir\ghostscript"

	You may also add the location of your LaTeX installation if it's not on the
	system PATH, and the location of JabRef.


Debugging
=========

	- Open LyX.sln

	- In Solution Explorer open applications\LyX\LyX\main.cpp, the main function is the entry point,
	  you can e.g. place breakpoints in there.

	- On the menu bar in Solution Explorer there is a button "Switch Views", click on that and choose "Folder view"
	  (to go back to normal view, click Switch Views again and choose "LyX.sln")

	- In folder view find "LyX.exe" in "LYX_INSTALLED\bin" folder, rightclick > Set as Startup Item

	- Start debugging with F5, clicking the Debug button (it shows now "LyX.exe") or rigchtlicking on LyX.exe in 
	  Solution Explorer - Folder View and choosing "Debug".
	  (Starting debugging will have to be always with active Folder View. Attempting to start debugging with 
	  normal view active will start LyX.exe located in e.g. C:\LyX\build\bin\Debug, it won't find the dependencies
	  and will therefore fail. Once debugging has started you can switch back to normal view of the Solution Explorer)

	- Don't forget to build the INSTALL project each time you change the source code.


Creating a patch file containing a bugfix
=========================================

	If you managed to fix a bug but dont have the rights to push your commits, you will want to create a patch file
	and share it with other developers. To do so you will have to do following:

	- Make sure you are working on the newest versions, pull from git before you start bugfixing.

	- After fixing a bug create a commit (it will be on your local repo and not on server), choose an approproate description, 
	  e.g. the ticket nr. if there is a bugreport for it

	- Use this command in git bash:
	git format-patch -1 HEAD
	it will create a patch file in your repository folder, this is what you share.

	Another usefull command is
	git diff --cached > file.diff
	which will create a .diff file of staged changes. There is no option for the description with it though.


Creating the Installer
======================

	- The installer is done with NSIS from http://nsis.sourceforge.net
	- In the LyX source directory, go to development\Win32\packaging\installer
	- Follow the steps in the file Readme.txt


Compiling with GCC with MinGW64 + MSYS2 Environment using autotools
===================================================================
1	Install MSYS2, MINGW64, Qt5+
	https://wiki.qt.io/MSYS2
2	Install bc (Bench calculater), which autotools uses for some reason to compile LyX
	pacman -S bc
3	Run the standard autotools install (Adapt paths and arguments accordingly)
	./autogen.sh
	 ./configure --without-x --enable-qt5 --disable-debug --enable-optimization --prefix=/mingw64
	make
	make install


Cross-Compiling on unix with MXE using autotools
=================================================
1	Install MXE: http://mxe.cc
	You can either install from sources, the generic .tar binaries or debian .deb packages.
	Installing the following .deb packages will drag in all needed dependencies:
		mxe-x86-64-w64-mingw32.shared-file
		mxe-x86-64-w64-mingw32.shared-gcc
		mxe-x86-64-w64-mingw32.shared-libiconv
		mxe-x86-64-w64-mingw32.shared-qtimageformats
		mxe-x86-64-w64-mingw32.shared-qtsvg
		mxe-x86-64-w64-mingw32.shared-qtwinextras
	Of course you can also use the static and/or 32bit versions.
2	Run the standard autotools install (Adapt paths and arguments accordingly)
	./autogen.sh
	mkdir builddir-mingw
	cd builddir-mingw
	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
	PATH="/usr/lib/mxe/usr/bin:$PATH" make
	PATH="/usr/lib/mxe/usr/bin:$PATH" DESTDIR=/tmp/lyxinstall make install
	This uses the paths from the 64bit shared MXE version installed from .deb packages.
3	If you want to run the resulting lyx.exe from the build directory using wine,
	create symlinks for all needed .dlls:
	cd builddir-mingw/src
	ln -s /usr/lib/mxe/usr/x86_64-w64-mingw32.shared/bin/*.dll .
	ln -s /usr/lib/mxe/usr/x86_64-w64-mingw32.shared/qt5/bin/*.dll .
	wine64 lyx.exe