BRL-CAD on Windows README
=========================

The usual way to build BRL-CAD for Windows is to use the CMake build
system generator and the Microsoft Visual Studio C++ (MSVC) compiler.
Recent versions of both are recommended.  If generating an installer,
the following options are available and supported:

Nullsoft Scriptable Install System (NSIS) - generates a. .exe installer

WiX Toolset - generates an MSI installer.

These tools must be installed separately - they are not included with
CMake or Visual Studio.

Note:  In principle BRL-CAD can be built using CMake and environments
like Cygwin and/or Mingw/Msys, but they are largely untested and
infrequently supported.  Enhancements or bug reports are welcome.

Visual Studio
-------------

To build with CMake and Visual Studio, the first step is to obtain the
BRL-CAD sources and create a build directory.  In principle, it is not
*required* to have a separate build directory, but with Windows and
Visual Studio this is the only tested configuration.  Once those the
sources are obtained and the build directory is created, run the CMake
application and specify the source and build directories.

Once CMake has the correct directory settings, select Configure.  If
this is the first time running Configure with this build directory,
CMake will prompt you to select a generator.  Look for your version of
Visual Studio and select it.  Configuration should now proceed.

It is normal for configuration to be a long process on Windows.  Once
it is complete, you should see a list of red highlighted entries
appear in the CMake interface.  Change any settings that appear to
need changing and press Configure again.  The second pass should be
shorter.  If no new red lines appear, the configuration is complete.

The final CMake step, after completing Configuration, is to select
Generate to create Visual Studio project files in the build directory.
Once this is done, you may quit CMake.

Navigate to your build directory.  You should see a BRLCAD solution
file for Visual Studio.  Double-click that file, and Visual Studio
should launch.  It will load the targets (a default configuration of
BRL-CAD on Windows will generate over 800 of them) and a large list of
targets will appear.  To build everything look for a target named
ALL_BUILD.  Start compiling that target.

Once compilation is successfully complete, you can find the compiled
executables in a 'bin' directory in your build directory.  For
example, mged.exe would be in brlcad-svn-trunk\.build\Debug\bin if
brlcad-svn-trunk\.build is the build directory specified to CMake and
CMAKE_BUILD_TYPE was set to Debug.

You may want to produce an NSIS installer.  If so, locate a target
named PACKAGE and run it.  The end result should be an .exe file
capable of installing BRL-CAD.

Debugging with Visual Studio
----------------------------

For most compilation environments, BRL-CAD defines a Debug build
configuration which disables optimizations and a Release build that
enables them - although Debug builds are generally easier to use when
tracking down problems, both configurations keep debugging information.
This allows for easier diagnosis of problems in real-world use, as
well as diagnosis of issues that occur only when optimizations are
enabled.

MSVC and Windows present a more complicated situation. On that platform,
Debug versions of applications are not redistributable:
https://docs.microsoft.com/en-us/cpp/windows/determining-which-dlls-to-redistribute

As a consequence the default BRL-CAD build configuration for Release
(unlike other platforms) does not support debugging.

If it is necessary to debug a Release mode specific issue on Windows,
extra steps are needed.  Users of CMake may be familiar with the build
configuration RelWithDebInfo, which is normally disabled for BRL-CAD
builds - debugging a Release-mode-only problem is exactly the situation
in which this build configuration is needed.

To re-enable the availability of RelWithDebInfo for BRL-CAD builds, set
the compilation variable ENABLE_ALL_CONFIG_TYPES to ON - once set,
BRL-CAD's configure will no longer eliminate CMake build types other
than Debug and Release.

Working with MSI files
----------------------

The WiX Toolset's MSI file, in addition to the standard interactive
graphical install, also supports a command line based silent
install. (See, for example, https://stackoverflow.com/a/25230485)

msiexec.exe /i c:\BRL-CAD-7.32.0_win64.msi /QN /L*V "C:\Temp\brlcad_install.log"

The logging step is not required but is recommended to allow for
easier understanding of any issues that might arise.

===========================================

=== Setting a specific SDK version ===

If a particular version of the Windows SDK is needed, it is specified
with CMAKE_SYSTEM_VERSION (for example, to use 10.0.15063.0 the user
would define a New Entry in the CMake GUI before running configure,
make the variable CMAKE_SYSTEM_VERSION as a string type, and assign the
value of 10.0.15063.0.)

Note that for this to work the SDK version in question must be
installed on the system.  To see what versions are installed,
look for Windows SDK installs in the "Apps & Features" Setup
interface.

=======================================================

=== Tracking down the source of a header inclusion  ===

If a Windows system header is reporting an error, it can be helpful to identify
where the header is being included from.  By default MSVC doesn't report this,
but in Visual Studio there is a "ShowIncludes" setting that may be enabled to
find this information:

https://stackoverflow.com/a/1138045

This setting may also be added to the compilation flags directly
in CMake as "/showIncludes":

https://docs.microsoft.com/en-us/cpp/build/reference/showincludes-list-include-files

Note that the output of this can be very verbose, especially if applied
globally to all targets - you may want to consider applying it specifically to
an individual target with target_compile_options.  This flag is a very useful
tool when trying to determine *why* a particular header is present in an error
message.

=========================================================

=== Debugging build outputs from a Ninja compilation  ===

Normally, Visual Studio is used to debug Windows executables.  However,
another alternative is available called WinDbg:

https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-download-tools

This has been used successfully to debug Ninja produced executables.
Note that if debugging an issue unique to Release builds, you will
want to set the CMake variable ENABLE_ALL_CONFIG_TYPES to ON
and the specific build type to RelWithDebInfo

cmake.exe -G Ninja -ENABLE_ALL_CONFIG_TYPES=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo

===========================================

=== Notes on Visual Studio 14 2015 ===

In order to build this version (required to build the Creo 3 converter)
with CMake, you must ensure that Microsoft's "rc.exe" program is
installed and findable by CMake.

To install "rc.exe", run or re-run the Visual Studio installer and enable
Visual C++ components and "Visual Studio Extensibility Tools Update 1" under
the "Common Tools" section.

The extensibility tools can become unselected by default in some
configurations. Verify "rc.exe" is installed in:

"C:\Program Files (x86)\Windows Kits\8.1\bin\x64"

Add that directory to your "Path" user variable so CMake will be able to
locate the rc executable.

See:
https://stackoverflow.com/questions/43847542/rc-exe-no-longer-found-in-vs-2015-command-prompt

======================================


MINGW (WORK IN PROGRESS - THIS DOES NOT YET WORK!!!)
-----

After installing the MINGW system, set up as follows:

set path=%path%;"C:\Program Files (x86)\CMake\bin"
set path=%path%;C:\MinGW\bin

now make a build directory, and run CMake:

cmake ..\brlcad -G "MinGW Makefiles" -DBRLCAD_BUNDLED_LIBS=BUNDLED

mingw32-make

Note that you don't want to do this from an msys prompt that has
sh in the path.  (ConEmu can make using the standard Windows command
prompt a bit more tolerable:  http://conemu.github.io)

