Support activeBuildProfile parameter

[ryo0ka]

Context

Enhancing #674 to cover more use cases.

Unity 6000+'s new feature "build profile" comes with multiple benefits:

1. Allows to override project/build configurations per profile
2. Allows to compile the project with profile-specific preprocessors before the build function is invoked

Current implementation by @MichaelBuhler (5eccc32) covers 1, but not 2.

Calling BuildProfile.SetActiveBuildProfile() during build script will not apply preprocessors, as documented here:

[...] when the Editor runs in batch mode, it runs “headless”, so there is no editor loop which would cause it to recompile with the new scripting symbols. Because of this, you should not use Editor scripts to set scripting symbols within a batch mode CI server because the scripts will not be recompiled, so they will not be applied.

It'll affect projects that manage code stripping like this:

#if PROFILE_A_LOADED
using ProfileA.Specific.Module;
ProfileA.Specific.Module.DoSomething();
#endif

We can cover this by passing buildProfile to -activeBuildProfile. In previous discussion, we went over compatibility mitigation:

1. We continue to use targetPlatform to identify which Docker image to pull.
2. If buildProfile is given by user, we pass it to -activeBuildProfile; otherwise we pass targetPlatform to -buildTarget.
3. In case users made a mistake to specify a mismatching pair of targetPlatform and buildProfile, build may fail (undefined behavior).

Regarding 3, previous discussion went over the possibility of reading the profile (yaml). I personally feel like not doing it because the file content format is not documented and it's a fairly new feature.

There was another compatibility issue surrounding the default build function but @MichaelBuhler has gracefully implemented a branching logic.

Suggested solution

Current implementation passes buildProfile to -customBuildProfile. Maybe we can simply reroute it to -activeBuildProfile but maybe I'm not seeing other compatibility issues?

Considered alternatives

Running two passes of unity-build action: (1) run the action with a function that sets active build profile and (2) run the action again with another function that actually runs the build.

Additional details

The -activeBuildProfile's behavior (that it invokes script compilation before -executeMethod function call) is actually not officially documented as far as I searched over their API documentation, but I believe that they just forgot to mention it. I've submitted a ticket to their documentation page assuming they ever read those.

[webbertakken]

Thank you so much for the clear write up!

To add: When searching the docs for -customBuildProfile flag or trying to find it in the v6000 command line arguments doc, you'll not find anything.

Looks like the parameter has evolved to become -activeBuildProfilein newer versions and -customBuildProfile isn't documented at all?

I'm happy with this approach if nobody else sees issues with it. It would be really nice if you could test what happens if we pass both flags (for possible backward compatibility).

If there's a breaking change we'll have to do a major release (fine if we must).

[webbertakken]

@davidmfinol @frostebite @GabLeRoux @AndrewKahr your thoughts?

[ryo0ka]

@webbertakken

Looks like the parameter has evolved to become -activeBuildProfile in newer versions and -customBuildProfile isn't documented at all?

I doubt -customBuildProfile had ever existed in the official specification. I'm assuming that @MichaelBuhler couldn't use -activeBuildProfile for some compatibility issue (that I'm not seeing now) and had to fall back to this custom parameter, which his revised build function picks up, finds a matching asset and sets as the active profile.

It would be really nice if you could test what happens if we pass both flags (for possible backward compatibility).

Will do. My hypothesis is that -customBuildProfile does nothing if Michael's build script chose not to pick it up; let's see.

Also the project doesn't seem to have a v6000+ unity project for testing so I'll try to create it next to the v2021 one and put both in the test cases if I managed to figure out how to.

[webbertakken]

Also the project doesn't seem to have a v6000+ unity project

Yes, we need new maintainers who have time to move things forward. I haven't used Unity in many years myself so I'm often out of context myself as well. Just trying on a best effort basis in the time we have to spare.