Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build guide: Note on Win10 Mandatory ASLR, and optimised procedure thanks to imrpoved hint paths #693

Merged
merged 1 commit into from
Feb 11, 2020
Merged

Build guide: Note on Win10 Mandatory ASLR, and optimised procedure thanks to imrpoved hint paths #693

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 57 additions & 39 deletions docs/BUILDING_INSTRUCTIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,17 @@ If desired, there are some [additional tools listed in the wiki](https://github.

This will clone the source code to your local machine...

#### GitHub and Windows Mandatory ASLR

Recent versions of Windows 10 include an anti-exploit mechanism called [Mandatory ASLR](https://msrc-blog.microsoft.com/2017/11/21/clarifying-the-behavior-of-mandatory-aslr/). However, this can prevent unix-like executable (such as those used by GitHub) from functioning.

If you have system-wide Mandatory ASLR enabled, you might see errors such as:

* `.... \git\usr\bin\sh.exe: *** fatal error - cygheap base mismatch detected`
* `.... \app\mingw64\libexec\git-core\git-submodule: line 1121: cmd_: command not found`

The only known workaround is to exclude all executables in `\resources\app\git\` from Mandatory ASLR. For details see [GitHub issue #3096](https://github.com/desktop/desktop/issues/3096#issuecomment-529138491).

#### GitHub Desktop:

* Go to [the online repository](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition)
Expand All @@ -48,45 +59,6 @@ This will clone the source code to your local machine...

> You only need to do these steps once

#### Dependencies

TM:PE relies on several `.dll` files bundled with the game. They can be found in the following folder (may be different folder depending on where game is installed):

> `C:\Program Files (x86)\Steam\steamapps\common\Cities_Skylines\Cities_Data\Managed\`

You'll have to link the dependencies using _only one_ of the following methods:

* Create a `\TLM\dependencies` folder and copy in the `.dll` files
* Create a `\TLM\dependencies` symlink to the `...\Managed` folder shown above
* Manually add reference paths to each project in the solution.

If you choose the latter option, the procedure depends on your IDE.

In Visual Studio:

* Open `\TLM\TMPL.sln` in your IDE, then...
* For each project listed in the **Solution Explorer** (right sidebar):
1. Right-click the project, then choose **Properties**
2. Select **Reference Paths** on the left
3. Add folder: `C:\Program Files (x86)\Steam\steamapps\common\Cities_Skylines\Cities_Data\Managed\` (may be different folder depending on where game is installed)

In JetBrains Rider:

* At time of writing, there is no GUI for adding Reference Paths so you have to do it manually:
* For each project, create a `<project name>.csproj.user` file (in the folder of that project)
* For example, the `TLM` project needs a `TLM.csproj.user` file (in the `\TLM` folder)
* Paste in the following code, editing the path if necessary:
```xml
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<ReferencePath>C:\Program Files (x86)\Steam\steamapps\common\Cities_Skylines\Cities_Data\Managed\</ReferencePath>
</PropertyGroup>
</Project>
```

#### Enable Roslyn Analyzers

This is only required for the JetBrains Rider IDE:

* [Activate Roslyn Analyzers](https://www.jetbrains.com/help/rider/Settings_Roslyn_Analyzers.html) ([why?](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/pull/463))
Expand All @@ -95,6 +67,8 @@ This is only required for the JetBrains Rider IDE:

This will compile the source code to DLL files...

> If you get errors at this stage, it's likely that your IDE isn't able to find the managed `.dll` files it needs. See **Managed DLLs** section at bottom of this page.

#### Configurations:

There are several build configurations, but we mostly use just three:
Expand Down Expand Up @@ -129,3 +103,47 @@ The built DLL files are automatically copied over to the local mods folder of th
Once built, you should be able to test the mod in-game. Remember to enable it in **Content Manager > Mods**.

If you have any problems, let us know!

#### Managed DLLs

> You only need to do this once, and only if your IDE wasn't able to find the required managed `.dll` files.

TM:PE requires references to several "managed" `.dll` files that are bundled with the game; it should automatically find the files, but if not you'll have to do some additional setup...

First, locate your `Steam` folder. It is normally found in:

* **Windows:** `C:\Program Files (x86)\Steam\`
* **Mac OS X:** `~/Library/Application Support/Steam/`

The managed `.dll` files are usually located within the following sub-folder: `\steamapps\common\Cities_Skylines\Cities_Data\Managed\`.

You'll have to link the dependencies using _only one_ of the following methods:

* Create a `\TLM\dependencies` folder (in the TM:PE repository folder) and copy in the `.dll` files
* Or, create a `\TLM\dependencies` symlink to the `...\Managed` folder shown above
* Or, manually add reference paths to each project in the solution.

If you choose the latter option, the procedure depends on your IDE.

In Visual Studio:

* Open `\TLM\TMPL.sln` in your IDE, then...
* For each project listed in the **Solution Explorer** (right sidebar):
1. Right-click the project, then choose **Properties**
2. Select **Reference Paths** on the left
3. Add the full path to the `Managed` folder.

In JetBrains Rider:

* At time of writing, there is no GUI for adding Reference Paths so you have to do it manually:
* For each project, create a `<project name>.csproj.user` file (in the folder of that project)
* For example, the `TLM` project needs a `TLM.csproj.user` file (in the `\TLM` folder)
* Paste in the following code, making sure to edit the path to the `Managed` folder:
```xml
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<ReferencePath>C:\full\path\to\Managed\</ReferencePath>
</PropertyGroup>
</Project>
```