Arma3_Epoch/ACE3
1
0
Fork 0
mirror of https://github.com/acemod/ACE3.git synced 2024-08-30 18:23:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge #3826

Browse Source
This commit is contained in:
jonpas 2017-02-07 03:56:39 +01:00
parent b2986cea8a
commit 6037daadde
1 changed files with 33 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
docs/wiki/development/setting-up-the-development-environment.md
View File

@ -1,108 +1,68 @@
--- ---
layout: wiki layout: wiki
title: Setting Up The Development Environment title: Setting Up The Development Environment
description: This page describes how you can setup your development environment for ACE3, allowing you to properly build ACE and utilize file patching. description: This page describes how you can setup your development environment for ACE3, allowing you to properly build ACE3 and utilize file patching.
group: development group: development
parent: wiki parent: wiki
order: 0 order: 0
--- ---
This page describes how you can setup your development environment for ACE3, allowing you to properly build ACE and utilize file patching. This page describes how you can setup your development environment for ACE3, allowing you to properly build ACE3 and utilize file patching.
## 1. Requirements ## 1. Getting Source Code
- Arma 3
- A proper installation of the Arma 3 Tools (available on Steam)
- A properly setup P-drive
- Run Arma 3 and Arma 3 Tools directly from steam once to install registry entries (and again after every update)
- [Python 3.x](https://www.python.org/)
- [Mikero Tools](https://dev.withsix.com/projects/mikero-pbodll/files): DePbo, DeRap, DeOgg, Rapify, MakePbo, PboProject
- `*.hpp` removed from PboProject's "Exclude From Pbo" list
- Python, Mikero Tools and Git in PATH environment variable
- [CBA](https://github.com/CBATeam/CBA_A3/releases/latest) mod (release or development version)
## 2. Why so complicated?
If you have contributed to AGM you might be used to an easier build process, where there was even an .exe you could use for building. ACE3, however, makes use of CBA macros to simplify things and give the developer access to a better debug process, which requires a stricter build environment. Additionally, Mikero's Tools are stricter and report more errors than AddonBuilder does. The structure of this development environment also allows for [file patching](#7-file-patching), which is very useful for debugging.
Not offering .exes for the Python scripts we use allows us to make easy changes without the hassle of compiling self-extracting exes all the time.
## 3. Getting Source Code
To actually get the ACE3 source code on your machine, it is recommended that you use Git. Tutorials for this are all around the web, and it allows you to track your changes and easily update your local copy. To actually get the ACE3 source code on your machine, it is recommended that you use Git. Tutorials for this are all around the web, and it allows you to track your changes and easily update your local copy.
If you just want to create a quick and dirty build, you can also directly download the source code using the "Download ZIP" button on the front page of the GitHub repo. If you just want to create a quick and dirty build, you can also directly download the source code using the "Download ZIP" button on the front page of the GitHub repo.
## 4. Setup and Building ## 2. Setup and Building
### 4.1 Initial Setup ### 2.1 Windows
Navigate to `tools` folder in command line. On Windows, you can use the make.bat file for creating a simple build of all PBOs using the packaged version of armake.
``` If you want more advanced features like only rebuilding changed addons or automated release packaging, you'll have to aquire `make` for Windows or use a Linux environment on Windows such as Cygwin or the Windows Subsystem for Linux in Windows 10 and then simply follow the Linux instructions.
cd "[location of the ACE3 project]\tools"
```
Execute `setup.py` to create symbolic links to P-drive and Arma 3 directory required for building. ### 2.2 Linux
On Linux, you'll have to aquire armake from the appropriate source for your distribution. Check the [armake repository](https://github.com/KoffeinFlummi/armake) for instructions for your distribution. Example for Ubuntu:
Should the script fail, you can create the required links manually. First, create `z` folders both in your Arma 3 directory and on your P-drive. Then run the following commands as admin, replacing the text in brackets with the appropriate paths:
```bat
mklink /J "[Arma 3 installation folder]\z\ace" "[location of the ACE3 project]"
mklink /J "P:\z\ace" "[location of the ACE3 project]"
```
Then, copy the `cba` folder from the `tools` folder to `P:\x\cba`. Create the `x` folder if needed. That folder contains the parts of the CBA source code that are required for the macros to work.
## 4.2 Creating a Test Build
To create a development build of ACE3 to test changes or to debug something, run the `build.py` file in the `tools` folder. This will populate the `addons` folder with binarized PBOs. These PBOs still point to the source files in their respective folders however, which allows you to use [file patching](#file-patching). This also means that you cannot distribute this build to others.
To start the game using this build, you can use the following modline:
```sh ```sh
-mod=@CBA_A3;z\ace $ sudo add-apt-repository ppa:koffeinflummi/armake
$ sudo apt-get update
$ sudo apt-get install armake
``` ```
## 4.3 Creating a Release Build Then, simply navigate to the ACE3 project directory and run `$ make`
To create a complete build of ACE3 that you can use without the source files you will need to: Other make targets include:
- Ensure `.hpp` is **NOT** in pboProject's "Exclude From Pbo" list - `$ make signatures` - Creates a signed build.
- `$ make release` - Creates a signed build and packages it into a zip file ready for release.
When the requirements are met: - `$ make filepatching` - Creates a build usable for filepatching.
- Execute `make.py version increment_build <other-increment-args> force checkexternal release` in the `tools` folder, replacing `<other-increment-args>` with the part of version you want to increment (options described below)
This will populate the `release` folder with binarized PBOs, compiled extensions, copied extras, bisigns and a bikey. Additionally, an archive file will also be created in the folder. The folder and archive handle like those of any other mod.
Different `make.py` command line options include:
- `version` - update version number in all files and leave them in working directory (leaving this out will still update the version in all files present in the `release` folder, but they will be reverted to not disturb the working directory)
- `increment_build` - increments _build_ version number
- `increment_patch` - increments _patch_ version number (ignored with `increment_minor` or `increment_major`)
- `increment_minor` - increments _minor_ version number and resets _patch_ version number to `0` (ignored with `increment_major`)
- `increment_major` - increments _major_ version number and resets _minor_ and _patch_ version numbers to `0`
- `force` - force rebuild all PBOs, even those already present in the `release` directory (combined with `compile` it will also rebuild all extensions)
- `checkexternal` - check external references (incompatible only with `<component1> <component2>` and `force <component1> <component2>`)
- `release` - create release packages/archives
- `<component1> <component2>` - build only specified component(s) (incompatible with `release`)
- `force <component1> <component2>` - force rebuild specified component(s) (incompatible with `release`)
## 7. File Patching ## 3. File Patching
File Patching allows you to change the files in an addon while the game is running, requiring only a restart of the mission. This makes it great for debugging, as it cuts down the time required between tests. Note that this only works with PBOs created using MakePBO, which `build.py` uses. File Patching allows you to change the files in an addon while the game is running, requiring only a restart of the mission. This makes it great for debugging, as it cuts down the time required between tests. Note that this only works with PBOs created using `$ make filepatching`.
For file patching to work, you need a symbolic link from "[Arma 3 installation folder]/z/ace" to your ACE3 project folder. To do this on Windows and Linux respectively, run these commands:
```sh
$ # Windows
$ mkdir "[Arma 3 installation folder]\z"
$ mklink /J "[Arma 3 installation folder]\z\ace" "[location of the ACE3 project]"
$ # Linux
$ mkdir "[Arma 3 installation folder]/z"
$ ln -s "[Arma 3 installation folder]/z/ace" "[location of the ACE3 project]"
```
To run Arma 3 with file patching add the `-filePatching` startup parameter (since Arma 3 v1.50, file patching is disabled by default). To run Arma 3 with file patching add the `-filePatching` startup parameter (since Arma 3 v1.50, file patching is disabled by default).
### 7.1 Disabling CBA Function Caching ### 3.1 Disabling CBA Function Caching
By default CBA caches a compiled version of functions to reduce mission load times. This interferes with file patching. There are three ways to disable function caching: By default CBA caches a compiled version of functions to reduce mission load times. This interferes with file patching. There are three ways to disable function caching:
@ -127,7 +87,7 @@ class CfgSettings {
#define DISABLE_COMPILE_CACHE #define DISABLE_COMPILE_CACHE
``` ```
### 7.2 Restrictions ### 3.2 Restrictions
Files must exist in the built PBOs for file patching to work. If you create a new file you must rebuild the PBO or Arma will not find it in your file paths. Files must exist in the built PBOs for file patching to work. If you create a new file you must rebuild the PBO or Arma will not find it in your file paths.