Dartino command line application

The dartino command-line application

Audience

This document is intended for developers of Dartino, not developers that use Dartino.

Introduction

The primary way to interact with the Dartino VM is via the dartino command. This command communicates with a persistent process that does all the heavy lifting.

The dartino command (via the persistent process) takes care of things like:

• Compiling a program

• Running and debugging programs on a Dartino VM

Architecture overview

As mentioned above, the dartino command communicates with a persistent process.

The dartino command is a C++ program (src/tools/driver/main.cc). It's meant to be a simple as possible and simply forward stdio and signals to the persistent process via a socket.

The persistent process is a Dart program (driver_main.dart).

The persistent process comprises a main isolate and several worker isolates.

The main isolate listens for incoming connections from the dartino command, and may use a worker isolate to complete the requested task.

The command-line API revolves around a concept of verbs, such as help, create, compile, show, debug, etc. The list of verbs can be found in actions.dart, or with this command line:

$ *dartino help all*
Manages interactions with the dartino compiler and runtime.
Example: dartino run sample.dart

Usage: dartino <action> [<argument>]...
 where <action> is one of the following:

   attach tcp_socket [<host>:]<port>
             Attach to Dartino VM on the given socket

   compile <file> [in session <name>]
             Compile <file>

   create session <name> [with <settings file>]

...

Sessions

The dartino command (really, the persistent processs) supports multiple sessions. Each session can be attached to a separate Dartino VM, which would enable a user to test multiple devices simultaneously. It's also important for taking advantage of multiple cores during testing. Currently, session management is explict, but we plan to make it implicit.

Here's an example of a complete session:

First we need a session

$ ./out/DebugIA32Clang/dartino create session my_session
Created session 'my_session'.

Then we need to start the Dartino VM:

$ ./out/DebugIA32Clang/dartino-vm
Waiting for compiler on 127.0.0.1:61745

Copy the socket address (127.0.0.1:61745 in the above example) and open a new terminal window:

$ ./out/DebugIA32Clang/dartino attach tcp_socket 127.0.0.1:61745 in session my_session
Connected to Dartino VM on TCP socket 61757 -> 61745

We have now attached the Dartino VM to the session we just created.

We can now compile a program and run it on the Dartino VM:

$ ./out/DebugIA32Clang/dartino compile file hello.dart in session my_session
Compiled 'hello.dart' to 3572 commands
$ ./out/DebugIA32Clang/dartino x-run in session my_session

For now, the Dartino VM's output will appear in the window where you started it.

Finally, end the session:

$ ./out/DebugIA32Clang/dartino x-end session my_session
Ended session 'my_session'.

Debugging the persistent process

To debug the persistent process, we need to start it manually. Normally it's started automatically by the dartino command. The easiest way to find the proper list of command-line arguments is by looking at the running process. We have built a tool to make this easier:

$ ./out/DebugIA32Clang/dartino
   debug [command]
             Perform a debug command, or if none are specified start an
             interactive debug session

   help      Display this information.
             Use 'dartino help all' for a list of all actions

   show      List things or show information about a thing
$ ./tools/persistent_process_info.sh -k
Persistent Dartino process 32541:
./out/DebugIA32Clang/dart -c --packages=pkg/dartino_compiler/.packages package:dartino_compiler/src/hub/hub_main.dart ./.dartino

Now start the persistent process in a separate terminal window:

$ ./out/DebugIA32Clang/dart -c -Ddartino.version=0.3.0 --packages=pkg/dartino_compiler/.packages package:dartino_compiler/src/hub/hub_main.dart ./.dartino
/var/folders/00/0q250000h01000cxqpysvccm002w8m/T/dartino_drivers9Sxjh/socket

It prints one line which is the socket it is listening to. Don't worry about that, it also saved it in ./.dartino so the next dartino command will know where to find it.

Debug by printing

Most of the code in the persistent process run inside a zone that sends output back to the C++ client (the dartino command). So if you want to print something to the terminal window of the persistent process, the best way is to ensure Zone is imported:

import "dart:async" show
    Zone;

And print through the root zone:

Zone.ROOT.print("FISK");

Testing

If you have launched the persistent process as described above, you should remember to disable automatic killing of it when running test.py: process):

$ ./tools/test.py -j1 -rdartino_compiler --kill-persistent-process=0

In the above example, we've also limited testing to the dartino_compiler runtime (the -r option selects runtimes), and no parallel tasks (the -j option specifies the number of tasks that can run in parallel). Whether or not -j1 and -rdartino_compiler are the right options depends on the situation.