|
| 1 | +## How can I build the GameCoreDLL |
| 2 | + |
| 3 | +* Install the git command line client and make sure it's in your path (it is needed for a pre-build script to run). |
| 4 | +* Clone the repo. The Visual Studio solution file `VoxPopuli_vs2013.sln`` is included in the repository folder |
| 5 | +* Significant portions of the mods are Lua / SQL / XML files. Those can be modified without rebuilding the game core |
| 6 | +* You need the Visual C++ 2008 SP1 (VC9) toolset to actually link the resulting game core DLL. |
| 7 | + * The SP1 is important, else you get errors that STL headers like `<array>` are missing. Try the internet archive ... |
| 8 | + * It is possible to use a recent IDE like Visual Studio 2022 Community, just make sure to use the correct toolset |
| 9 | + * If you get errors that the VC9 toolset cannot be found, install Visual C++ 2010 (not logical but true) |
| 10 | + * It's best to install different Visual Studio editions in chronological order, eg 2008 before 2019 |
| 11 | +* If prompted on loading the solution file whether you want to retarget projects, select "No Upgrade" for both options and continue |
| 12 | +* If you encounter an "unexpected precompiler header error", install [this hotfix](http://thehotfixshare.net/board/index.php?autocom=downloads&showfile=11640) |
| 13 | +* A tutorial with visual aids has been posted [here](https://forums.civfanatics.com/threads/how-to-compile-the-vox-populi-dll.665916/), courtesy of ASCII Guy |
| 14 | +* To build the 43 Civ version of the DLL: |
| 15 | + * Open the file `Community-Patch-DLL\CvGameCoreDLLUtil\include\CustomModsGlobal.h` |
| 16 | + * Remove everything **before** the `#` in this line: `// #define MOD_GLOBAL_MAX_MAJOR_CIVS (43)` |
| 17 | + * Save the file. |
| 18 | +* If building the Release version, Whole Program Optimization is enabled, which will cause a several minute delay at the end of pass 1, but the compiler is still functioning! |
| 19 | + * You can disable Whole Program Optimization locally under Project > VoxPopuli Properties > C/C++ > Optimization > Whole Program Optimization (set it to No) |
| 20 | +* If the compiler stops responding at the end of pass 2, try deleting the hidden .vs folder as well as the BuildOutput/BuildTemp folders in the project directory, then reopening the solution file. |
| 21 | +* There is also clang-based build script now! |
| 22 | + |
| 23 | +## How do I debug this |
| 24 | + |
| 25 | +### To enable logging (for bug reports) |
| 26 | +[This thread](https://forums.civfanatics.com/threads/how-to-enable-logging.487482) is useful for basic understanding of how logging works, down there is below and for more serious bug reports! |
| 27 | + |
| 28 | +* Logs provide some useful information on AI decisions and other problems |
| 29 | +* Logging can be enabled in `My Games\Sid Meier's Civilization V\config.ini` |
| 30 | +* Set the following options to 1: |
| 31 | + * `ValidateGameDatabase` |
| 32 | + * `LoggingEnabled` |
| 33 | + * `MessageLog` |
| 34 | + * `AILog` |
| 35 | + * `AIPerfLog` |
| 36 | + * `BuilderAILog` |
| 37 | + * `PlayerAndCityAILogSplit` |
| 38 | +* Make sure to save your changes! Enabling logging only needs to be done once every time the game is installed. |
| 39 | +* The log files will now be written to `My Games\Sid Meier's Civilization V\Logs` |
| 40 | + * Place them in a `.zip` file and attach them to your bug report! |
| 41 | + |
| 42 | +### To debug the GameCoreDLL |
| 43 | +* Use Visual Studio to build the `DEBUG` configuration of the project (as opposed to the `RELEASE` config) |
| 44 | +* Place the generated `.dll` and `.pdb` file (from the `BuildOutput` folder) in the mods folder (Community Patch Core), replacing the dll there. |
| 45 | +* Start Civ V and load the mod |
| 46 | +* Make sure Visual Studio is open with the solution file loaded |
| 47 | +* In the Visual Studio debugger menu select "Attach to process" and pick `Civilization5.exe` |
| 48 | +* Start the game. In case it crashes the debugger will show you where and why. |
| 49 | + * It may be you only see an address, no code. In that case the crash is outside of the game core dll ... |
| 50 | + * However it may still be possible to learn something from the callstack! |
| 51 | +* You do not have to play yourself - the FireTuner from the Civ V SDK has an autoplay feature under the Game tab, so you can lean back and watch the AI |
| 52 | + * You must first enable the tuner in `My Games\Sid Meier's Civilization V\config.ini` (first option) |
| 53 | +* You can also set (conditional) breakpoints in the code to inspect the value of interesting variables. |
| 54 | + * It is useful to place breakpoints where bugged functions are called, as you will see the callstack leading to that function call, and the value of the variables passed to it |
| 55 | +* Do not make changes to the code while the mod is running, this will desync the debugger |
| 56 | +* You may encounter benign exceptions, usually soon after beginning the debugging process |
| 57 | + * An example of this is an error informing you that a PDB file was not found. |
| 58 | + * These are nothing to worry about, you only want to catch unhandled exceptions (i.e. crashes) |
| 59 | + * If you encounter these exceptions, uncheck the box labelled "Break when this exception is thrown" |
| 60 | + * Then detach the debugger and reattach it to the process to resume debugging. You may have to do this a few times |
| 61 | + |
| 62 | +## How do I use Visual Studio 2022 Diagnostic Tools |
| 63 | + |
| 64 | +It is possible to use available out-of-box Diagnostic Tools to measure DLL performance. |
| 65 | +The things which you can do is profiling memory usage and profiling CPU performance. |
| 66 | + |
| 67 | +### Profiling memory |
| 68 | + |
| 69 | +To start with profiling memory, firstly follow the steps above to start a debug session. |
| 70 | +When you have debug session started: |
| 71 | +- Use Visual Studio shortcut Ctrl + T to open search bar and switch to "Feature Search". |
| 72 | +- Type "Diagnostic Tools" to find the appropriate window. |
| 73 | +- You will see window with graphs and with some tabs below. |
| 74 | +- Click at "Summary" tab, press "Enable heap profiling". |
| 75 | +- Go to "Memory Usage" tab and press "Take Snapshot" when you need to capture current |
| 76 | + memory allocations. |
| 77 | +- Taken snapshot will appear below and now you are able to click there to investigate |
| 78 | + memory allocations. You also can click on text in "Heap Diff" column to view diff |
| 79 | + with previous snapshot (if any). Doing so you will easily find how much memory DLL |
| 80 | + uses and find possible leaks. |
| 81 | + |
| 82 | +How it looks like. Summary view: |
| 83 | + |
| 84 | + |
| 85 | + |
| 86 | +Details view: |
| 87 | + |
| 88 | + |
| 89 | + |
| 90 | +### Profiling CPU |
| 91 | + |
| 92 | +CPU profiling will help you find the most "heavy" (in terms of time) functions. To start |
| 93 | +with profiling CPU performance, start a debug session and open "Diagnostic Tools". Then |
| 94 | +do the following: |
| 95 | +- Open "Summary" tab. When you will be ready to start CPU profiling, press |
| 96 | + "Record CPU profile". Time range on the graph will be colored in green if CPU |
| 97 | + profiling was enabled there. |
| 98 | +- When you finished with profiling and you want to investigate your results, switch to |
| 99 | + the "CPU Usage" tab, disable "Record CPU profile" button and click on text "Break All" |
| 100 | + to break application. |
| 101 | +- Select the time range which you want to investigate right on graph. Use "Zoom Out" |
| 102 | + button if time range does not fit. |
| 103 | +- Under the "Categories" uncheck "UI", "Graphics" and "Runtime". |
| 104 | +- Under the "Threads" uncheck all threads and leave only "CivilizationV_DX11.exe thread" |
| 105 | + selected (you can find its' id under the "Continue" button in main toolbar). |
| 106 | +- Under the "Settings" uncheck "Show Just My Code", leave only "Show Native Code". |
| 107 | +- Click on "Open details ..." text and select "Modules" as current view. |
| 108 | +- Now you can expand `cvgamecore_expansion2` and there you will notice all the data you |
| 109 | + need. There you can navigate between functions, switch between different views and so |
| 110 | + on. |
| 111 | + |
| 112 | +How it looks like: |
| 113 | + |
| 114 | + |
0 commit comments