Compiling MTASA: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
m (root -> top-level)
(38 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{Note|These instructions are slightly incorrect as MTA does not build properly with VS 2019. You need to install VS 2017 instead.}}
In order to successfully build Multi Theft Auto from source, it is necessary to perform a number of steps, which we will explain below.
In order to successfully build Multi Theft Auto from source, it is necessary to perform a number of steps, which we will explain below.


Line 9: Line 11:
Make sure you have the following software and SDKs installed:
Make sure you have the following software and SDKs installed:


=== Visual Studio 2015 ===
=== Visual Studio 2019 ===
[[File:Visual_Studio_Community.PNG|left|150px|link=https://www.visualstudio.com/vs/]]
[[File:Visual_Studio_Community.PNG|left|150px|link=https://www.visualstudio.com/vs/]]
'''Download'''<br>
'''Download'''<br>
[https://www.visualstudio.com/vs/ Microsoft Visual Studio 2015] (Community Edition is free).<br>
[https://visualstudio.microsoft.com/vs/ Microsoft Visual Studio 2019] (Community Edition is free).<br>
Make sure you also install other items during installation, see below.
(You can re-run the installer to modify your current installation, no need to uninstall and reinstall.)<br>


'''Addon: EditorConfig''' (optional)<br>
'''Missing #include "afxres.h"'''<br>
Download: [https://visualstudiogallery.msdn.microsoft.com/c8bccfe2-650c-4b42-bc5c-845e21f96328 EditorConfig]<br>
[[Media:VsFoundationClasses.png|Make sure you have MFC and ATL support installed.]] MFC/ATL must be v141.<br>
(Install this addon to automatically set up your IDE for the correct code formatting)
 
'''Toolset issues'''<br>
[[Media:VsFoundationClasses.png|Make sure you have ''VC++ 2015 toolset'' installed.]]<br>
(You can re-run the installer to modify your current installation, no need to uninstall and reinstall)


'''Addon: ReAttach''' (optional)<br>
'''Addon: ReAttach''' (optional)<br>
Download: [https://visualstudiogallery.msdn.microsoft.com/8cccc206-b9de-42ef-8f5a-160ad0f017ae ReAttach]<br>
Download: [https://marketplace.visualstudio.com/items?itemName=ErlandR.ReAttach ReAttach]<br>
(ReAttach gives you an easy way to re-attach your prior debug targets)
(ReAttach gives you an easy way to re-attach your prior debug targets)
'''Missing #include "afxres.h"'''<br>
[[Media:Vs2015_foundationClasses.png|Make sure you have ''Microsoft Foundation Classes for C++'' installed.]]<br>
(You can re-run the installer to modify your current installation, no need to uninstall and reinstall)<br style="clear:both">


=== Microsoft DirectX SDK ===
=== Microsoft DirectX SDK ===
Line 30: Line 33:
'''Download'''<br>
'''Download'''<br>
[https://www.microsoft.com/en-us/download/details.aspx?id=23549 Microsoft DirectX SDK (August 2009)]<br>
[https://www.microsoft.com/en-us/download/details.aspx?id=23549 Microsoft DirectX SDK (August 2009)]<br>
'''NOTE:''' Restart your computer after installing ''Microsoft DirectX SDK'', because otherwise the environment variable '''DXSDK_DIR''' won't be available yet. After restarting it re-run '''create-projects.bat'''
'''Cant find d3dx9.h'''<br>
Add the '''$(DXSDK_DIR)Include;''' to the VC++ Directories in DirectX9GuiRenderer, GUI and Client Core projects.
You can find the VC++ Directories list by selecting a project, then pressing the shortcut ALT + ENTER (without the +), then under the 'Configuration properties' you can find 'VC++ Directories', and in there you can find the 'Include Directories' field, click on it and add ''';$(DXSDK_DIR)Include;''' at the end of it.
'''Note: You need to do the same thing in Release mode as well'''
'''Cant find d3dx9.lib'''<br>
Do do same as in the error above, but instead of ''';$(DXSDK_DIR)Include;''' you must add ''';$(DXSDK_DIR)Lib/x86;''' to the '''Library directories''' field
'''Note: You need to do the same thing in Release mode as well'''


'''S1023 Error'''<br>
'''S1023 Error'''<br>
Line 36: Line 50:
=== Git Client ===
=== Git Client ===
[[File:Git_logo.png|left|32px|link=https://git-scm.com/]]
[[File:Git_logo.png|left|32px|link=https://git-scm.com/]]
You have three options here available. You can install '''ONE''' of the clients below (for collaboration) or download the entire codebase in a [https://github.com/multitheftauto/mtasa-blue/archive/master.zip .ZIP] file (if you only want to compile the code). You can also use Git on the command line to checkout the respository.<br style="clear:both">


==== GitHub Desktop ====
If you would like to contribute to MTA, you should install Git. This will allow you to collaborate with us by creating branches and pushing to your own fork. If you are not comfortable with the command line, we recommend you to download and install [https://desktop.github.com/ GitHub Desktop].
[[File:GitHub_Desktop.png|left|150px]]
'''Download:'''<br>
[https://windows.github.com/ GitHub for Windows]<br style="clear:both">


==== SourceTree ====
If you only want to compile the source code and are not interested in contributing to MTA, you can download the source directly (see below).
[[File:Atlassian_SourceTree.png|left|150px]]
'''Download:'''<br>
[https://www.sourcetreeapp.com/ SourceTree]<br style="clear:both">
 
==== GitKraken ====
[[File:GitKraken_Logo.png|left|150px]]
'''Download:'''<br>
[https://www.gitkraken.com/ GitKraken]<br style="clear:both">


== Getting the latest source code ==
== Getting the latest source code ==
Line 63: Line 65:


== Compiling the code ==
== Compiling the code ==
# Execute the script '''create-projects.bat'''
# Execute the script '''win-create-projects.bat'''
# Open the solution file '''MTASA.sln''' in the '''Build''' directory
# Open the solution file '''MTASA.sln''' in the '''Build''' directory
# If you are asked to upgrade the project, click '''Cancel'''
# Compile in Visual Studio with '''Debug''' configuration (may take some minutes)
# Compile in Visual Studio with '''Debug''' configuration (may take some minutes)
# Install data files: '''utils\premake5.exe install_data''' (''Shift + Right-Click'' in the ''top-level'' directory and click on [http://michaelcrump.net/files/image_635243330608233338.png ''Open command window here''])
# Execute the script '''win-install-data.bat'''
# Install resources: '''utils\premake5.exe install_resources''' (optional step)


= Running the software =
= Running the software =
Line 74: Line 76:


You can start your client in the '''Bin''' directory. You might find there a ''Multi Theft Auto.exe'' and/or ''Multi Theft Auto_d.exe'' executable. The ''_d'' suffix indicates a debug build of the software.<br>
You can start your client in the '''Bin''' directory. You might find there a ''Multi Theft Auto.exe'' and/or ''Multi Theft Auto_d.exe'' executable. The ''_d'' suffix indicates a debug build of the software.<br>
Furthermore, you can also run your client inside the debugger from Visual Studio if you want to investigate a stack trace or set breakpoints in interesting code regions (read more in the section below).
Furthermore, you can also run your client inside the debugger from Visual Studio if you want to investigate a stack trace or set breakpoints in interesting code regions (read more in the section Debugging below).


== Running the dedicated server ==
== Running the dedicated server ==
Line 87: Line 89:
=== Starting the server ===
=== Starting the server ===
To run the server, open the ''MTA Server.exe'' executable in the '''Bin/server''' directory. The ''_d'' suffix indicates a debug build of the software.<br>
To run the server, open the ''MTA Server.exe'' executable in the '''Bin/server''' directory. The ''_d'' suffix indicates a debug build of the software.<br>
You can also run the debug build ''MTA Server_d.exe'' with the Visual Studio Debugger (as of writing, you can do that by right-clicking on the Server's Launcher project and selecting ''Start a local instance'' in the ''Debugger'' menu).
You can also run the debug build ''MTA Server_d.exe'' with the Visual Studio Debugger (as of writing, you can do that by right-clicking on the Server's Launcher project and selecting ''Start a local instance'' in the ''Debugger'' menu), but you can also attach to a running debug build MTA server (see more in the section Debugging below).


== Debugging ==
== Debugging ==
If you already compiled the code in the '''Debug''' configuration then continue reading, if not, then go up to ''Compilling the code'' and follow the steps for a ''Debug'' build.<br>
If you already compiled the code in the '''Debug''' configuration then continue reading, if not, then go up to ''Compilling the code'' and follow the steps for a ''Debug'' build.<br>
You can either launch MTA yourself and attach any debugger you want to use (also applies to the Visual Studio debugger) or you start a local debugging session in Visual Studio.<br>
You can either launch MTA yourself and attach any debugger you want to use (also applies to the Visual Studio debugger) or you start a local debugging session in Visual Studio.<br>
[[File:Local_Windows_Debugger.PNG]]
=== How to enable breakpoints ===
If you choose to run MTA with Visual Studio then you should also attach the debugger to the executable '''gta_sa.exe''' (press ''CTRL + ALT + P'' in Visual Studio) - otherwise your
If you choose to run MTA with Visual Studio then you should also attach the debugger to the executable '''gta_sa.exe''' (press ''CTRL + ALT + P'' in Visual Studio) - otherwise your
breakpoints will not work for anything beside the MTA Launcher project.<br>
breakpoints will not work for anything beside the MTA Launcher project.<br>
Furthermore, it is advisable to create an empty "timeout.longtime" file in your ''Bin/server/'' directory<br>
[[File:Attach_to_Process.png|600px]]
This will extend the time before players are kicked from your server for unresponsiveness to 120 seconds. This is useful when in Debug mode on the client and the process is halted.
 
[[File:Local_Windows_Debugger.PNG]]


[[File:Attach_to_Process.png|600px]]
=== Extending timeout duration ===
When you use breakpoints during debugging, you may get kicked by the server due to timeout, because the client is frozen. To prevent this, create the '''timeout.longtime''' file in your ''Bin/server/'' directory. 
The content of the file is the new timeout duration in seconds, so make sure you type a huge number in there. If you keep the file empty, the timeout will be set to 120 seconds.


=== ReAttach for Visual Studio ===
You can use [https://marketplace.visualstudio.com/items?itemName=ErlandR.ReAttach ReAttach] to re-attach the debugger to the '''gta_sa.exe''' executable whenever you start your local debugger in Visual Studio.<br>
[[File:ReAttach_to_GTASA.PNG]]
[[File:ReAttach_to_GTASA.PNG]]
You can use [https://visualstudiogallery.msdn.microsoft.com/8cccc206-b9de-42ef-8f5a-160ad0f017ae ReAttach] to re-attach the debugger to the '''gta_sa.exe''' executable whenever you start your local debugger in Visual Studio.


= Getting involved =
= Getting involved =
Line 112: Line 115:
If you need more information, try our [http://bugs.mtasa.com/ bug tracker] or [irc://irc.multitheftauto.com IRC channel].
If you need more information, try our [http://bugs.mtasa.com/ bug tracker] or [irc://irc.multitheftauto.com IRC channel].


= Errors =
== CL38 error. [netc_d.dll not found] ==
Solution: Delete '''Multi Theft Auto_d.exe''' and hit compile again.
== After cloning the repository, it doesn't compile the project ==
Solution: Execute '''win-create-projects.bat''' in main directory.
== CL17 Load field. Please ensure that the latest data files have been installed correctly ==
Solution: Execute '''win-install-data.bat''' in main directory.
[[hu:Compiling MTASA]]
[[pt-br:Compilando o MTASA]]
[[pt-br:Compilando o MTASA]]
[[ru:Compiling MTASA]]
[[ru:Compiling MTASA]]
[[Category: Development]]
[[Category: Development]]

Revision as of 22:54, 19 May 2019

[[{{{image}}}|link=|]] Note: These instructions are slightly incorrect as MTA does not build properly with VS 2019. You need to install VS 2017 instead.

In order to successfully build Multi Theft Auto from source, it is necessary to perform a number of steps, which we will explain below.

Please read the instructions carefully and do not skip parts of it, if you have no experience.

Prerequisites

You should be using Windows 7 or above, before you can compile the Multi Theft Auto client.

Make sure you have the following software and SDKs installed:

Visual Studio 2019

Visual Studio Community.PNG

Download
Microsoft Visual Studio 2019 (Community Edition is free).
Make sure you also install other items during installation, see below. (You can re-run the installer to modify your current installation, no need to uninstall and reinstall.)

Missing #include "afxres.h"
Make sure you have MFC and ATL support installed. MFC/ATL must be v141.

Toolset issues
Make sure you have VC++ 2015 toolset installed.
(You can re-run the installer to modify your current installation, no need to uninstall and reinstall)

Addon: ReAttach (optional)
Download: ReAttach
(ReAttach gives you an easy way to re-attach your prior debug targets)

Microsoft DirectX SDK

DirectX SDK.jpg

Download
Microsoft DirectX SDK (August 2009)

NOTE: Restart your computer after installing Microsoft DirectX SDK, because otherwise the environment variable DXSDK_DIR won't be available yet. After restarting it re-run create-projects.bat

Cant find d3dx9.h
Add the $(DXSDK_DIR)Include; to the VC++ Directories in DirectX9GuiRenderer, GUI and Client Core projects. You can find the VC++ Directories list by selecting a project, then pressing the shortcut ALT + ENTER (without the +), then under the 'Configuration properties' you can find 'VC++ Directories', and in there you can find the 'Include Directories' field, click on it and add ;$(DXSDK_DIR)Include; at the end of it. Note: You need to do the same thing in Release mode as well

Cant find d3dx9.lib
Do do same as in the error above, but instead of ;$(DXSDK_DIR)Include; you must add ;$(DXSDK_DIR)Lib/x86; to the Library directories field Note: You need to do the same thing in Release mode as well

S1023 Error
"S1023" error when you install the DirectX SDK (June 2010)

Git Client

Git logo.png

If you would like to contribute to MTA, you should install Git. This will allow you to collaborate with us by creating branches and pushing to your own fork. If you are not comfortable with the command line, we recommend you to download and install GitHub Desktop.

If you only want to compile the source code and are not interested in contributing to MTA, you can download the source directly (see below).

Getting the latest source code

To get the latest code, you will have to download the latest copy of our Git repository.
We recommend cloning the repository in your Git client, because you can pull any updates from there easily.

Compiling the code

  1. Execute the script win-create-projects.bat
  2. Open the solution file MTASA.sln in the Build directory
  3. If you are asked to upgrade the project, click Cancel
  4. Compile in Visual Studio with Debug configuration (may take some minutes)
  5. Execute the script win-install-data.bat

Running the software

Running the client

You can start your client in the Bin directory. You might find there a Multi Theft Auto.exe and/or Multi Theft Auto_d.exe executable. The _d suffix indicates a debug build of the software.
Furthermore, you can also run your client inside the debugger from Visual Studio if you want to investigate a stack trace or set breakpoints in interesting code regions (read more in the section Debugging below).

Running the dedicated server

If you already have run the step 5 (Install resources) in Compiling the code to install resources then you can goto Starting the server.

Installing the latest resources

If you want to run the Multi Theft Auto dedicated server, you will have to install the required resources. These are required because they implement the most basic functionality (e.g. spawning players) in order to play.

Our official resources repository is hosted on GitHub. You can download the latest resources from there or download a zipped version. Make sure that you have the latest resources package.

Starting the server

To run the server, open the MTA Server.exe executable in the Bin/server directory. The _d suffix indicates a debug build of the software.
You can also run the debug build MTA Server_d.exe with the Visual Studio Debugger (as of writing, you can do that by right-clicking on the Server's Launcher project and selecting Start a local instance in the Debugger menu), but you can also attach to a running debug build MTA server (see more in the section Debugging below).

Debugging

If you already compiled the code in the Debug configuration then continue reading, if not, then go up to Compilling the code and follow the steps for a Debug build.
You can either launch MTA yourself and attach any debugger you want to use (also applies to the Visual Studio debugger) or you start a local debugging session in Visual Studio.
Local Windows Debugger.PNG

How to enable breakpoints

If you choose to run MTA with Visual Studio then you should also attach the debugger to the executable gta_sa.exe (press CTRL + ALT + P in Visual Studio) - otherwise your breakpoints will not work for anything beside the MTA Launcher project.
Attach to Process.png

Extending timeout duration

When you use breakpoints during debugging, you may get kicked by the server due to timeout, because the client is frozen. To prevent this, create the timeout.longtime file in your Bin/server/ directory. The content of the file is the new timeout duration in seconds, so make sure you type a huge number in there. If you keep the file empty, the timeout will be set to 120 seconds.

ReAttach for Visual Studio

You can use ReAttach to re-attach the debugger to the gta_sa.exe executable whenever you start your local debugger in Visual Studio.
ReAttach to GTASA.PNG

Getting involved

Please see our Coding guidelines for information on coding practice.

Additional information

If you need more information, try our bug tracker or IRC channel.

Errors

CL38 error. [netc_d.dll not found]

Solution: Delete Multi Theft Auto_d.exe and hit compile again.

After cloning the repository, it doesn't compile the project

Solution: Execute win-create-projects.bat in main directory.

CL17 Load field. Please ensure that the latest data files have been installed correctly

Solution: Execute win-install-data.bat in main directory.