-
Notifications
You must be signed in to change notification settings - Fork 159
Adding third‐party libraries to the project
In AGS we prioritize not including third-party library code into the project, and instead configure the program (engine, editor, tools) to link stand-alone library either dynamically, or statically - at the linking step. There are following general reasons for this:
- not having to store and maintain the library source in the repository; also we don't have to pull library changes to repository when we like to use newer version;
- on some systems, such as Linux and similar, it's preferable to link libraries installed on system whenever possible.
- in regards to the Editor, which is written in C#, it's a common practice to fetch dependencies using NuGet.
There are cases when we may add library sources into the repository and build them embedded with the engine:
- the library does not have proper distribution on Linux and similar systems.
- the library's source is so small (like a pair of .h/.c or *.cpp files) that it's easier to add directly.
- we must use a very particular old version of the library, for compatibility reasons; or we want to have a modified library code.
In other cases it's preferable to not put lib sources into the repository, but configure the respective program to link it from an external location, and require users to install the library separately prior to building.
First of all, determine which part of the program is dependent on this library. Engine currently consists of 2 parts: a Common lib, which is still shared with the Editor, and Engine itself. If the library is required for some code that was added into Common, then this library should be linked with Common (the Engine will also be able to use it). Otherwise it should be linked with the Engine directly.
For the C++ MSVS projects we add the library name to the list of Linker's dependencies. But we don't add explicit paths to the library headers or lib file itself, because these may be different on each workplace. Instead we use VS property pages which let each user configure these paths individually through the "User Macros".
Here's how it's done. Let's suppose you'd like to add a dependency called "LibName", which static library name on Windows is "libname.lib".
Adding library as the dependency to the project
Open a respective solution in the Visual Studio, open project's properties. Go to "Linker -> Input" settings, and add "libname.lib" into the list of "Additional Dependencies". Note that you should do this for each of the existing configurations (Release, Debug, etc).
Adding paths to the library and its headers
In Visual Studio open "Property Manager" window. Choose the project you need this library for, call a context menu and choose "Add New Project Property Sheet...". Give this sheet a name related to the library, and make sure that the Location to create the sheet file is set to "Solutions" in the AGS repository. Confirm the creation of a new file.
This will create a property sheet file (*.props), which you may edit either directly by hand, or from MSVS.
Open it up by double clicking the created item in the "Property Manager". This will open a dialog similar to the project settings. This is where you need to add paths to library headers and compiled lib files. But the paths must not be explicit absolute paths (because these will be different for each user), instead you need to invent a "macro" name for them. For example, if your library is called "LibName", then the macro pointing to the headers would be LIBNAME_INCLUDE and macro pointing to the library files - LIBNAME_LIB.
Go to "C/C++ -> General", and in the field "Additional Include Directories" add the invented macro to the list of paths, like this:
$(LIBNAME_INCLUDE)
Then, go to "Linker -> General", and in the field "Additional Library Directories" add the invented macro to the list of paths, like this:
$(LIBNAME_LIB)
What you did now is defined two new paths for the engine project, that will be used for building in MSVS.
Before you could test that this works, you would need to define the newly invented macros for yourself, assigning them to actual paths. To do so, open "Property Manager" once more, and this time open an item called "Microsoft.Cpp.Win32.user". These are your personal MSVS user settings. In the opened property pages dialog go to "User Macros", and add two macros that you have just invented: LIBNAME_INCLUDE and LIBNAME_LIB. Assign LIBNAME_INCLUDE to a path leading to where the library's headers are, and assign LIBNAME_LIB to a path where the built library file(s) are.
For more information on "User Macros" see the Microsoft's documentation here: https://docs.microsoft.com/en-us/cpp/build/working-with-project-properties?view=msvc-160#user-defined-macros
TBD
TBD