Short:        Remote command launcher Amiga/PC
Author:       Andreas Fredriksson <deplinenoise (at) gmail (dot) com>
Uploader:     deplinenoise@gmail.com
Type:         dev/cross
Architecture: m68k-amigaos
Version:      1.0

ABOUT
===============================================================================

The rlaunch utility allows the user to develop programs using cross-compilers
on a PC platform and then test the resulting binaries immediately on an Amiga
computer without copying files. Output from the program is channeled back to
the controlling PC as if it was run locally.

BUILDING
===============================================================================

Host tools (rl-controller and a host rl-target):

    cmake -B build -DCMAKE_BUILD_TYPE=Release
    cmake --build build

Amiga target (needs docker; vbcc is taken from the terriblefire78/vbcc image,
which is pulled and patched up on the first configure):

    cmake -B build-amiga -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=cmake/amiga-vbcc.cmake
    cmake --build build-amiga

TESTS
===============================================================================

The host build produces rl-test, covering the file server, the wire protocol
codecs and the string/format utilities:

    ctest --test-dir build --output-on-failure

Tests assert correct behaviour, so those covering a still-open bug begin with
UTEST_SKIP("#N: ...") to keep the build green. Removing that one line is how
you check a fix: the test should go from skipped to passing.

The same ctest run also drives the rl-controller binary as a subprocess for the
things that are not reachable from rl-test (test/controller-connect-test.sh).
Those tests are POSIX-shell only and are skipped on Windows.

amigafs.c is Amiga-only source, but it compiles unmodified for a 32-bit host
against the real NDK headers in the vbcc image, so it can be unit tested by
feeding it DosPackets directly:

    test/amigafs-host-test.sh

Only a dozen AmigaOS entry points are faked (test/amiga_stubs.c); the code
under test is the code that ships.

There is also an end-to-end test that boots AROS m68k under the Amiberry
emulator, runs a real rl-target on it and drives it with the host controller:

    test/amiga-e2e.sh build build-amiga

It needs an amd64 Linux host with docker (for the amiga build) and sudo (to
install Amiberry). No Kickstart ROM and no Workbench install are involved: the
Amiberry package ships AROS ROMs, and bsdsocket.library is emulated, so the
target's TCP port appears as an ordinary listening socket on the host. CI runs
this job non-blocking until it has proven stable.

The two are complementary: the host tests pin down individual packet handling,
the emulator proves the whole thing actually works on a real 68k.

INSTALLATION
===============================================================================

Just copy the binaries to any directory you like on their respective platform.

HOW IT WORKS
===============================================================================

There are two parts to rlaunch, the controller and the target. The target
binary runs as a daemon on the Amiga and sets up a TCP/IP port (7001 by
default) listening for incoming connections. The controller runs on some other
machine (UNIX or Win32) and is started on demand by the user when a program is
to be launched on the Amiga.

When the controller is started, it is given at least two options, the path to
the file tree to present to the Amiga, and the path to an Amiga executable to
be started. The controller initiates a connection to the target and instructs
it to launch said executable.

The target process knows how to set up a virtual file system on the Amiga for
each controller connection which is also used to load the designated
executable. These devices (named TBL0, TBL1 and so on) are maintained
automatically by the target process for the lifetime of controller connection.
Requests against these virtual file system devices will map back over the same
TCP/IP connection and operate on the controller's file system.

For example; if a controller is started on Win32 with the file serving path
C:\Foo and the executable Bar, the following events will take place:

1. A connection is made to the specified target

2. A "launch executable" request is transmitted from controller to target

3. The target creates a new virtual file system TBLx:, mapping it to this
controller

4. The target spawns the process "TBLx:Bar"

5. When the connection is broken or the target program is interrupted, the
device is torn down.

BUGS AND LIMITATIONS
===============================================================================

- All paths on the Amiga side are limited to 108 characters. They will be
  silently truncated.

- The remote file system is read only.

CONTROLLER SYNPOSIS
===============================================================================

 rl-controller [-fsroot <r>] [-port <#>] [-log <..>] <host> <exe_path> [args]

Arguments:
  <host>         Hostname to connect to (mandatory, names are ok)

  <exe_path>     Path to executable relative to fsroot, with forward
                 slashes. Absolute Amiga paths can also be used to run
                 remote programs, e.g. c:info (mandatory)

  [args]         Optional arguments to pass to Amiga executable

Options:
  -fsroot        Specifies the file serving directory. The executable
                 must live in this directory as well. (default: cwd)

  -port          The TCP port to connect to (default: 7001)

  -log           Specifies log levels (default: 'c')
                 0: disable everything    a: everything
                 d: debug channel         i: info channel
                 w: warning channel       p: network packet channel
                 c: console channel

DAEMON SYNOPSIS
===============================================================================

  rl-target.exe ADDRESS,PORT/N,LOG

  ADDRESS          IP address to bind, defaults to 0.0.0.0
  PORT/N           TCP port to bind, defaults to 7001
  LOG              Specifes log levels, see above.

LICENSE
===============================================================================

This program is free to use for non-commercial purposes.
Copyright (c)2009 Andreas Fredriksson, TBL Technologies. All rights reserved.