Unity Developer KB - lochrist/DocHoliday GitHub Wiki

This is a Knowledge base of snippets and shortcut to help your work as a Unity Developer (git, confluence and internal Unity tools)

• Okta
• Unity Internal Doc
• Service Desk

In base repo folder:

• git worktree add ../path-to-new-worktree trunk

• To list all commits directly one the branch ( not coming from merge ) since the git command line is :

  • git log --oneline --no-merges --first-parent <hash>..HEAD

Very useful for listing commits since last trunk PR.

• To rebase and force push:

  • git rebase -i origin/base-branch
  • git push origin <your_branch_name> -f

• If you merge trunk in a branch and someone else pushes to it before you merge, you need to:

  • git fetch -p
  • git merge <LATEST-COMMIT-SHA>
  • git commit -m "Merge latest changes"
  • git push

• git pull --rebase <remote>

• git checkout -b <branch>

• git merge <branch>

Rebasing on hierarchy/develop

• git pull --rebase origin hierarchy/develop
• Fix all conflicts
• git push --force # You need to force push to force rewriting commit history

• Diff against local branch: git difftool -d -b <branch name>
• Diff file: git diff branch1:file branch2:file

• git stash : Put current changes in your working directory into stash for later use.
• git stash pop: Apply stored stash content into working directory, and clear stash.

• git mergetool <filename>

• Discard changes in working directory. This operation is unrecoverable. : git checkout -- [file]
• Reset staging area to match most recent commit, but leave the working directory unchanged. git reset
• Reset staging area and working directory to match most recent commit and overwrites all changes in the working directory: git reset --hard
• Resets both the staging area & working directory to match. Deletes uncommitted changes, and all commits after . : git reset --hard <commit>

• git clean -dffx

<any diff expression> > ../patches/patchfile.patch

Generate a patch

• Apply a Patch: git apply --reject patch_file.patch (--reject will apply as mush as possible even if some part fail)
• If patch file is properly formatted git am -3 <patch file>
• Fork has a nice Apply patch functionality. Not sure if it keeps conflict markers.

Generate a path from a PR:

• Just add .patch or .diff to the github PR
• Example: https://github.cds.internal.unity3d.com/unity/unity/pull/24030.diff

Assuming origin/feature_branch is your feature branch and you want to squash it against trunk

• git reset --soft trunk
• git add .
• git commit -m "squash it baby!"

from stackoverflow

• 50 commands you should know
• Cheat sheet Poster
• Bigger and better cheatsheet

• Use Merge Vision
• This internal doc article gives more info on this process.

• Build Debug with
  • je
• Build Release with
  • jer
• Build visual studio solution with
  • jp
• If building solutions gives errors, try
  • ./jam ProjectFiles -sUSE_JAM_BACKEND=1
• Open visual studio solution with
  • de
• To build the Standalone player
  • ./jam WinPlayer -sCONFIG=debug|release
• To build the bugreporter
  • ./jam bugreporter -sCONFIG=debug|release
• To build old versions of Unity
  • ./jam Editor* -sCONFIG=debug|release (*Editor or WinEditor)

• Open the Unity hub
  • unity
• Open unity with a project
  • unity -projectpath path/to/project
• Open unity with a new project
  • unity -createproject path/to/new/project
