DEV Community: Isaac Broyles

Building Unity with GitHub Actions

Isaac Broyles — Sat, 04 Jul 2020 00:00:00 +0000

I recently began doing some work on a personal project in Unity Engine. As with any of my projects, the first thing I set up is a working CI pipeline for it. I find doing this early reinforces best practices. I liked the option of using GitHub Actions, since it is a relatively small project. Here's how I did it!

Getting Started

First, familiarize yourself with the community offerings for GitHub Actions - game-ci/unity-actions. There's a good overview here in the readme of the supported actions.

The other thing to check would be the official game-ci getting starting docs.

Setting up License

The instructions in the official docs aren't the most verbose, but it's actually quite simple.

I'll just go into a little more detail here to try to make things super clear.

Step 1 - Request Activation File on GitHub

This is an action that is intended to be a one-time use. Its purpose is to create a "license request file" that will be needed for the next step. This is what will allow unity to run builds on the GitHub Actions servers.

The file should end up looking something like this:

.github/workflows/activation.yml:

name: Acquire activation file
on:
  workflow_dispatch: {}
jobs:
  activation:
    name: Request manual activation file 🔑
    runs-on: ubuntu-latest
    steps:
      # Request manual activation file
      - name: Request manual activation file
        id: getManualLicenseFile
        uses: game-ci/unity-request-activation-file@v2
      # Upload artifact (Unity_v20XX.X.XXXX.alf)
      - name: Expose as artifact
        uses: actions/upload-artifact@v2
        with:
          name: ${{ steps.getManualLicenseFile.outputs.filePath }}
          path: ${{ steps.getManualLicenseFile.outputs.filePath }}

After you push it up, you can manually run the worfklow to generate your license.

To find this file, go to GitHub > Your Repository > Actions. Click on the commit that last ran. You should find a file named something like Unity_v2019.3.14f1.alf. (The exact name depends on the version string that you put in unityVersion above.)

You'll need to save this file locally for use in the next step.

Step 2 - Request License from Unity

Head over to the Unity Manual Activation link.

Here you simply upload your .alf file from the previous step. Fill out the form with your license details.

On the last step you should be able to download a file that ends in .ulf.

This is your license you will put in GitHub secrets for use in your build actions.

Step 3 - Save License in GitHub Secrets

Open GitHub > Your Repository > Settings > Secrets.

Create a secret called UNITY_LICENSE and add the contents of the obtained license file (.ulf). Yes, add the entire XML contents to the GitHub secret.

Now that this step is done, you can delete the .github/workflows/activation.yml file.

Set up workflow

Now's the fun stuff! Now that you have your license ready to go, you can start setting up actions.

A couple of best practice recommendations:

Cache your Library folder. This is where all your cached packages and large files end up during builds.
- Note caches created on branches are scoped to that branch, regardless of key matches. Same goes for tags.
Use GitHub Releases to store your file, not actions artifacts. You will quickly run into free limits using artifacts
Due to the size and time of full builds, I like to generate target builds only on tags.

Here's an example of a couple of workflow files.

Test - Runs on every commit

.github/workflows/test.yml:

name: Test

on:
  pull_request: {}
  push: { branches: [master] }

env:
  UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}

jobs:
  build:
    name: Test project
    runs-on: ubuntu-latest
    steps:

      # Checkout
      - name: Checkout repository
        uses: actions/checkout@v2
        with:
          lfs: true

      # Cache
      - uses: actions/cache@v2
        with:
          path: Library
          key: Library

      # Test
      - name: Run tests
        uses: game-ci/unity-test-runner@v2
        with:
          unityVersion: 2020.3.15f2

Build - Runs on tagged commits

This file uses this on.push.tags trigger to only run when tags are pushed.

It then uploads artifacts, zips up the binaries, creates a GitHub release for the tag, and uploads the release assets to it.

Depending on your usage, you might not want to upload the artifacts. You'll quickly run into limits if you use it too much.

.github/workflows/main.yml:

name: Build

on:
  push:
    tags:
      - '*'

env:
  UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}

