Compiling MTASA: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(Git != GitHub [don't touch the image])
 
(106 intermediate revisions by 22 users not shown)
Line 3: Line 3:
Please read the instructions carefully and do not skip parts of it, if you have no experience.
Please read the instructions carefully and do not skip parts of it, if you have no experience.


== Prerequisites ==
= [[File:Dialog-warning.svg|32px]] Prerequisites =


You should be using Windows 7 or above, before you can compile the Multi Theft Auto client.
Compiling the Multi Theft Auto client is only supported on Windows 10. Everything also works on Windows 11.
 
[[File:Emblem-important.svg|24px]] '''Skipping any prerequisite steps will lead to unexpected build failures. Read the sections below carefully to understand the entire developer workflow.'''
 
[[File:Process-stop.svg|24px]] '''There are solutions to common problems you may encounter in the [[#Error Troubleshooting]] section below.'''


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 2022 ==
[[File:Visual_Studio_Community.PNG|left|150px|link=https://beta.visualstudio.com/downloads/]]
[[File:Visual_Studio_Community.PNG|right|150px|link=https://www.visualstudio.com/vs/]]
'''Download'''<br>
# Download and install '''[https://visualstudio.microsoft.com/vs/ Microsoft Visual Studio 2022]''' - make sure you get the Community Edition, that one is free.
[https://beta.visualstudio.com/downloads/ Microsoft Visual Studio 2015] (Community Edition is free).<br>
# On the installation checklist, [[:File:VsFoundationClasses.png|make sure you tick these 2 items]]:
## ''Desktop development with C++''
## Optional component ''C++ MFC for latest v143 build tools (x86 & x64)''
 
If you've made a mistake, you can run the ''Visual Studio Installer'' app to modify your current installation. There is no need to uninstall and reinstall.


'''Addon: EditorConfig''' (optional)<br>
== Microsoft DirectX SDK ==
Download: [https://visualstudiogallery.msdn.microsoft.com/c8bccfe2-650c-4b42-bc5c-845e21f96328 EditorConfig]<br>
[[File:DirectX_SDK.jpg|right|150px|link=http://web.archive.org/web/20200804044856/https://www.microsoft.com/en-us/download/details.aspx?id=23549]]
(Install this addon to automatically set up your IDE for the correct code formatting)
'''Download and install Microsoft DirectX SDK (August 2009) (DXSDK_Aug09.exe):'''
* [https://archive.org/download/dxsdk_aug09/DXSDK_Aug09.exe Mirror 1 (archive.org)]
* [https://mega.nz/file/pQJCiAJY#jBcYT6ZP4DMBpnm12BLRto9EQ-RjjpP3BWkSPanpvLI Mirror 2 (mega.nz)]


'''Missing #include "afxres.h"'''<br>
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'''
[[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 ===
See [[Compiling_MTASA/DXSDK_Aug09_Hashes|DXSDK Aug09 Hashes]] for file hashes of the installer.
[[File:DirectX_SDK.jpg|left|150px|link=https://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=6812]]
'''Download'''<br>
[http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=6812 Microsoft DirectX SDK]<br>


'''S1023 Error'''<br>
==[[File:Git_logo.png|left|32px|link=https://git-scm.com/]] Git Client==
[https://support.microsoft.com/en-us/kb/2728613 "S1023" error when you install the DirectX SDK (June 2010)]<br style="clear:both">


=== Git Client ===
If you would like to contribute to MTA, you should use Git. This will allow you to collaborate with us by creating branches and pushing changes to [https://github.com/multitheftauto/ GitHub].
[[File:Git_logo.png|left|32px|link=https://git-scm.com/]]
You have 2 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 ====
[https://learn.microsoft.com/en-us/visualstudio/version-control/git-with-visual-studio '''Visual Studio''' comes with a Git client] that you can use to manage your local repository. You should fork the [https://github.com/multitheftauto/mtasa-blue mtasa-blue repository] and clone on your machine.
[[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">


== Getting the latest source code ==
=[[File:Document-save.svg|32px]] Getting the latest source code=


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


* '''Repository:''' [https://github.com/multitheftauto/mtasa-blue multitheftauto/mtasa-blue]
* '''Repository:''' [https://github.com/multitheftauto/mtasa-blue multitheftauto/mtasa-blue]
Line 53: Line 49:
* '''.tar.gz:''' [https://github.com/multitheftauto/mtasa-blue/archive/master.tar.gz master.tar.gz]
* '''.tar.gz:''' [https://github.com/multitheftauto/mtasa-blue/archive/master.tar.gz master.tar.gz]


== Getting the latest network module ==
=[[File:Media-floppy.svg|32px]] Compiling the code=
 
You should install [http://nightly.mtasa.com/?mtasa-{{Current Version|master}}-full_unstable-latest the latest unstable nightly Windows full installer] into this '''exact''' directory:
    C:\Program Files\MTA San Andreas {{Current Version|master}}\
If you have 64 bit windows, be sure to remove (x86) from the path.
 
Since the '''netc.dll'''/'''net.dll''' network modules for the software are covered by a different license, you will have to use the binary files that get installed with the [http://nightly.mtasa.com/?mtasa-{{Current Version|master}}-full_unstable-latest latest nightly].<br>
If you want to run a debug version of MTA, the client expects a debug version of the net.dll. As we don't provide this, you can append '_d' to a copy of the network dll.


Furthermore, it is advisable to create an empty "timeout.longtime" file in your ''Bin/server/'' directory. 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.
Follow these steps to successfully build the '''mtasa-blue''' project.


== Compilling the code ==
# Execute the script '''win-create-projects.bat'''. This installs dependencies and generates the Visual Studio project files that are mandatory to compile the code.
# Execute the script '''create-projects.bat'''
# Open the solution file '''MTASA.sln''' in the '''Build''' directory. If you are asked to upgrade the project, click '''Cancel'''.
# Open the solution file '''MTASA.sln''' in the '''Build''' directory
# Select '''Debug''' - '''Win32''' configuration in Visual Studio, then press Build > Build Solution (may take some minutes).
# Compile in Visual Studio (may take some minutes)
# Alternatively, you may execute the script '''win-build.bat''', which runs the previous mentioned steps, without the need to open Visual Studio.
## Compile in '''Debug''' config
# Finally, execute the script '''win-install-data.bat'''. This copies important files to the Bin directory that are required for MTA to function. It gives you the option to '''Install the official resources''', which you can read about in the [[#Running the dedicated server]] section below.
## Compile in '''Nightly''' config (you will be missing the essential ''libcef.dll'' if you don't do this step)
# Install data files: '''utils\premake5.exe install_data''' (''Shift + Right-Click'' in the ''<root>'' directory and click on [http://michaelcrump.net/files/image_635243330608233338.png ''Open command window here''])
# Install resources: '''utils\premake5.exe install_resources''' (optional step)


=== Microsoft DirectX SDK (August 2009) includes missing ===
=[[File:Input-gaming.svg|40px]] Running the software=
You can either use the [https://www.microsoft.com/en-us/download/details.aspx?id=23549 DirectX SDK (August 2009)] package or modify the source code to omit this warning to compile the code anyway (might break shaders etc.):<br>
Open the file ''mtasa-blue\Client\core\DXHook\CDirect3DHook9.cpp'' in an editor of your choice and go to the line
  #if D3DX_SDK_VERSION != 42
and change it to
  #if D3DX_SDK_VERSION != 43
(for June 2010 SDK).


= Running the software =
This section contains information on how to run the Multi Theft Auto client and server separately.


== Running the client ==
== 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.<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.
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 ==


If you already have run the step 5 (''Install resources'') in ''Compilling the code'' to install resources then you can goto ''Starting the server''.
If you already have run '''win-install-data.bat''' and selected "''Install resources''" then you can go to [[#Starting the server]].


=== Installing the latest resources ===
=== 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.
If you want to run the Multi Theft Auto dedicated server, you will have to install the official resources. This default package includes resources that implmenent the most basic functionality (e.g. spawning players) in order to play.
 
Our official resources repository is [https://github.com/multitheftauto/mtasa-resources hosted on GitHub]. You can download the latest resources from there or [http://mirror.mtasa.com/mtasa/resources/ download a zipped version]. Make sure that you have the latest resources package.


=== Missing mtaserver.conf ===
Our official resources repository is [https://github.com/multitheftauto/mtasa-resources hosted on GitHub]. You can download the latest resources from there or [http://mirror.multitheftauto.com/mtasa/resources/ download a zipped version]. Make sure that you have the latest resources package.
If you are missing the default configuration files for your server then go ahead and install these from [https://linux.mtasa.com/dl/152/baseconfig-1.5.2.tar.gz here] and extract all three files to '''Bin/server/mods/deathmatch'''.


=== 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'' in the Visual Studio Debugger.
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).
 
= [[File:Preferences-system.svg|32px]] Debugging =
If you already compiled the code in the '''Debug''' configuration then continue reading, if not, then go up to ''Compiling the code'' and follow the steps for a ''Debug'' build.<br>
To compile in '''Release''', click on the '''Debug''' list and switch to '''Release'''.<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
breakpoints will not work for anything besides the MTA Launcher project.<br>
[[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<!--
Actually, its 60 milliseconds? When setting the content to "600", it should be 600 seconds (10 minutes) but the timeout is being set to 36000 seconds (36000 / 600 = 60 ms)
-->, 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:System-users.svg|32px]] Getting involved =
Please see our [[Coding guidelines]] for information on the coding practice.
 
= [[File:Mail-reply-all.svg|32px]] Additional information =
If you need more information, try our [https://github.com/multitheftauto/mtasa-blue/issues bug tracker] or [https://discord.com/invite/mtasa Discord].
 
= Error Troubleshooting =
 
==Cannot open include file 'afxres.h'==
This error is caused by your incomplete Visual Studio configuration. Use the Visual Studio Installer to enable Optional component ''C++ MFC for latest v143 build tools (x86 & x64)''.
 
==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==
[https://support.microsoft.com/en-us/kb/2728613 "S1023" error when you install the DirectX SDK (June 2010)]<br style="clear:both">
 
==Cannot open source file "xxx.h" after upgrading to Visual Studio 2022==
If you've just upgraded to Visual Studio 2022 and were working on MTA using a previous version, you may receive errors about header files not being found (stdio.h, stddef.h, etc) when building the project.
 
Make sure you have the latest Windows 10 SDK installed (via the Visual Studio Installer) and restart your PC.
 
If that doesn't work - close Visual Studio, go into the `Build` folder (where your mtasa-blue is located) and delete the `.vs` folder. Start Visual Studio and everything should be fixed.


If you have any problems with missing DLL files (e.g. libcurl.dll), then you can copy these from your MTA installation.
== CL38 error. [netc_d.dll not found] ==
Solution: Delete '''Multi Theft Auto_d.exe''' and hit compile again.


= Getting involved =
== After cloning the repository, it doesn't compile the project ==
Please see our [[Coding guidelines]] for information on coding practice.
Solution: Execute '''win-create-projects.bat''' in main directory.


= Additional information =
== CL17 Load field. Please ensure that the latest data files have been installed correctly ==
If you need more information, try our [http://bugs.mtasa.com/ bug tracker] or [irc://irc.multitheftauto.com IRC channel].
Solution: Execute '''win-install-data.bat''' in main directory.


== ERROR: Loading network library (net_d.dll) failed! ==
Solution: Execute '''win-install-data.bat''' in main directory.
[[pl:Compiling MTASA]]
[[pt-br:Compilando o MTASA]]
[[pt-br:Compilando o MTASA]]
[[ru:Compiling MTASA]]
[[ru:Compiling MTASA]]
[[Category: Development]]
[[Category: Development]]

Latest revision as of 11:07, 6 November 2024

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.

Dialog-warning.svg Prerequisites

Compiling the Multi Theft Auto client is only supported on Windows 10. Everything also works on Windows 11.

Emblem-important.svg Skipping any prerequisite steps will lead to unexpected build failures. Read the sections below carefully to understand the entire developer workflow.

Process-stop.svg There are solutions to common problems you may encounter in the #Error Troubleshooting section below.

Make sure you have the following software and SDKs installed:

Visual Studio 2022

Visual Studio Community.PNG
  1. Download and install Microsoft Visual Studio 2022 - make sure you get the Community Edition, that one is free.
  2. On the installation checklist, make sure you tick these 2 items:
    1. Desktop development with C++
    2. Optional component C++ MFC for latest v143 build tools (x86 & x64)

If you've made a mistake, you can run the Visual Studio Installer app to modify your current installation. There is no need to uninstall and reinstall.

Microsoft DirectX SDK

DirectX SDK.jpg

Download and install Microsoft DirectX SDK (August 2009) (DXSDK_Aug09.exe):

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

See DXSDK Aug09 Hashes for file hashes of the installer.

Git logo.png
Git Client

If you would like to contribute to MTA, you should use Git. This will allow you to collaborate with us by creating branches and pushing changes to GitHub.

Visual Studio comes with a Git client that you can use to manage your local repository. You should fork the mtasa-blue repository and clone on your machine.

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).

Document-save.svg 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.

Media-floppy.svg Compiling the code

Follow these steps to successfully build the mtasa-blue project.

  1. Execute the script win-create-projects.bat. This installs dependencies and generates the Visual Studio project files that are mandatory to compile the code.
  2. Open the solution file MTASA.sln in the Build directory. If you are asked to upgrade the project, click Cancel.
  3. Select Debug - Win32 configuration in Visual Studio, then press Build > Build Solution (may take some minutes).
  4. Alternatively, you may execute the script win-build.bat, which runs the previous mentioned steps, without the need to open Visual Studio.
  5. Finally, execute the script win-install-data.bat. This copies important files to the Bin directory that are required for MTA to function. It gives you the option to Install the official resources, which you can read about in the #Running the dedicated server section below.

Input-gaming.svg Running the software

This section contains information on how to run the Multi Theft Auto client and server separately.

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 win-install-data.bat and selected "Install resources" then you can go to #Starting the server.

Installing the latest resources

If you want to run the Multi Theft Auto dedicated server, you will have to install the official resources. This default package includes resources that implmenent 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).

Preferences-system.svg Debugging

If you already compiled the code in the Debug configuration then continue reading, if not, then go up to Compiling the code and follow the steps for a Debug build.
To compile in Release, click on the Debug list and switch to Release.
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 besides 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

System-users.svg Getting involved

Please see our Coding guidelines for information on the coding practice.

Mail-reply-all.svg Additional information

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

Error Troubleshooting

Cannot open include file 'afxres.h'

This error is caused by your incomplete Visual Studio configuration. Use the Visual Studio Installer to enable Optional component C++ MFC for latest v143 build tools (x86 & x64).

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)

Cannot open source file "xxx.h" after upgrading to Visual Studio 2022

If you've just upgraded to Visual Studio 2022 and were working on MTA using a previous version, you may receive errors about header files not being found (stdio.h, stddef.h, etc) when building the project.

Make sure you have the latest Windows 10 SDK installed (via the Visual Studio Installer) and restart your PC.

If that doesn't work - close Visual Studio, go into the `Build` folder (where your mtasa-blue is located) and delete the `.vs` folder. Start Visual Studio and everything should be fixed.

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.

ERROR: Loading network library (net_d.dll) failed!

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

Retrieved from "https://wiki.multitheftauto.com/wiki/Compiling_MTASA?oldid=80992"