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

update the install documentation to mention VS2022 properly

develop
Amber Brown 2023-01-06 21:14:09 +11:00
parent 7433cb463d
commit d7495bfdf8
2 changed files with 38 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/dev/building/Compile.rst
Unescape Escape View File

@ -160,10 +160,10 @@ Then you can either open the solution with MSVC or use one of the msbuild script
Visual Studio IDE Visual Studio IDE
----------------- -----------------
After running the CMake generate script you will have a new folder called VC2015 After running the CMake generate script you will have a new folder called VC2022
or VC2015_32, depending on the architecture you specified. Open the file or VC2022_32, depending on the architecture you specified. Open the file
``dfhack.sln`` inside that folder. If you have multiple versions of Visual ``dfhack.sln`` inside that folder. If you have multiple versions of Visual
Studio installed, make sure you open with Visual Studio 2015. Studio installed, make sure you open with Visual Studio 2022.
The first thing you must then do is change the build type. It defaults to Debug, The first thing you must then do is change the build type. It defaults to Debug,
but this cannot be used on Windows. Debug is not binary-compatible with DF. but this cannot be used on Windows. Debug is not binary-compatible with DF.
@ -183,15 +183,9 @@ In the build directory you will find several ``.bat`` files:
* Scripts with ``package`` prefix will build and create a .zip package of DFHack. * Scripts with ``package`` prefix will build and create a .zip package of DFHack.
Compiling from the command line is generally the quickest and easiest option. Compiling from the command line is generally the quickest and easiest option.
However be aware that due to the limitations of ``cmd.exe`` - especially in Modern Windows terminal emulators such as `Cmder <https://cmder.app/>`_ or
versions of Windows prior to Windows 10 - it can be very hard to see what happens `Windows Terminal <https://github.com/microsoft/terminal>`_ provide a better
during a build. If you get a failure, you may miss important errors or warnings experience by providing more scrollback and larger window sizes.
due to the tiny window size and extremely limited scrollback. For that reason you
may prefer to compile in the IDE which will always show all build output.
Alternatively (or additionally), consider installing an improved Windows terminal
such as `Cmder <https://cmder.net/>`_. Easily installed through Chocolatey with:
``choco install cmder -y``.
**Note for Cygwin/msysgit users**: It is also possible to compile DFHack from a **Note for Cygwin/msysgit users**: It is also possible to compile DFHack from a
Bash command line. This has three potential benefits: Bash command line. This has three potential benefits:

126
docs/dev/building/Dependencies.rst
Unescape Escape View File

