Connecting from EBuild on the Command Line

Connecting to your CrossBox server is easy, and only needs to be done once, after which the server will automatically be available for all your projects.

The EBuild command line tool provides an option to do this from the command line, for cases where you do not have access to an IDE, for example on build servers, or when developing with the command line compiler on Linux.

This can be done by invoking the ebuild command with the --register-crossbox-server parameter, which then introduces a few new command line parameters that can be used to specify details about the server to register.

--host:<hostname or ip address>
--port:<port>
--name:<name>
--user:<name>
--password:<password>
--keyfile:<name>
--keyfilepassword:<password>
--agent:<true/false>
--local-shared-root:<local path>
--remote-shared-root:<remote path>
  • The --host parameter is always required to specify the host name or IP address of the remote server. This can can be an IPv4 or IPv6 address, or a DNS name.

All other parameters are optional, and can be omitted:

  • The --port parmeter can specify a custom port for the SSH connection. The default is port 22.
  • The --name parameter can be used ot override the user-visible name that the server will be registered under. By default, the host address will be used.
  • The --user parameter specifies the name of the remote user. If not specified, the name of the current local user will be used.

Either a password or a key file (recommended) are required for authorization. If a default private key file is present in the local SSH installation (and has its public key registered on the server), both parameters can be omitted and the default key file will be used.

Optionally, a key file password can be provided, or the --agent option can be set to true to use the local SSH agent system for login, instead.

We recommend to familiarize yourself with how SSH works in general, via the link(s) provided below.

Shared Roots

You can also optionally specify a so-called "shared root folder" for your CrossBox server, if you have a folder from the server mapped as a local drive, or vice versa. This is helpful especially for Cocoa (where some build phases use the Mac, and can cause a lot of files to be transferred over SSH), but provides an extra speed boost for Island debugging, as well.

Essentially, you will provide two paths that point to the same folder, one local to your PC or VM and one that's valid on the CrossBox server.

Whenever you work with projects located within the shared root, CrossBox will forego manually transferring files back and forth via SSH. Instead, it will just build the project locally, and use the shared root to map the file paths whenever it needs to execute things remotely – both for building and for debugging.

For example, say you work in a Windows VM on a Mac. All your projects are located on your Mac, in /Users/paul/Code, and you have that folder mapped into your VM as drive Z:\. You can pass the --local-shared-root and --remote-shared-root parameters, and whenever you work in a project from drive Z:, CrossBox will use the shared root. (If you open a project located elsewhere, say in C:\, CrossBox will fall back to transferring files via SSH as needed.)

Note: EBuild will verify that the local shared root folder exists, and that it maps to the remote root, on registration (and on subsequent use, as well), by creating a small temporary file. If the check fails, the server will be registered without the shared root option.

See Also