Remote Project References
Remote Project References are similar to regular Project References, but instead of referencing another project on the local system, they refer to a project hosted online in a Git repository. As part of the build, EBuild will automatically download (clone) or update the repository to the local disk as needed, and then include the local project as regular reference.
Remote Project References are a great way to maintain dependencies to projects that are maintained by third parties, or libraries shared between teams or solutions within your own company.
A Remote project Reference is specified using the
The name of the package is the complete URL to a .elements project file in a remote git repository, currently limited to GitHub. The version can be "*", or a valid branch name, tag name or commit ID for the repository. "*" or lack of version will refer to the master branch of the repository.
Note that the proper GitHub URL for a file consists of 'github.com domain name, followed by the username and repository name, and then the path to the relevant file (in this case, an .elements project file). This is not the same URL as is shown when browsing the GitHub repository in the browser. The http:// or https:// prefix is optional, and EBuild will always use HTTPS to access GitHub.
For example, the reference below refers to RemObjects InternetPack open source library.
<RemoteProjectReference Include=“github.com/remobjects/internetpack/Source/RemObjects.InternetPack.elements:master”/>
How EBuild Resolves Remote Project References
EBuild resolves Remote Project References as part of the same pre-build phase that also verifies regular (local) Project References and determines the best build order for all projects involved.
For each Remote Project References encountered, EBuild will determine a standardized local folder to create a local clone in. If a copy of the repository already exists, EBuild will update (i.e. fetch and pull) that repository to be up to date with the remote; if not, it will download (i.e. clone) the repository to that folder.
Remote Project References can specify an optional branch name; if present, EBuild will select that branch, otherwise it will use the master branch of the repository.
EBuild will then load in the local copy of the referenced project, and ensure it will be built as if it had been part of the solution to begin with. EBuild will of course also process any Project References or Remote Project References contained within that project, so that recursive dependencies are handled correctly. The final build order for all involved projects will be determined once all Remote Project References have been pulled and resolved.
If a Remote Project Reference cannot be pulled/cloned, or if the specified project file cannot be found within the repository, the build will fail.
As each project hits the ElementsResolveReferences task, project references are resolved, as described in Project References: How EBuild resolves Project References.
LFS support
Remote Project References can be used with Git repositores that leverage Git Large File Storage (LFS). Git support for LFS must be installed manually from git-lfs.github.com, system wide. After that, Remote Project References can be marked with the <LFS>True</LFS> metadata tag, and EBuild will automatically issue the right commands to initialize and pull LFS data, as needed.