@ -156,31 +156,8 @@ older GCC (but still at least 4.8) version if possible.
Windows Windows
======= =======
For ABI compatibility with recent releases of Dwarf Fortress, DFHack requires the ``v140`` or ``v140_xp`` DFHack must be built with the Microsoft Visual C++ 2022 toolchain (aka MSVC v143)
toolchain to build for windows. for ABI compatibility with Dwarf Fortress v50.
Of course all dependencies are listed above, but here are some things you'll likely want on Windows
to avoid risk of wading into uncharted waters:
* Microsoft Visual C++ 2022, 2019, 2017, or 2015 (optional)
* ``v140`` or ``v140_xp`` toolchain (Microsoft Visual C++ 2015 Build Tools)
* StrawberryPerl (perl + perl packages)
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.
Visual Studio 2015 is no longer supported by Microsoft and it can be difficult to obtain
working installers for this product today. The recommended approach is to use a modern community
version of Visual Studio such as 2022_ or 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.
.. _build tools: https://my.visualstudio.com/Downloads?q=visual%20studio%202015&wt.mc_id=o~msft~vscom~older-downloads
With Choco With Choco
~~~~~~~~~~ ~~~~~~~~~~
@ -194,34 +171,19 @@ Here are some package install commands::
choco install strawberryperl choco install strawberryperl
choco install python choco install python
choco install sphinx choco install sphinx
choco install visualstudio2022community
You may have noticed this list **does not include** the build tools, one of the build tool packages
in the chocolatey `package repository <https://community.chocolatey.org/packages>`_ may work for our purposes
but the tried and true method is just below in the **next section**. If you verify a package works feel free
to open an issue, or update this documentation.
.. _chocolatey: https://chocolatey.org/install
Visual Studio # Visual Studio
~~~~~~~~~~~~~ choco install visualstudio2022community --params "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended"
You could install visual studio `manually<install-visual-studio>`, perhaps even the build tools as well. # OR
You could also just run a ``choco`` command. For example:: # Build Tools for Visual Studio
choco install visualstudio2022buildtools --params "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended"
choco install visualstudio2022community
If Visual Studio is installed follow these next steps for the build tools:
1. Open **Visual Studio Installer**. If you already have Visual Studio 2022 or the Build Tools installed, you may
2. Select modify, for whichever version you've chosen to utilize. need to modify the installed version to include the workload components
3. Check the boxes for the following components: listed in the manual installation section, as chocolatey will not amend
the existing install.
* "Desktop Development with C++" .. _chocolatey: https://chocolatey.org/install
* "C++ Windows XP Support for VS 2017 (v141) tools [Deprecated]"
* "MSVC v140 - VS 2015 C++ build tools (v14.00)"
Yes, this is unintuitive. Installing XP Support for VS 2017 installs XP Support for VS 2015
if the 2015 toolchain is installed.
Manually Manually
~~~~~~~~ ~~~~~~~~
@ -280,55 +242,31 @@ See the `Sphinx`_ website.
Visual Studio Visual Studio
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
Click Visual Studio 2022_ or 2019_ to download an installer wizard that will prompt you The required toolchain can be installed as a part of either the `Visual Studio 2022 IDE`_
to select the optional tools you want to download alongside the IDE. You may need to log into or the `Build Tools for Visual Studio 2022`_. If you already have a preferred code
(or create) a Microsoft account in order to download Visual Studio. editor, the Build Tools will be a smaller install. You may need to log into (or create)
a Microsoft account in order to download Visual Studio.
.. _Visual Studio 2022 IDE: https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&channel=Release&version=VS2022&source=VSLandingPage&cid=2030&passive=false
.. _Build Tools for Visual Studio 2022: https://my.visualstudio.com/Downloads?q=Build%20Tools%20for%20Visual%20Studio%202022
.. _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 [Without Visual Studio] Build Tools [Without Visual Studio]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Click `build tools`_ and you will be prompted to login to your Microsoft account. Click `Build Tools for Visual Studio 2022`_ and you will be prompted to login to your Microsoft account.
Then you should be redirected to a page with various download options with 2015 Then you should be redirected to a page with various download options with 2022
in their name. If this redirect doesn't occur, just copy, paste, and enter the in their name. If this redirect doesn't occur, just copy, paste, and enter the
download link again and you should see the options. You need to get: download link again and you should see the options.
Visual C++ Build Tools for Visual Studio 2015 with Update 3. You want to select the most up-to-date version -- as of writing this is
Click the download button next to it and a dropdown of download formats will appear. "Build Tools for Visual Studio 2022 (version 17.4)". "LTSC" is an extended
Select the DVD format to download an ISO file. When the download is complete, support variant and is not required for our purposes.
click on the ISO file and a folder will popup with the following contents:
When installing, select the "Desktop Development with C++" workload and ensure that the following are checked:
* packages (folder)
* VCPlusPlusBuildTools2015Update3_x64_Files.cat - MSVC v143 - VS 2022 C++ x64/x86 build tools
* VisualCppBuildTools_Full.exe - C++ CMake tools for Windows
- At least one Windows SDK (for example, Windows 11 SDK 10.0.22621).
The packages folder contains the dependencies that are required by the build tools.
These include:
* Microsoft .NET Framework 4.6.1 Developer Pack
* Microsoft Visual C++ 2015 Redistributable (x64) - 14.0.24210
* Windows 10 Universal SDK - 10.0.10240
* Windows 8.1 SDK
Click VisualCppBuildTools_Full.exe and use the default options provided by the installer
wizard that appears. After the installation is completed, add the path where MSBuild.exe
was installed to your PATH environment variable. The path should be:
* ``C:\Program Files (x86)\MSBuild\14.0\Bin``
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.
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.
.. _mac-dependency-instructions: .. _mac-dependency-instructions: