Go Import

One of the main use cases of the Go language with Elements is to use functionality from one of the countless existing Go libraries in your own project. Of course, it is always possible to just add the .go source files to your project directly, but for using complete libraries there's an easier way: Go Imports.

The EBuild command line tool offers a special option to import a Go library project, along with all its dependencies, from a git repository, create one or more.elements projects from it for you, and build it — so that all that is left for you to do is add a Project Reference to the project where you need it.

This mode of EBuild is run by specifying the --import-go-project command line switch, alongside the URL of the G o project (same as you would pass it to "go get") and a set of additional parameters. e.g.:

ebuild --import-go-project https://github.com/nakagami/firebirdsql

Since pretty much all Go libraries depend on a fully covered Go Base Library, Go Import is only supported for .NET and Island-based projects.

The mode for the generated project(s) can be determined via the --mode switch, and defaults to Echoes (.NET), if not specified.

For Island imports, a --submode and optional --sdk can be specified, as well, by default the import will happen for the platform of the current system (i.e. Windows on a Windows PC, Darwin (Cocoa) on a Mac, etc.

For .NET imports, an optional --target-framework can be provided, e.g. to import for .NET Core or .NET Standard. The default is ".NETFramework4.5".

How the Import Works

The import will determine the base URL of the repository specified by the URL. Supported are GitHub repositories, gopkg.in URLs, as well as any valid Git URL or any URL that supports the ?go-get=1 parameter.

It will clone that URL into a folder underneath the output folder and generate a .elments project containing all .go files within the specified subdirectory.

It will then check the import sections of all these .go files for additional external dependencies, and repeat the same steps, recursively if necessary, until all dependencies are covered.

A separate .elements project will be generated for each repository; if import dependencies request subdirectories of the same repository, the project for that repository will be extended to include the additional files.

If the --build switch is provided, the root project and all its dependencies will be build using a regular EBuild build run, as the final step.

Note that some Go projects have many dependencies, sometimes in the hundreds or even thousands of different folders. The import may take a while, and depending on the amount of projects generated, the generated .sln file might not be well-suited to be opened by the IDEs.

We recommend building it from the command line (either as part of the import by specifying --build, or by calling ebuild with the solution file at a later point) first, and then simply adding the main .elements project as Project Reference to your real projects.

Switches

Supported switches are:

  • --mode:<Island|Echoes> — the target Mode for the new project.
  • --submode:<Windows|Linux|Darwin|Android> — the submode, for Island imports.
  • --sdk:<sdk> — the SDK, for Island imports.
  • --target-framework:<framework> — the Target Framework, for .NET imports.
  • --output-folder:<folder> — the output folder.
  • --build — causes the generated project(s) to be actually build, as final step.
  • --debug — emits more detailed diagnostics and debug info.

Also any specified --settings: will be ignored by the import, but passed on to project for the build.

See Also

  • Go
  • Target Frameworks on .NET