=========================================================
xLights Windows build instructions
=========================================================

xLights can be built and run on Linux, Mac OS/X, or Windows. This
document describes how **developers** should set up their tool chain to build
xLights on Windows.

If you are a Windows user, installation packages are available at
https://xlights.org/releases/

xLights is written in C++ and uses the wxWidgets library as a
compatibility layer across operating systems.  The minimum required version
of wxWidgets for xLights is 3.1.5.  Do not use the pre-compiled
Windows binaries of wxWidgets, as these are for the Visual Studio IDE.

We support the VisualStudio/MS Visual C++ compiler for Windows builds.  Support for building with
MinGW/gcc on Windows is being slowly being removed and likely doesn't work.

Instructions for MS Visual Studio C++
=====================================

Here are the steps to compile xLights for Windows using the Visual Studio compiler.

  a) Install Visual Studio 2022 ... the community edition is fine
  	- Requires Windows 11 SDK build 22000

  b) Select a base directory to place all your source code in. From now on this is represented as <basedir>

  c) Download and build wxWidgets for Windows (currently using a patched version of 3.2.0)

    git clone  --recurse-submodules -b xlights_2024.06 https://github.com/xLightsSequencer/wxWidgets

     1) Also if you have built wxWidgets before you should delete the following 2 folders
        - <basedir>\wxWidgets\build\msw\vc_mswuddll
        - <basedir>\wxWidgets\build\msw\vc_mswudll
     2) Open the project <basedir>\wxWidgets\build\msw\wx_vc17.sln
     3) Also if you have built wxWidgets64 before you should delete the following 2 folders (if they exist) to force
        a rebuild using new configuration
        - wxWidgets\lib\vc_x64_dll
        - wxWidgets\lib\vc_x64_lib
     3) Compile both a release and a debug version
        NOTE: I have experienced issues with the use of spectre vs non spectre mitigated libraries. By default I turn spectre mitigation off which can be done in visual studio before building ... except the custom build step where the project file has to be manually added to tell it not to use it even though it doesnt need it. To do so copy the <SpectreMitigation>false</SpectreMitigation> tag under each of the PropertyGroup tags in the wx_custom_build.vcxproj file
     4) In the Windows System Properties -> Advanced -> Environment variables, create a new environment variable WXWIDGETS_ROOT with the value being the directory where wxWidgets is installed.  (example: c:\wxWidgets )

  d) Download and build xLights for Windows
       1) If you plan on contributing to the main repo, create a fork on GitHub
	   2) Now clone that fork to your <basedir>:
       
            cd <basedir>
            git clone  --recurse-submodules https://github.com/<youruser>/xLights.git
   
          NOTE: If you get an error or warning during this operation about certificates while getting log4cpp-codegit, follow these instructions:
		        a) Edit <basedir>\xLights\.gitmodules and remove the section <[submodule "dependencies/log4cpp-codegit"]> and its indented lines
				b) Edit <basedir>\xLights\.git\config  and remove the section <[submodule "dependencies/log4cpp-codegit"]> and its indented lines
				c) Run the command: git rm --cached dependencies/log4cpp-codegit
				d) Run the command: git submodule update --init
				e) Be sure not to submit these files in any PRs.
   
       3) Open the xLights project <basedir>\xLights\xLights\xLights.sln and build the project in x64 Debug mode
       4) Once built, copy the contents of these two folders (in the order below!):
            <basedir>\xLights\bin
            <basedir>\xLights\bin64
		  to the folder
		    <basedir>\xLights\xLights\x64\Debug
		  If you do a Release build, you'll also need to copy them into 
		    <basedir>\xLights\xLights\x64\Release

	   5) From now on you can Edit/Compile/Debug from within Visual Studio


Windows Installer
=================

    We use Inno Setup to create the setup.exe for xLights
    http://www.jrsoftware.org/isinfo.php

    You will find a xLights.iss file that is used to create the release setup.exe




The instructions below are for informational purpose right now as we deprecate and remove
support for building with mingw/gcc.   The information will be removed soon.


Instructions for MinGW 32 Bit
================================================