• Open unity with a new project from a template
  • `unity -createproject path/to/new/project -cloneFromTemplate path/to/templat
• Open unity with a new project and no UPM cache
  • UPM_NPM_CACHE_PATH=D:/Temp/npm UPM_CACHE_PATH=D:/Temp/upm unity -createproject path/to/new/project
• Launch a dev Unity build like a build from the Hub
  • D:\travail\unity\hub-installs\2022.1.0a12\Editor\Unity.exe -projectpath D:/travail/unity/projects/fogbugz/case-1367675 -useHub -hubIPC -cloudEnvironment production -hubSessionId YOUR_SESSION_ID -accessToken YOUR_ACCESS_TOKEN
• With UTR:

run.bat --projectpath Modules/QuickSearch/Tests/QuickSearch
run.bat --projectpath ../code/UniLisp/projects/UniLispExamples
run.bat --projectpath ../Projects\UnityProjectsTemplates\DragonCrashers

• In Batch mode like Katana

  • unity -projectPath "C:\Work\tests\NewSceneTemplate_2020" -batchmode -testPlatform editmode -forgetProjectPath -automated "-forceFullStacktrace Assert" -api-profile NET_Standard_2_0 -runTests -automated -accept-apiupdate

• With UTR:

  • perl utr.pl --suite=editor --fail-on-assert --generate-test-projects=verified --testproject=com.unity.quicksearch --zero-tests-are-ok=1 --testfilter=Unity.QuickSearch.QuickSearchToolTests.Search_SceneObjects(1)
  • perl utr.pl --suite=editor --fail-on-assert --zero-tests-are-ok=1 --testproject=Modules/QuickSearch/Tests/QuickSearch --clean-library - perl utr.pl --suite=editor --fail-on-assert --zero-tests-are-ok=1 --testproject=Tests/EditModeAndPlayModeTests/GraphToolsFoundation --clean-library

• With UTR like Yamato

  • Need qs_run_test project (found on Seb's google drive)
  • Modify manifest.json accordingly.
  • Copy this function into batch_profile:

  function utr() {
      array=( "${@}" )
      title 'testing...'
      pd="$(dirname "$1")"
      test_name="$(basename "$1")"
      pl='./artifacts/projectlist.txt'
      echo "$pd" > $pl
      perl utr.pl --suite=editor --projectlist=$pl --open-report --testproject=$test_name ${array[@]:1}
      local RETVAL=$?
      if [ $RETVAL -ne 0 ] ; then
          error "TEST $test_name"
          return $RETVAL
      else
          update_title
      fi
  }
  

  • utr ../tests/qs_run_tests --clean-library

  • utr ../tests/qs_run_tests --clean-library --testfilter=TransactionManagerTests --editor-location="D:\travail\unity\hub-installs\2020.2.0a18\Editor"

• PureCSharpTests: perl utr.pl --suite=integration --testfilter=ExpressionEvaluatorTests

• Run ApiUpdater tests: perl utr.pl --suite=ApiUpdater

• Run Native tests: perl utr.pl --fail-on-assert --suite=NativeEditor

• Some useful parameters for utr:

  • --reruncount=VALUE The maximum number of times to re-run failed tests to discover instabilities, Default value: 0

  • --repeat=VALUE Repeat test execution n times, Default value: 0

  • --replay-path=VALUE Replays test session from specified path

• Some useful parameters when running Unity:

  • -createproject
  • -cleanTestPrefs

Useful test args: --testproject=Modules/QuickSearch/Tests/QuickSearch --repeat=1

• perl utr.pl --suite=editor --testproject=Modules/QuickSearch/Tests/QuickSearch --open-report -cleanTestPrefs --testfilter=SceneProviderTests

• perl utr.pl --suite=editor --testproject=Tests/EditModeAndPlayModeTests/SceneTemplate

• perl utr.pl --suite=editor --testproject=Tests/EditModeAndPlayModeTests/EditorModes

• perl utr.pl --suite=editor --testproject=Tests/EditModeAndPlayModeTests/InspectorWindow

• perl utr.pl --suite=editor --testproject=Tests/EditModeAndPlayModeTests/ShortcutManagerInit

• perl utr.pl --suite=editor --testproject=Hierarchy

• To attach and debug to a test running with UTR, you have two choices:

  • Add this line where you want to break: System.Diagnostics.Debugger.Launch();

  Sometimes it doesn't work. You can also add the folowing parameter to utr:

  • --debug

To run the native tests:

• ./run test native HierarchyCore
• ./run test native Hierarchy

In order to debug native tests you can:

• Compile Unity in debug
• run the following Unity command:
• perl utr.pl --suite=native --testfilter=HierarchyCore --debug
• This will allow you to attach your debugger to the process and you can put break point in your native tests.

You can also start unity using Visual Studio and specify the following switch:

• -runNativeTests HierarchyCore

No satisfying solution for now...

Some information here

Run with Visual Studio

1. You need Visual Studio with Resharper installed
2. Run jam ManagedProjectFiles from the command line.
3. Open the generated Projects/CSharp/Unity.CSharpProjects.gen.sln solution.
4. Open a test .cs file.
5. Resharper will display a bubble next to each test, click it to run.

Manual method:

1. Run the test from utr. Found the artifacts path:

2. This folder should contain Artifacts explaining where the generated projects have been put on disk:

3. Open the RawLog and look for the command line arguments passed to Unity:

4. Go to the generated folder and open it with Unity:

• #dots-monorepo -> Where everything happens and where the current version of Unity is specified.

• Dots repo

public class QueryEngineTestCase
{
   public string query;

   public QueryEngineTestCase(string query)
   {
       this.query = query;
   }

   public override string ToString()
   {
       return query;
   }
}

public class QueryEngineTests
{
    public static IEnumerable<QueryEngineTestCase> GetQueryEngineTestCase()
    {
        yield return new QueryEngineTestCase("c=Boid") {};
    }

    [Test]
    public void ConvertToHierarchySearch([ValueSource(nameof(GetQueryEngineTestCase))] QueryEngineTestCase test)
    {

    }
}

• For trunk itself, documentation is done in the *.xml files. To generate documentation, use the project:

  • unity -projectpath Tools/DocTools/UnityDocBrowser/

  You must open the prject twice after a build. Open the menu Window->Internal->Doc Browser

• To validate the documentation, go into Tools/DocTools, then run

  • perl ./verify.pl

• To generate the documentation, go into Tools/DocTools, then run

  • perl ./run.pl

• To generate the documentation for one file, go into Tools/DocTools, then run

  • perl ./run.pl --onefile Search.QueryEngine_1

  This is essentially generating the html for the documentation in the namespace "Search" for the class "QueryEngine". It is the name of the member in the xml file.

• To run the tests of the APIDocGenerator:

  • Add this line where you want to break: System.Diagnostics.Debugger.Launch();
  • ./jam DocGen
  • ./jam DocGenTests
  • perl utr.pl --suite=docmodel

• Install the Package Doc Manager: https://github.cds.internal.unity3d.com/unity/com.unity.package-manager-doctools
  • Installing using URL in the package manager didn't work. I had to download the package and link to it.
• More info on package documentation.
• Open Package manager, select the package in your project you want to validate. See that there is a new Validate button
• Press Validate and View Results.

Registry: Computer\HKEY_CURRENT_USER\SOFTWARE\Unity Technologies\Unity Editor 5.x

e:\UnitySrc\gunity1\Editor
e:\UnitySrc\gunity1\Runtime
e:\UnitySrc\gunity1\Modules
e:\UnitySrc\gunity1\Tests
e:\UnitySrc\gunity1\Projects\Jam

• Flush the caches: C:\Users\sebastien.phaneuf\AppData\Local\JetBrains\Transient\ReSharperPlatformVs15\v191_278f5cf5\SolutionCaches

perl utr.pl --suite=editor --testproject=Modules/QuickSearch/Tests/QuickSearch/ --enable-code-coverage --coverage-results-path="cov-path" --coverage-options="generateAdditionalMetrics;generateHtmlReport;assemblyFilters:+UnityEditor.QuickSearchModule"

The Unity downloader cli allows you to make a build of a branch on katana and download the build.

• unity-downloader-cli -u editor/tech/search-window-uitk -c editor

If using git, you might have to add the existing ssh key to git

• ssh -i /path/to/key

• My PRs in Unity/unity.
• My Pr in Dots.

Validating PR state:

• Evergreen. Look at the bottom of the page:

• Evergreen on trunk

• 21.3 : guess work. --testproject=Modules/QuickSearch/Tests/QuickSearch (Test EditorTests - WindowsEditor - Part 4 of 4, remainder)
• 22.3 : guess work. --testproject=Modules/QuickSearch/Tests/QuickSearch (Test EditorTests - WindowsEditor - Part 4 of 4, remainder)
• 23.2 (see Tests/Sharding)
  • --testproject=Modules/QuickSearch/Tests/AttributeValidation (Test EditorTests - WindowsEditor - Part 7 of 10)
  • --testproject=Modules/QuickSearch/Tests/QuickSearch (Test EditorTests - WindowsEditor - Part 4 of 10)
  • --testproject=Modules/QuickSearch/Tests/SearchExamples (Test EditorTests - WindowsEditor - Part 6 of 10)
• 23.2 Mac 11.5 (see Tests/Sharding)
  • --testproject=Modules/QuickSearch/Tests/AttributeValidation (Test EditorTests - MacEditor (macOS 11.5) - Part 4 of 10)
  • --testproject=Modules/QuickSearch/Tests/QuickSearch (Test EditorTests - MacEditor (macOS 11.5) - Part 9 of 10)
  • --testproject=Modules/QuickSearch/Tests/SearchExamples (Test EditorTests - MacEditor (macOS 11.5) - Part 5 of 10)
• 23.3 Windows (see Tests/Sharding)
  • --testproject=Modules/QuickSearch/Tests/AttributeValidation (Test EditorTests - WindowsEditor - Part 6 of 10)
  • --testproject=Modules/QuickSearch/Tests/QuickSearch (Test EditorTests - WindowsEditor - Part 9 of 10)
  • --testproject=Modules/QuickSearch/Tests/SearchExamples (Test EditorTests - WindowsEditor - Part 4 of 10)
• 23.3 Mac 11.5 (see Tests/Sharding)
  • --testproject=Modules/QuickSearch/Tests/AttributeValidation (Test EditorTests - MacEditor (macOS 11.5) - Part 3 of 10)
  • --testproject=Modules/QuickSearch/Tests/QuickSearch (Test EditorTests - MacEditor (macOS 11.5) - Part 1 of 10)
  • --testproject=Modules/QuickSearch/Tests/SearchExamples (Test EditorTests - MacEditor (macOS 11.5) - Part 2 of 10)
• Neutron: we need to run the UXEngineering builder. See AreaGroup Builders for more information.

For Trunk, The QuickSearch Project uses these builder for all platforms:

• Test EditorTests - WindowsEditor - x64 - Part 9 of 10
• Test EditorTests - WindowsEditor - Arm64 - Part 9 of 10
• Test EditorTests - LinuxEditor - x64 - Part 8 of 10
• Test EditorTests - MacEditor - Arm64 - (VM) - Part 1 of 10
• Test EditorTests - MacEditor - x64 - Part 1 of 10

For trunk The SceneTemplate project uses these builder for all platform: Tests/EditModeAndPlayModeTests/SceneTemplate:

• Test EditorTests - WindowsEditor - x64 - Part 9 of 10
• Test EditorTests - WindowsEditor - x64 - (DebugAllocator) - Part 9 of 10
• Test EditorTests - WindowsEditor - x64 - (Coverage) - Part 9 of 10
• Test EditorTests - WindowsEditor - Arm64 - Part 9 of 10
• Test EditorTests - MacEditor - x64 - (Debug) - Part 7 of 10
• Test EditorTests - MacEditor - x64 - (DebugAllocator) - Part 7 of 10
• Test EditorTests - MacEditor - Arm64 - (VM) - Part 7 of 10
• Test EditorTests - MacEditor - x64 - Part 7 of 10
• Test EditorTests - MacEditor - x64 - (Device) - Part 7 of 10

For trunk The Settings project uses these builder for all platform: Tests/EditModeAndPlayModeTests/Settings:

• Test EditorTests - WindowsEditor - x64 - Part 2 of 10
• Test EditorTests - WindowsEditor - x64 - (DebugAllocator) - Part 2 of 10
• Test EditorTests - WindowsEditor - x64 - (Coverage) - Part 2 of 10
• Test EditorTests - WindowsEditor - Arm64 - Part 2 of 10
• Test EditorTests - MacEditor - x64 - (Debug) - Part 3 of 10
• Test EditorTests - MacEditor - x64 - (DebugAllocator) - Part 3 of 10
• Test EditorTests - MacEditor - Arm64 - (VM) - Part 3 of 10
• Test EditorTests - MacEditor - x64 - Part 3 of 10
• Test EditorTests - MacEditor - x64 - (Device) - Part 3 of 10

The file <Neutron>\Tests\EditModeAndPlayModeTestsProjectListToAreaMap.md stores a mapping between Test project and which Area builder will run it:

| Tests/EditModeAndPlayModeTests/Hierarchy | UX Engineering |

Then you need to find the proper builder on Yamato:

For Hierarchy you can use the following builder configuration:

• Unity7 Win 10 ([QV] Test EditorTests - WindowsEditor (CoreCLR - Win10) [UX Engineering])
  • --testproject=Tests/EditModeAndPlayModeTests/Hierarchy

• Yamato for Katana Users
• Rerun: run the job as is, at the commit it was initially run.
• If you want to know which builder runs which project check here

QuickSearch builder is in Test EditorTests - WindowsEditor - Part 4 of 10

• Queue job: run a specific job with all the new commits that have been pushed.

• To run a job with specific utr command line arguments. Click the Edit Variables in the Queue job dialog and add arguments to Bisection:

• To find the TestRunnerLog.json. Go to `Artifacts -> build-ReportedArtifacts@build/build/ReportedArtifacts

• Quicksearch on yamato
• QuickSearch on github
• How to release package
• More info on package promotion

Steps to get the package ready for Package Manager:

1. Publish
2. Promote

• Office Space: Select a date and book in your neighborhood (red one):