IDE Communicator

Although Xojo itself cannot be run as a command line app, it can be controlled using a separate command-line app that communicates with Xojo using IPC sockets and the "XojoIDE" path.

There are two versions of the communication protocol. The original v1 protocol lets you send IDE Scripts directly to Xojo, but you do not get any reponse back from Xojo.

The newer v2 protocol lets you send IDE Scripts directly to Xojo (embedded in JSON) and returns responses (from the Print command) and script errors to you.

Version 1

The IDECommunicator example project (Examples/Topics/Build Automation/IDE Scripting/IDECommunicator/v1) contains a console project that can be used communicate with Xojo from the command line by sending IDE Scripts to Xojo for it to run.

Xojo must already be running in order for the communication to work. To use it, build the app for your platform and then run it from the command line with the “-h” option to see how it works. This command runs it on Mac and Linux (# indicates your shell/terminal prompt):

# ./IDECommunicator -h

Most often you will send it an IDE Script file. This runs the provided test script:

# ./IDECommunicator testscript.xojo_script

Version 2

Starting with Xojo 2016 Release 4, a new protocol can be used for communication. The new protocol allows two-way communication and the capture of load and compile errors (instead of showing dialogs).

Xojo includes two IDE Communicator projects that can help you use this new protocol, located here: Example Projects/Advanced/IDE Scripting/IDECommunicator/v2.

IDECommunicator-Tester: A desktop project that lets you send IDE Scripts to Xojo.
IDECommunicator: A console project that lets you send IDE Scripts to Xojo.

Xojo must be be running in order for the communication to work. To use the console project, built it for your OS and then run it from the command line to see how it works. This command runs it on Mac and Linux (# indicates your shell/terminal prompt):

# ./IDECommunicator

Most often you will send it an IDE Script file. This runs the provided test script:

# ./IDECommunicator testscript.xojo_script

Protocol information

The new Communicator protocol uses JSON strings termined with NULL characters (NUL) for communication. To turn on the new protocol, you need to upgrade to version 2 by sending the following command:

"{""protocol"":2}" + Chr(0)

Once in this mode, you can send scripts and receive responses as JSON with these values:

"script": The script you want to send.
"tag": Unique text used to identify responses.

For example, sending this JSON will attempt to build the app:

{"script":"Print BuildApp(7,False)", "tag":"build"}

Don't forget that you need to add a NULL character terminator (NUL or Chr(0)) to the JSON you send.

If the build was successful you will receive a response like this:

{"tag":"build", "response":"<path to built app>"}

In this case, "response" is the value of the last value normally sent by the "Print" method.

If a build error occurs, "response" will be an object containing errors, like this:

{
  "tag":"build",
  "response":{
    "buildError":{
      "errors":[
        {
          "type":"Code",
          "message":"Can't find a type with this name",
          "source":"dat",
          "location":"Module1.Run",
          "position":"Module1.Run, line 2"
        }
      ]
    }
  }
}

This response is a compile error indicating that there was a bad type "dat" on Module1.Run, Line 2.

Script errors

This is an example of the response to an error in a supplied script:

{
  "tag":"build",
  "response":{
    "scriptError":[
      {
        "type":"compiler",
        "line":0,
        "number":11,
        "message":"Error found while compiling"
      }
    ]
  }
}

Load errors

This is an example of an error caused by a missing picture in an image on load:

{
  "tag":"build",
  "response":{
    "openErrors":[
      {
        "projectError":[
          {
            "name":"image",
            "type":"Unable to locate original image",
            "data":"The original image cannot be located",
            "isFatal":false
          }
        ]
      }
    ]
  }
}

This error response indicates a missing Picture object:

{
  "tag":"build",
  "response":{
    "openErrors":[
      {
        "projectError":[
          {
            "name":"Artboard",
            "type":"Missing File 'Artboard.png'",
            "data":"Macintosh HD:Users:username:Desktop:Artboard.png",
            "isFatal":false
          }
        ]
      }
    ]
  }
}

You will also get an openError if the IDE version is lower than the project version:

{
  "tag":"build",
  "response":{
    "openErrors":[
      {
        "projectError":{}
      },
      {
        "error":{
          "type":"IDE Version Conflict",
          "projectVersion":"2016.040",
          "ideVersion":"2016.030"
        }
      },
      {
        "projectError":{}
      }
    ]
  }
}

Environment variables

Communicating With Multiple Xojo IDEs Independently

The Xojo IDE listens on an IPCSocket with a path of /tmp/XojoIDE. In order to communicate with more than one running at a time, you need to use a unique path for each running IDE. This can be accomplished by setting the environment variable XOJO_IPCPATH to a filename. The only valid characters for the filename are a-z, A-Z, 0-9 and _.

env XOJO_IPCPATH=Xojo2019r2 /Applications/Xojo 2019 Release 2/Xojo.app/Contents/MacOS/Xojo &

Prevent Dialogs from Appearing When IDE Starts

When Xojo is launched with the environment variable XOJO_AUTOMATION set to TRUE it will skip the Feedback Crash dialog and the Restore Previous Project dialog so the build automation process doesn't get paused. (Added in 2018r3.)