-
Notifications
You must be signed in to change notification settings - Fork 16
Windows Notes
Building and using the DACE library on Windows is a bit different from Mac OS X or Linux. On this page we collect some information on how to use the DACE with Windows.
To use the pre-built release packages of the DACE, you need to install the following programs. Versions that have been tested by us to be working at the time of writing are given in parentheses.
- Microsoft Visual Studio (2017 Community Edition)
- CMake (CMake 3.13.4)
- DACE (DACE 2.0.2)
Only if you want to build your own DACE installer packages you also need to install this:
- NSIS (NSIS 3.04)
If you want to use Git to track this repository to always have the latest versions ("bleeding edge") of the DACE code, or if you just want to use it to track your own project, you also need a Git client. Possible options (choose one of these):
- GitHub Desktop (GitHub Desktop 1.62)
- SourceTree (SourceTree 3.1)
- Git (Git 2.20.1)
To use the DACE in Windows is no different than on any other platform on the code side: your C++ code will look just the same. However, the build process is slightly different as it is fully done by GUIs instead of from the command line.
To start a new project using the DACE, you first create a CMakeList.txt file for it. The DACE installer made sure to tell your CMake installation about where to find the DACE, so all you need in your CMakeList.txt file to get started is
cmake_minimum_required (VERSION 2.8.4)
project(MyProjectName CXX)
find_package(dace 2.0.0 REQUIRED)
add_executable(MyDAProject driver.cpp logic.cpp magic.cpp)
target_link_libraries(MyDAProject PUBLIC dace::dace_s)
This basic file tells CMake your project name (MyProjectName) and adds an executable to it (MyDAProject). This executable will be built from the listed source files (you only need to list the .cpp files, not any .h headers). It then tells CMake to link your program with the static DACE library, meaning any DA code you use inside the DACE will be copied into your program while it is built and therefore can be run on any system without requiring a separate installation of the DACE.
In you code, you start by including the DACE static library headers using the line
#include <dace/dace_s.h>
See DACE Headers for more information on the DACE header files to use in your project.
To build your project, start the CMake GUI program, select the source folder (where you put the CMakeList.txt file), and create another Folder named "build" in it to be used as the build folder. Then "Configure" your project, which should check for your compilers and find the DACE. Once done, use the "Generate" button to generate a VisualStudio project file, and finally click the "Open Project" button to start VisualStudio and build your project in there. For more information on the process, refer to the CMake and VisualStudio documentation.
Note that on Windows it is crucial that you use the same build configuration for your project as was used for the building of the DACE libraries. Windows does not allow mixing of debug executables and release libraries. This will result in crashes and, worse, unexplainably wrong results (see Issue #3 for more details).
The DACE libraries are always built using the RelWithDebInfo build type. If you need your libraries to be built with another type, you have to rebuild the DACE libraries yourself.
Windows library handling is different from other operating systems. Usually, Windows applications are expected to bring along their own dynamic libraries (DLLs) with them. There is no repository management system that takes care of dependencies of different programs to different library versions installed in a central system location.
That means that we, too, don't install the DACE library in a system location. As a result, even if you build your application successfully against the DACE dynamic library (because CMake knows where to find it), when you try to run this executable Windows will most likely refuse to run it on account of a missing dace.dll library. To get around this issue, you need to manually copy the dace.dll library into the same directory as the executable you are running.
If you want to do this automatically inside your CMake project, so that in Visual Studio you can just hit "Run" or "Debug" and things just work, you can use the following snippet in your CMakeList.txt file:
if(WIN32)
get_target_property(DACEDLL dace::dace LOCATION)
file(COPY "${DACEDLL}" DESTINATION "${CMAKE_CURRENT_BINARY_DIR}")
endif(WIN32)
The conditional makes sure you don't spam copies of the shared library on systems that don't need it (i.e. anything but Windows). This code also uses the CMake package system to find the correct location of the dace.dll file to copy.
If you do not want a copy of some dace.dll next to every executable you generate, you can also choose from the following more advanced options:
- Add the installation path of the DACE library (where dace.dll is found) to the PATH environment variable of your system. Windows searches this path when it looks for dace.dll.
- Copy the dace.dll library into one of your system directories Windows uses to look for DLLs (e.g. C:\Windows\System32 for 64bit libraries and C:\Windows\SystemWOW64 for 32bit libraries).
- Link your program against the static version of the DACE library to avoid any of these problems (see above for details)
Before building the DACE, you should use your Git client to clone the main DACE repository you want to build from https://github.com/dacelib/dace onto your local machine.
Building the DACE library is quite straight forward. It has no external dependencies at the moment, so you can just start the CMake GUI, select the Folder you cloned the Git repository to, and specify a "build" Folder within it. Then hit the "Configure" button to start the configuration process. Various build time options will be populated in the GUI, just leave the defaults unless you know what you are doing. Hit "Configure" again just to be sure all options take effect. Then hit "Generate" to generate the VisualStudio project. CMake may ask you what generator to use, make sure to select the correct VisualStudio generator (32 bit or 64 bit), as you can't change this setting from within the CMake project easily. When done, simply hit "Open Project" to start VisualStudio.
Within VisualStudio, you need to built the ALL target to build all parts of the DACE library. If you have NSIS installed, you can then build the PACKAGE target to produce a stand-alone installer package for the DACE. This is the same installer package we distribute with our releases.