jobs:
  build:
    name: Build my project
    runs-on: ubuntu-latest
    steps:

      # Checkout
      - name: Checkout repository
        uses: actions/checkout@v2
        with:
          lfs: true

      # Cache
      - uses: actions/cache@v2
        with:
          path: Library
          key: Library

      # Test
      - name: Run tests
        uses: game-ci/unity-test-runner@v2
        with:
          unityVersion: 2020.3.15f2

      # Build
      - name: Build project
        uses: game-ci/unity-builder@v2
        with:
          unityVersion: 2020.3.15f2
          targetPlatform: StandaloneWindows64 

      # Output 
      - uses: actions/upload-artifact@v2
        with:
          name: Build
          path: build

      - name: Zip build
        run: |
          pushd build/StandaloneWindows64
          zip -r ../../StandaloneWindows64.zip .
          popd

      - name: Release
        uses: softprops/action-gh-release@v1
        with:
          files: StandaloneWindows64.zip
          name: Release ${{ github.ref }}

Note: If you're using the above workflow, and experience an error on the build step like this:

Warning: Changes were made to the following files and folders:

Warning: ?? artifacts/

Error: Branch is dirty. Refusing to base semantic version on uncommitted changes

You will need to add the artifacts folder to your .gitignore file, as referenced in this GitHub issue.

Another option would be using the allowDirtyBuild flag if you are still running into dirty branch issues.

Feel free to customize for your use case, as this workflow only outputs windows binaries. However, as mentioned in game-ci/unity-actions, there's a ton more supported actions/options.

Conclusion

Setting up a CI flow early tends to keep me honest in following best practices. I like to do it even for my hobby projects.

A good side effect, is if I have to let projects idle for a while, I can always come back and expect my builds to work.

How to effectively use Model Mapper

Isaac Broyles — Sun, 15 Jul 2018 00:00:00 +0000

I had the pleasure of modifying a large code base that extensively used Model Mapper. I ran into some issues using it blindly, and I did not have much luck searching for answers. Most of the information in this blog posts already exists elsewhere, but I was suprised that it was not very visible on google. Hopefully we can correct that.

Here are my tips for effective use of ModelMapper.

Use and understand PropertyMap

The first thing you should understand are the nuances of configuring a PropertyMap, which I personally found unintuitive. It wasnt until scouring the documentation and a few well written Stack Overflow posts that everything started to click.

If you’re like me, this first thing you’ll run up against when searching for help is running across an unintuitive example like this:

public class MyMapper extends PropertyMap<Source, Destination>{
    @Override
    protected void configure(){
        map(source.getProperty()).setOther(null);
    }
}

The reason why this is confusing, is why would I “set” my destination property to null?

The configure() function contains EDSL

The answer is, the code in the configure() method is not actually executed as part of your mapping at all. It is actually an Embedded Domain Specific Language (EDSL). This is the number one thing that made my understanding of Model Mapper so much clearer.

You can read more about how the EDSL works in the official javadocs.

This gist is this:

The mapping is not executed as Java code. The PropertyMap.configure() is not being executed during the mapping process. You can validate this by setting a breakpoint in the method while debugging a mapping.
The mapping is interpreted by ModelMapper when the mappings are added using addMapping(...).
Converter.convert()’s are executing during runtime. So you can do something like this:

public class MyMapper extends PropertyMap<Source, Destination>{
    private Converter<String, String> toUppercase = (c) -> {
        return c.getSource().toUpperCase();
    };

    @Override
    protected void configure(){
        using(toUppercase)
            .map(source.getProperty())
            .setOther(null);
    }
}

And the code in the toUppercase converter will be executed each time the objects are mapped.

Use TDD when defining mappings

I cover unit testing in the next section, but bring it up here because it can reduce boilerplate. ModelMapper actually does a pretty good job on its own in most cases. If you define what you expect in tests, it will force you to do the bare minimum definition in the PropertyMap.

For example, if you were to naively define a PropertyMap without running any tests, you might end up with something as verbose as this:

public class OverkillPropertyMap
        extends PropertyMap<PersonDto, Person> {

    @Override
    protected void configure() {
        map(source.getFirstName(), destination.getFirstName());
        map(source.getLastName(), destination.getLastName());
        map(source.getEmail(), destination.getEmail());
        map(source.getPhone(), destination.getPhone());
        map(source.getAddress1(), destination.getAddress1());
        map(source.getAddress2(), destination.getAddress2());
        map(source.getCity(), destination.getCity());
        map(source.getState(), destination.getState());
        map(source.getZip(), destination.getZip());
        map(source.getCountry(), destination.getCountry());

    }
}

