MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

visual studio 2022/2019 build instructions (#2034) 

* visual studio 2022/2019

update instructions to recommend using VS 2022 or VS 2019 with downlevel tool support

* reinsert accidentally deleted line

* fix markup

* notes on abi compatibility, changelog
develop
Kelly Kinkade 2022-03-17 15:19:12 -05:00 committed by GitHub
parent e0ecf21896
commit e1961f5fcd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 46 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
docs/Compile.rst
Unescape Escape View File

@ -469,7 +469,8 @@ Dependencies
------------
You will need the following:
* Microsoft Visual C++ 2015 or 2017
* Microsoft Visual C++ 2022, 2019, 2017, or 2015 (optional)
* Microsoft Visual C++ 2015 Build Tools
* Git
* CMake
* Perl with XML::LibXML and XML::LibXSLT
@ -478,14 +479,21 @@ You will need the following:
* Python (for documentation; optional, except for release builds)
Microsoft Visual Studio 2015
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DFHack has to be compiled with the Microsoft Visual C++ 2015 or 2017 toolchain on Windows;
other versions won't work against Dwarf Fortress due to ABI and STL incompatibilities.
Microsoft Visual Studio
~~~~~~~~~~~~~~~~~~~~~~~
Releases of Dwarf Fortress since roughly 2016 have been compiled for Windows using
Microsoft's Visual Studio 2015 C++ compiler. In order to guarantee ABI and STL compatibility
with Dwarf Fortress, DFHack has to be compiled with the same compiler.
You can install Visual Studio 2015_ or 2017_ Community edition for free, which
include all the features needed by DFHack. You can also download just the
Visual C++ 2015 `build tools`_ if you aren't going to use Visual Studio to edit code.
Visual Studio 2015 is no longer supported by Microsoft and it can be difficult to obtain
working installers for this product today. As of 2022, the recommended approach
is to use Visual Studio 2022 or Visual Studio 2019, installing additional optional
Visual Studio components which provide the required support for using
Visual Studio 2015's toolchain. All of the required tools are available from Microsoft as part of
Visual Studio's Community Edition at no charge.
You can also download just the Visual C++ 2015 `build tools`_ if you aren't going to use
Visual Studio to edit code.
Option 1: Build Tools Only
^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -516,22 +524,37 @@ was installed to your PATH environment variable. The path should be:
* ``C:\Program Files (x86)\MSBuild\14.0\Bin``
Option 2: IDE + Build Tools
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Click Visual Studio 2015_ or 2017_ to download an installer wizard that will prompt you
to select the optional tools you want to download alongside the IDE. If you are not sure
what options to check, it can be helpful to download the `build tools`_ and open the
ISO file to see the required dependencies in the packages folder. For Visual Studio 2017,
it is important to select the v140 build tools option. DFHack requires v140 and not
the v141 version that comes in a bundle when you click the Desktop Development with C++
option from the installer.
Note that this process may install only the ``v140`` toolchain, not the ``v140_xp`` toolchain that
is normally used to compile build releases of DFHack. Due to a bug in the Microsoft-provided libraries used with
the ``v140_xp`` toolchain that Microsoft has never fixed, DFHack (and probably also Dwarf Fortress itself)
doesn't run reliably on 64-bit XP. Investigations have so far suggested that ``v140`` and
``v140_xp`` are ABI-compatible. As such, there should be no harm in using ``v140`` instead of
``v140_xp`` as the build toolchain, at least on 64-bit platforms. However, it is our policy to use
``v140_xp`` for release builds for both 32-bit and 64-bit Windows,
since 32-bit releases of Dwarf Fortress work on XP and ``v140_xp`` is required for compatibility with
XP.
.. warning::
Do not run the build tools installer together with the Visual Studio installer as they
will have conflicts with each other by trying to install the same dependencies.
The ``v141`` toolchain, in Visual Studio 2017, has been empirically documented to be incompatible with
released versions of Dwarf Fortress and cannot be used to make usable builds of DFHack.
.. _2015: https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2015-and-other-products
.. _2017: https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=15
Option 2: IDE + Build Tools
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Click Visual Studio 2022_ or 2019_ to download an installer wizard that will prompt you
to select the optional tools you want to download alongside the IDE. You may need to log into
(or create) a Microsoft account in order to download Visual Studio.
In addition to selecting the workload for "Desktop Development with C++",
you will also need to go to the "Individual Components" tab in the Installer and
select the following additional components to get the "``v140_xp``" toolchain that DFHack
requires for ABI compatibility with recent releases of Dwarf Fortress:
* MSVC v140 - VS 2015 C++ build tools (v14.00)
* C++ Windows XP Support for VS 2017 (v141) tools [Deprecated]
Yes, this is unintuitive. Installing XP Support for VS 2017 installs XP Support for VS 2015
if the 2015 toolchain is installed.
.. _2022: https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&channel=Release&version=VS2022&source=VSLandingPage&cid=2030&passive=false
.. _2019: https://my.visualstudio.com/Downloads?q=visual%20studio%202019&wt.mc_id=o~msft~vscom~older-downloads
.. _build tools: https://my.visualstudio.com/Downloads?q=visual%20studio%202015&wt.mc_id=o~msft~vscom~older-downloads
Additional dependencies: installing with the Chocolatey Package Manager

1
docs/changelog.txt
Unescape Escape View File

@ -54,6 +54,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
- Add more examples to the plugin skeleton files so they are more informative for a newbie
- Lua API.rst added: ``isHidden(unit)``, ``isFortControlled(unit)``, ``getOuterContainerRef(unit)``, ``getOuterContainerRef(item)``
- Update download link and installation instructions for Visual C++ 2015 build tools on Windows
- Updated information regarding obtaining a compatible Windows build environment
## API
- Added functions reverse-engineered from ambushing unit code: ``Units::isHidden``, ``Units::isFortControlled``, ``Units::getOuterContainerRef``, ``Items::getOuterContainerRef``