Here are the steps to compile xLights for Windows using the MinGW compiler.

  a) Install Code::Blocks for Windows (currently using version 20.03)

     Download and install the codeblocks-20.03-setup.exe file from here:
        http://www.codeblocks.org/downloads/binaries

  b) Install MinGW for Windows (currently using version 8.1.0)

     Download and install the ming-w64-install.exe file from here:
        Navigate to: https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/
        Click the i686-posix-dwarf link.

  b) wxWidgets for Windows (currently using a patched version of 3.2.0)

     git clone  --recurse-submodules -b xlights_2023.02 https://github.com/xLightsSequencer/wxWidgets

     1) Open a command prompt
     2) cd to the build\msw directory under your wxWidgets base directory
     3) Execute the command: SET Path=%PATH%;C:\Program Files (x86)\mingw-w64\i686-8.1.0-posix-dwarf-rt_v6-rev0\mingw32\bin
        Note: If your MinGW installation was placed in a different directory adjust the command above accordingly.
	 4) If you have previously built wxWidgets before and are using the same directory you will need to make the same change as above to the setup.h file in two
	    more locations: wxWidgets\lib\gcc_dll\mswu\wx\setup.h and wxWidgets\lib\gcc_dll\mswud\wx\setup.h.
	 5) Also if you have built wxWidgets before you should delete the following 2 folders to force the setup.h change to be included
		- wxWidgets\build\msw\gcc_mswudll
     6) run: mingw32-make -f makefile.gcc --debug TARGET_CPU=X86 GCCFLAGS="-m32" USE_QA=1 MONOLITHIC=0 SHARED=1 UNICODE=1 CXXFLAGS="-std=gnu++14 -m32" BUILD=release -j 10
			NOTE: If it fails the first time try it again ... and sometimes again
     7) You need to update your path environment variable to include C:\wxWidgets\lib\gcc_dll
        (assuming C:\wxWidgets is your wxWidgets base directory).

  c) In Code::Blocks:
     1) select Settings > Compiler
     2) click Search Directories tab
     3) Under Compiler, Search  sub-tab should be:
          $(#wx)\include
          $(#wx)\contrib\include
		  ffmpeg\include
		  ..\include
     4) Under Linker sub-tab should be:
          $(#wx)\lib\gcc_dll
		  ffmpeg\lib
     5) click Toolchain Executables tab
     6) Fill in the compiler's installation directory to your path to MinGW:
        example: C:\Program Files\mingw-w64\x86_64-8.1.0-posix-seh-rt_v6-rev0\mingw64
     7) Set C Compiler to gcc.exe, C++ compiler to g++.exe, Linker for dynamic libs to g++.exe,
        Linker for static libs to ar.exe, Debugger set to GDB..., resource compiler set to windres.exe,
        and Make program set to mingw32-make.exe.
     8) select Settings > Debugger
     9) click 'Default' under GDB/CDB debugger
     10) uncheck the box for 'Disable startup scripts...'
	 11) Update the path to gdb.exe similar to step 7 above
     12) select Settings > Global Variables
     13) Make sure "wx" is defined as described in the Code::Blocks documentation.
         wx should be set to your wxWidgets base directory. Just the "Base" field
         needs to be filled in - to something like "C:\wxWidgets",
         assuming that is where your copy of wxWidgets is located.

  d) Now you are ready to use Code::Blocks to build xLights
     by double-clicking on the cbp file in the xLights directory.
     Make sure you set the build target to MinGW_Debug or MinGW_Release!

Instructions for MinGW 64-bit
================================================

Here are the steps to compile xLights for Windows using the MinGW 64-bit compiler.

  a) Install Code::Blocks for Windows (currently using version 20.03)

     Download and install the codeblocks-20.03-setup.exe file from here:
        http://www.codeblocks.org/downloads/binaries

  b) Install MinGW for Windows (currently using version 8.1)

     Download and install the ming-w64-install.exe file from here:
        Navigate to: https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/
        Click the x86_64-posix-seh link.

  c) wxWidgets for Windows (currently using a patch of version 3.2.0)

     git clone  --recurse-submodules -b xlights_2023.02 https://github.com/xLightsSequencer/wxWidgets

     To compile it yourself:

     1) Open a command prompt
     2) cd to the build\msw directory under your wxWidgets64 base directory
     3) Execute the command: SET Path=%PATH%;C:\Program Files\mingw-w64\x86_64-8.1.0-posix-seh-rt_v6-rev0\mingw64\bin
        Note: If your MinGW installation was placed in a different directory adjust the command above accordingly.
	 4) Also if you have built wxWidgets64 before you should delete the following 2 folders to force the setup.h change to be included
		- wxWidgets\build\msw\gcc_mswudll
     5) run: mingw32-make -f makefile.gcc --debug TARGET_CPU=X64 USE_QA=1 MONOLITHIC=0 SHARED=1 UNICODE=1 CXXFLAGS="-std=gnu++14 -m64" BUILD=release -j 10
			NOTE: If it fails the first time try it again ... and sometimes again
     6) You need to update your path environment variable to include C:\wxWidgets\lib\gcc_dll
        (assuming C:\wxWidgets is your wxWidgets base directory).

  c) In Code::Blocks:
     1) select Settings > Compiler then with selected compiler as "GNU GCC Compiler"
        press the Copy button naming the new configuration gnu_gcc_64bit_compiler
     2) click Search Directories tab
     3) Under Compiler, Search  sub-tab should be:
          $(#wx64)\include
          $(#wx64)\contrib\include
     4) Under Linker sub-tab should be:
          $(#wx64)\lib\gcc_dll
     5) select Settings > Debugger
     6) click "GDB/CDB debugger" in the hiearchy which contains "Default" then press the Create Config button and name it GDB64
     7) uncheck the box for 'Disable startup scripts...'
     8) Fill in the Executable Path to your path to MinGW debugger executable then click OK:
        example: C:\Program Files\mingw-w64\x86_64-8.1.0-posix-seh-rt_v6-rev0\mingw64\bin\gdb.exe
     9) Go back to Settings > Compiler > select gnu_gcc_64bit_compiler > select tab Toolchain executables
     10) Fill in the compiler's installation directory to your path to MinGW:
         example: C:\Program Files\mingw-w64\x86_64-8.1.0-posix-seh-rt_v6-rev0\mingw64
     11) Set C Compiler to gcc.exe, C++ compiler to g++.exe, Linker for dynamic libs to g++.exe,
         Linker for static libs to ar.exe, Debugger set to GDB64 you created in step 6..., resource compiler set to windres.exe,
         and Make program set to mingw32-make.exe.
     12) select Settings > Global Variables
     13) Make sure "wx64" is defined as described in the Code::Blocks documentation.
         wx64 should be set to your wxWidgets64 base directory. Just the "Base" field
         needs to be filled in - to something like "C:\wxWidgets",
         assuming that is where your copy of wxWidgets is located.

  d) Now you are ready to use Code::Blocks to build xLights
     by double-clicking on the cbp file in the xLights directory.
     Make sure you set the build target to "64bit MinGW_Debug" or "64bit  MinGW_Release"!