=========================================================
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.
xLights used a forked version of wxWidgets code with some custom patches.(https://github.com/xLightsSequencer/wxWidgets)
Do not use the pre-compiled Windows binaries of wxWidgets, as these are for the Visual Studio IDE.
Use the "/build_scripts/msw/clone_&_build_WX_master_x64.cmd" script to download and build WX.

We support the Visual Studio/MS Visual C++ compiler for Windows builds. 

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>

**** Skip "c)" if Using the "clone_&_build_WX_master_x64.cmd" script ****
  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

*** Newer Solution Files should automatically do step 4) now, only preform if you encounter build failures ***
       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 Setting up Code::Blocks for Editing UI Files
================================================

Most the GUIs in xLights use .wxs files Generated by the wxSmith plugin in Code::Blocks.
Code::Blocks will auto-generate the .h/.cpp files from these .wxs files. Do not edit the code in the
generated sections as they will be overridden by Code::Blocks.

Here are the steps to Code::Blocks for Editing .wxs files in Windows.

  a) Install Code::Blocks nightly for Windows (currently using The 30 July 2024 build 13538)

     Download the codeblocks '.exe' and 'DLLs' from here:
        http://sourceforge.net/projects/codeblocks/files/Binaries/Nightlies/2024/CB_20240730_rev13538_win64.7z
	https://sourceforge.net/projects/codeblocks/files/Binaries/Nightlies/Prerequisites/wxmsw32u_gcc_cb_wx325_2D_gcc1410-mingw64.7z
	http://sourceforge.net/projects/codeblocks/files/Binaries/Nightlies/Prerequisites/Mingw64dlls14.1.0.7z

  b) Extract all the EXE and DLLs from above to one folder i.e "C:\Codeblocks_nightly_7_30"

  c) Launch 'codeblocks.exe' from the folder to open Code::Blocks
    
  d) Now you are ready to use Code::Blocks to Edit xLights UI Files
     by double-clicking on the .cbp file in the xLights directory.
     Then Open a Dialog, Panel, or Frame in the Left Panel to edit it.