# How to build

## Requirements

- dotnet core 2.1+

## Versioning

The version is automatically generated whenever the projects are built, using the [Nerdbank.GitVersionining](https://github.com/aarnott/Nerdbank.GitVersioning) package. This package generates semver versions based on the version set in the `version.json` file at the root of the repo + the commit height since the last time the version was updated.

Not all changes affect the commit height/version update. Only changes in the paths tracked by the `src/version.json` file cause version updates.

By default, only builds from branches/tags that match the regex in the [version.json](version.json) file at the root of the repo will be stamped with a public release (semantic) version, and other builds will be preview builds.

- C#/nuget public version format: `X.Y.[commit height]`.
- C#/nuget non-public version format: `X.Y.[commit height]-g[commit hash]`.
- Packman public version format: `X.Y.[commit height]`.
- Packman non-public version format: `X.Y.[commit height]`-preview-g[commit hash].

If the fixed part of the version in the `version.json` file is a semver preview version (i.e. it contains a `-alphanumeric` suffix), then the versioning is as follows: 

- C#/nuget public version format: `X.Y.[commit height]-alphanumeric`.
- C#/nuget non-public version format: `X.Y.[commit height]-alphanumeric-g[commit hash]`.
- Packman public version format: `X.Y.[commit height]-preview-alphanumeric`.
- Packman non-public version format: `X.Y.[commit height]`-preview-alphanumeric-g[commit hash].

## Command line build scripts

- `build.cmd`/`build.sh`: Build shell script for Windows command line or Windows/Mac/Linux bash. 
- `pack.cmd`/`pack.sh`: Packaging shell script for Windows command line or Windows/Mac/Linux bash. 
- `test.cmd`/`test.sh`: Test shell script for Windows command line or Windows/Mac/Linux bash. 

All shell scripts take the same parameters:

- `-r|--release`: Release build (default)
- `-d|--debug`: Release build (default)
- `-p|--public`: Stamp a build with a public release version. See the [versioning](#versioning) section for details

### Visual Studio

To build with Visual Studio, open the solution file `GitForUnity.sln`. Select `Build Solution` in the `Build` menu.

## Build artifacts

Before opening the Unity projects in the `UnityProjects` folder, you should build at least once, so that required binaries are generated in the right places.

Note: If you build while having a Unity project open that points to the sources or build artifacts, some files might be locked by Unity if have one of the build output projects open when you compile from VS or the command line. This is expected and shouldn't cause issues with your builds.

### Packman (npm) sources

The sources and tests for each package are versioned and copied to `build/packages` as part of the build process. Metafiles for autogenerated build artifacts (like the `Version.cs` file generated during the build) are copied from the `extras/[name of package]` folder into `build/packages`.
The artifacts in `build/packages` are used for packaging during the `pack` step.

## Packaging

### Windows

- Release build packaging: `.\pack`
- Debug build packaging: `.\pack -d`
- Build and pack in one: `.\pack -b`

### Mac, Linux, Windows Bash

- Release build packaging: `./pack.sh`
- Debug build packaging: `./pack.sh -d`
- Build and pack in one: `./pack.sh -b`

## Packaging artifacts

### Packman (npm)

- Location: `upm-ci~/packages`

### Nuget

- Location: `build/nuget`

## Testing

### Windows

- Test release: `.\test`
- Test debug: `.\test -d`
- Build and test: `.\test -b`

### Mac, Linux, Windows Bash

- Test release: `./test.sh`
- Test debug: `./test.sh -d`
- Build and test: `./test.sh -b`

## Where are the build artifacts?

Packages sources are in `build/packages`.

Nuget packages are in `build/nuget`.

Packman (npm) packages are in `upm-ci~/packages`.

Binaries for each project are in `build/bin` for the main projects, `build/Samples/bin` for the samples, and `build/bin/tests` for the tests.

## How to bump the major or minor parts of the version

The `version.json` file in the root of the repo controls the version for all packages.
Set the major and/or minor number in it and **commit the change** so that the next build uses the new version.
The patch part of the version is the height of the commit tree since the last manual change of the `version.json`
file, so once you commit a change to the major or minor parts, the patch will reset back to 0.