This is a contrived example that can seem silly to an experienced developer, but you’d be surprised at how many mappings like these pop up in codebases.

Let’s see if we can simplify this in the next section with a unit test.

Unit Testing

The ModelMapper official docs state that you should always unit test mappings, and I fully agree. As with most issues, it’s much easier to catch things in unit tests than later on in the SDLC.

Here are the two things to always cover in your mapping unit tests:

Always use ModelMapper.validate()
Verify fields are being mapped with assertEquals(…)

ModelMapper.validate()

The handy method will verify that all destination properties are matched. This is extremely useful if somebody forgets to map a destination property after adding it. In other words, this will protect your mapper from future changes to both source/destination objects.

If you are getting false positives here, you can skip properties in your mapping:

skip(destination.getPropertyNotMapped());

Example of effective unit test

Going back to the example from the last section, except let’s start with a unit test this time.

A standard unit test would look something like this:

public class PersonMapTests {
    private ModelMapper modelMapper;

    @Before
    public void setup(){
        modelMapper = new ModelMapper();
        modelMapper.addMappings(new PersonMap());
        modelMapper.getConfiguration()
            .setMatchingStrategy(MatchingStrategies.STRICT);
    }

    @Test
    public void map_ShouldValidate_IfObjectsValid(){
        var personDto = preparePersonDto();

        var personModel =
            modelMapper.map(personDto, Person.class);

        modelMapper.validate();

        assertEquals(
            personDto.getFirstName(), personModel.getFirstName());
        assertEquals(
            personDto.getLastName(), personModel.getLastName());
        assertEquals(
            personDto.getEmail(), personModel.getEmail());
        assertEquals(
            personDto.getPhone(), personModel.getPhone());
        assertEquals(
            personDto.getAddress1(), personModel.getAddress1());
        assertEquals(
            personDto.getAddress2(), personModel.getAddress2());
        assertEquals(
            personDto.getCity(), personModel.getCity());
        assertEquals(
            personDto.getState(), personModel.getState());
        assertEquals(
            personDto.getCountry(), personModel.getCountry());
        assertEquals(
            personDto.getZip(), personModel.getZip());
    }

    private PersonDto preparePersonDto() {
        return new PersonDto.Builder()
                .firstName("Isaac")
                .lastName("Broyles")
                .email("isaacbroyles@example.com")
                .phone("202-555-0129")
                .address1("123 Street")
                .address2("Apt 101")
                .city("Ville")
                .state("TX")
                .zip("12345")
                .country("USA")
                .build();
    }
}

In running this unit test, I get an error like this:

1) Unmapped destination properties found in TypeMap[PersonDto -> Person]:

com.isaacbroyles.examples.modelmapperexamples.models.Person.setLastModified()

Uh oh, the validate() method is showing us that we have a destination property that is not mapped. So let’s define a PropertyMap to fix that issue.

Here is the property map, with just the minimal code to fix my error:

public class PersonMap extends PropertyMap<PersonDto, Person> {
    @Override
    protected void configure() {
        map(source.getDateCreated(),
            destination.getLastModified());
    }
}

Now I rerun my test – Oh cool, it passes now.

Compare the PropertyMap we ended up with to the OverkillPropertyMap in the previous section. All the other properties were automatically mapped, even with MatchingStrategies.STRICT.

Conclusion

I’m somewhat conflicted over whether I like the usage of ModelMapper or not. On the one hand, it provides a good way to reduce boilerplate mapping code. On the other hand, some of the rather unintuitive aspects of it have caused me headache. This isn’t necessarily a critique of ModelMapper, and probably speaks more to my inexperience with it than any lacking on the tool’s part. It has obviously grown to be a popular tool for a good reason.

Regardless, I thought this post would prove useful to others who are in a codebase that uses ModelMapper, and are running into the same kinds of issues.

DEV Community: Isaac Broyles

Building Unity with GitHub Actions

Getting Started

Setting up License

Step 1 - Request Activation File on GitHub

Step 2 - Request License from Unity

Step 3 - Save License in GitHub Secrets

Set up workflow

Test - Runs on every commit

Build - Runs on tagged commits

Conclusion

Related Links

How to effectively use Model Mapper

Use and understand PropertyMap

The configure() function contains EDSL

Use TDD when defining mappings

Unit Testing

ModelMapper.validate()

Example of effective unit test

Conclusion

Related Links