"Fossies" - the Fresh Open Source Software Archive

Member "brlcad-7.32.4/doc/README.Windows" (29 Jul 2021, 8138 Bytes) of package /linux/misc/brlcad-7.32.4.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "README.Windows": 7.32.0_vs_7.32.2.

    1 BRL-CAD on Windows README
    2 =========================
    3 
    4 The usual way to build BRL-CAD for Windows is to use the CMake build
    5 system generator and the Microsoft Visual Studio C++ (MSVC) compiler.
    6 Recent versions of both are recommended.  If generating an installer,
    7 the following options are available and supported:
    8 
    9 Nullsoft Scriptable Install System (NSIS) - generates a. .exe installer
   10 
   11 WiX Toolset - generates an MSI installer.
   12 
   13 These tools must be installed separately - they are not included with
   14 CMake or Visual Studio.
   15 
   16 Note:  In principle BRL-CAD can be built using CMake and environments
   17 like Cygwin and/or Mingw/Msys, but they are largely untested and
   18 infrequently supported.  Enhancements or bug reports are welcome.
   19 
   20 Visual Studio
   21 -------------
   22 
   23 To build with CMake and Visual Studio, the first step is to obtain the
   24 BRL-CAD sources and create a build directory.  In principle, it is not
   25 *required* to have a separate build directory, but with Windows and
   26 Visual Studio this is the only tested configuration.  Once those the
   27 sources are obtained and the build directory is created, run the CMake
   28 application and specify the source and build directories.
   29 
   30 Once CMake has the correct directory settings, select Configure.  If
   31 this is the first time running Configure with this build directory,
   32 CMake will prompt you to select a generator.  Look for your version of
   33 Visual Studio and select it.  Configuration should now proceed.
   34 
   35 It is normal for configuration to be a long process on Windows.  Once
   36 it is complete, you should see a list of red highlighted entries
   37 appear in the CMake interface.  Change any settings that appear to
   38 need changing and press Configure again.  The second pass should be
   39 shorter.  If no new red lines appear, the configuration is complete.
   40 
   41 The final CMake step, after completing Configuration, is to select
   42 Generate to create Visual Studio project files in the build directory.
   43 Once this is done, you may quit CMake.
   44 
   45 Navigate to your build directory.  You should see a BRLCAD solution
   46 file for Visual Studio.  Double-click that file, and Visual Studio
   47 should launch.  It will load the targets (a default configuration of
   48 BRL-CAD on Windows will generate over 800 of them) and a large list of
   49 targets will appear.  To build everything look for a target named
   50 ALL_BUILD.  Start compiling that target.
   51 
   52 Once compilation is successfully complete, you can find the compiled
   53 executables in a 'bin' directory in your build directory.  For
   54 example, mged.exe would be in brlcad-svn-trunk\.build\Debug\bin if
   55 brlcad-svn-trunk\.build is the build directory specified to CMake and
   56 CMAKE_BUILD_TYPE was set to Debug.
   57 
   58 You may want to produce an NSIS installer.  If so, locate a target
   59 named PACKAGE and run it.  The end result should be an .exe file
   60 capable of installing BRL-CAD.
   61 
   62 Debugging with Visual Studio
   63 ----------------------------
   64 
   65 For most compilation environments, BRL-CAD defines a Debug build
   66 configuration which disables optimizations and a Release build that
   67 enables them - although Debug builds are generally easier to use when
   68 tracking down problems, both configurations keep debugging information.
   69 This allows for easier diagnosis of problems in real-world use, as
   70 well as diagnosis of issues that occur only when optimizations are
   71 enabled.
   72 
   73 MSVC and Windows present a more complicated situation. On that platform,
   74 Debug versions of applications are not redistributable:
   75 https://docs.microsoft.com/en-us/cpp/windows/determining-which-dlls-to-redistribute
   76 
   77 As a consequence the default BRL-CAD build configuration for Release
   78 (unlike other platforms) does not support debugging.
   79 
   80 If it is necessary to debug a Release mode specific issue on Windows,
   81 extra steps are needed.  Users of CMake may be familiar with the build
   82 configuration RelWithDebInfo, which is normally disabled for BRL-CAD
   83 builds - debugging a Release-mode-only problem is exactly the situation
   84 in which this build configuration is needed.
   85 
   86 To re-enable the availability of RelWithDebInfo for BRL-CAD builds, set
   87 the compilation variable ENABLE_ALL_CONFIG_TYPES to ON - once set,
   88 BRL-CAD's configure will no longer eliminate CMake build types other
   89 than Debug and Release.
   90 
   91 Working with MSI files
   92 ----------------------
   93 
   94 The WiX Toolset's MSI file, in addition to the standard interactive
   95 graphical install, also supports a command line based silent
   96 install. (See, for example, https://stackoverflow.com/a/25230485)
   97 
   98 msiexec.exe /i c:\BRL-CAD-7.32.0_win64.msi /QN /L*V "C:\Temp\brlcad_install.log"
   99 
  100 The logging step is not required but is recommended to allow for
  101 easier understanding of any issues that might arise.
  102 
  103 ===========================================
  104 
  105 === Setting a specific SDK version ===
  106 
  107 If a particular version of the Windows SDK is needed, it is specified
  108 with CMAKE_SYSTEM_VERSION (for example, to use 10.0.15063.0 the user
  109 would define a New Entry in the CMake GUI before running configure,
  110 make the variable CMAKE_SYSTEM_VERSION as a string type, and assign the
  111 value of 10.0.15063.0.)
  112 
  113 Note that for this to work the SDK version in question must be
  114 installed on the system.  To see what versions are installed,
  115 look for Windows SDK installs in the "Apps & Features" Setup
  116 interface.
  117 
  118 =======================================================
  119 
  120 === Tracking down the source of a header inclusion  ===
  121 
  122 If a Windows system header is reporting an error, it can be helpful to identify
  123 where the header is being included from.  By default MSVC doesn't report this,
  124 but in Visual Studio there is a "ShowIncludes" setting that may be enabled to
  125 find this information:
  126 
  127 https://stackoverflow.com/a/1138045
  128 
  129 This setting may also be added to the compilation flags directly
  130 in CMake as "/showIncludes":
  131 
  132 https://docs.microsoft.com/en-us/cpp/build/reference/showincludes-list-include-files
  133 
  134 Note that the output of this can be very verbose, especially if applied
  135 globally to all targets - you may want to consider applying it specifically to
  136 an individual target with target_compile_options.  This flag is a very useful
  137 tool when trying to determine *why* a particular header is present in an error
  138 message.
  139 
  140 =========================================================
  141 
  142 === Debugging build outputs from a Ninja compilation  ===
  143 
  144 Normally, Visual Studio is used to debug Windows executables.  However,
  145 another alternative is available called WinDbg:
  146 
  147 https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-download-tools
  148 
  149 This has been used successfully to debug Ninja produced executables.
  150 Note that if debugging an issue unique to Release builds, you will
  151 want to set the CMake variable ENABLE_ALL_CONFIG_TYPES to ON
  152 and the specific build type to RelWithDebInfo
  153 
  154 cmake.exe -G Ninja -ENABLE_ALL_CONFIG_TYPES=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo
  155 
  156 ===========================================
  157 
  158 === Notes on Visual Studio 14 2015 ===
  159 
  160 In order to build this version (required to build the Creo 3 converter)
  161 with CMake, you must ensure that Microsoft's "rc.exe" program is
  162 installed and findable by CMake.
  163 
  164 To install "rc.exe", run or re-run the Visual Studio installer and enable
  165 Visual C++ components and "Visual Studio Extensibility Tools Update 1" under
  166 the "Common Tools" section.
  167 
  168 The extensibility tools can become unselected by default in some
  169 configurations. Verify "rc.exe" is installed in:
  170 
  171 "C:\Program Files (x86)\Windows Kits\8.1\bin\x64"
  172 
  173 Add that directory to your "Path" user variable so CMake will be able to
  174 locate the rc executable.
  175 
  176 See:
  177 https://stackoverflow.com/questions/43847542/rc-exe-no-longer-found-in-vs-2015-command-prompt
  178 
  179 ======================================
  180 
  181 
  182 MINGW (WORK IN PROGRESS - THIS DOES NOT YET WORK!!!)
  183 -----
  184 
  185 After installing the MINGW system, set up as follows:
  186 
  187 set path=%path%;"C:\Program Files (x86)\CMake\bin"
  188 set path=%path%;C:\MinGW\bin
  189 
  190 now make a build directory, and run CMake:
  191 
  192 cmake ..\brlcad -G "MinGW Makefiles" -DBRLCAD_BUNDLED_LIBS=BUNDLED
  193 
  194 mingw32-make
  195 
  196 Note that you don't want to do this from an msys prompt that has
  197 sh in the path.  (ConEmu can make using the standard Windows command
  198 prompt a bit more tolerable:  http://conemu.github.io)
  199