Remote Building (from Windows)

If you work in Water of Visual Studio on Windows, some build phases will run remotely over the network, on a Mac.

You need a Mac with Secure Shell (SSH) enabled, and Xcode installed, and connect to it via CrossBox Elements built-in infrastructure for remote debugging.

Please refer to these topics below for more detailed instructions on how to set the Mac up:

When you open a Cocoa project on Windows in Water or Visual Studio, the CrossBox server/device selector in the toolbart will show "(Unsuppoerted)" after the name of your local machine, because Cocoa apps cannot build* and run on WIndows.

Before working in the project, you need to either create a new connection to your Mac, or select an existing one you created before, via said device picker. Refer to the following topics for more detail:

Once a connection is made, you are ready to build, debug and deploy using your Mac for build tasks that cannot be done on Windows, and to test and run your projects of course.

macOS projects will run directly on the Mac selected via the CrossBox device picker; iOS, tvOS and watchOS projects can be run on Simulators on the same Mac, or on physical devices connected to the Mac via USB or WiFi.

Provisioning Profiles & Code Signing Certificates

To run build iOS, tvOS and watchOS applications to be run on-device (whether for local debugging or Deployment you will need a matching Provisioning Profile and Code Signing Certificate that you can obtauin from Apple's developer portal here.

Provisioning Profiles can be dowloaded on the Mac and either double-clicked to have Xcode install them, or manually places in the ~//Library/MobileDevice/Provisioning Profiles folder.

Certificates can be requested and downloaded to the Mac and double-clicked to be installed in the macOS Keychain.

In Project Settings you can select both the certificate (for all Cocoa projects) and profile (where applicable) to use for your project. Commonly, you will se different set of profile and certificate for Deployment or Debugging, in the "Release" and "Debug" configurations.

Water and Visual Studio will automatically obtain the list of available options fro the Mac, but the settings drop-down also provides an option to manually refresh the list, for example if you just recently added a new profile or certificate.

Keychain Access

By default, the build will look for the selected certificate (by name or fingerprint) in the default Keychain of the macOS user that you are connected as in your SSH connection.

If you share a build Mac with multiple users, it might make sense to put your certificates ito a separate keychain, which you can create with the Keychain Access tool that ships with macOS.

If you do so, you will need to provide the name of the keychain to use, in the KeychainName project setting. You can obtain the list of valid names by running the security list-keychains command in terminal on your Mac, and you will want to provide the full name as emitted by this command, for the KeychainName setting, e.g.


("login" is the default keychain that will be used if no name is provided).

You might also need to provide the password for the keychain, via the keychainPassword setting. The password for the default (login) keychain is usually the same as the password for the user; for custom keychains, you can pick a password upon creation.

What Projects or Build Tasks Require a Mac?

Generally, most real life Cocoa projects will require a Mac for one or more build tasks, but there are a few exceptions.

The following build tasks require connection to a Mac:

  • Processing resources such as Storyboards, XIBs, Asset Catalogs or other more rare file formats that require a mac-native tool for conversion.
  • Code-signing the final executable or app bundle.
  • Linking the final executable, for Toffee (V1) projects.

Trying to build a project that requires a Mac connection with the CrossBox server set tom "Local", will fail on Windows.

The following project types can be compiled locally, provided Code Signing is not needed:

  • Static Librares (as they don't require linkling).
  • Dynamic Libraries or plain "command line" executables, when using the Toffee V2 or Island back-end.

See Also