From 919a351446df1c4039daf7bdc6adaa53edcd5030 Mon Sep 17 00:00:00 2001 From: Colin Ward Date: Fri, 19 May 2023 07:47:49 +0900 Subject: [PATCH] Improve documentation RADRunner was "discovered" by amiga-news.de and some people had trouble compiling and using it. The README.md file has now been updated to add documentation about missing arguments, advanced usage instructions and compilation instructions. --- Examples/BuildAndGet.rad | 3 + Examples/SendAndExecute.rad | 3 + Examples/c_cpp_properties.json | 58 +++++++ Examples/make | 1 + Examples/settings.json | 20 +++ README.md | 305 +++++++++++++++++++++++++++++++-- 6 files changed, 373 insertions(+), 17 deletions(-) create mode 100644 Examples/BuildAndGet.rad create mode 100644 Examples/SendAndExecute.rad create mode 100644 Examples/c_cpp_properties.json create mode 100644 Examples/make create mode 100644 Examples/settings.json diff --git a/Examples/BuildAndGet.rad b/Examples/BuildAndGet.rad new file mode 100644 index 0000000..d99a17a --- /dev/null +++ b/Examples/BuildAndGet.rad @@ -0,0 +1,3 @@ +# Compile a project on the remote server and fetch the binary +execute make +get diff --git a/Examples/SendAndExecute.rad b/Examples/SendAndExecute.rad new file mode 100644 index 0000000..ef6235f --- /dev/null +++ b/Examples/SendAndExecute.rad @@ -0,0 +1,3 @@ +# Send an executable to the remote server and execute it +send Debug/RADRunner +execute RADRunner diff --git a/Examples/c_cpp_properties.json b/Examples/c_cpp_properties.json new file mode 100644 index 0000000..ef59a2f --- /dev/null +++ b/Examples/c_cpp_properties.json @@ -0,0 +1,58 @@ +{ + "configurations": [ + { + "name": "AmigaOS3", + "includePath": [ + "${workspaceFolder}/**", + "../StdFuncs", + "c:/amiga-gcc/lib/gcc/m68k-amigaos/6.5.0b/include/c++", + "c:/amiga-gcc/lib/gcc/m68k-amigaos/6.5.0b/include/c++/m68k-amigaos", + "c:/amiga-gcc/m68k-amigaos/clib2/include", + "c:/amiga-gcc/m68k-amigaos/ndk-include", + "c:/amiga-gcc/m68k-amigaos/sys-include" + ], + "defines": [ + "__amigaos__", + "_DEBUG", + "MUNGWALL_NO_LINE_TRACKING" + ], + "compilerPath": "c:/amiga-gcc/bin/m68k-amigaos-g++.exe", + "cStandard": "c11", + "cppStandard": "c++14", + "intelliSenseMode": "gcc-x64", + "configurationProvider": "ms-vscode.makefile-tools" + }, + { + "name": "Win32", + "includePath": [ + "${workspaceFolder}/**", + "${workspaceFolder}/../StdFuncs", + "c:/Program Files (x86)/Windows Kits/10/Include/10.0.18362.0/um" + ], + "defines": [ + "_DEBUG" + ], + "cStandard": "c11", + "cppStandard": "c++14", + "intelliSenseMode": "msvc-x64", + "configurationProvider": "ms-vscode.cmake-tools" + }, + { + "name": "Win32 GCC", + "includePath": [ + "${workspaceFolder}/**", + "${workspaceFolder}/../StdFuncs" + ], + "defines": [ + "__unix__", + "_DEBUG" + ], + "compilerPath": "d:/Coding/MingW/bin/g++.exe", + "cStandard": "c11", + "cppStandard": "c++14", + "intelliSenseMode": "gcc-x64", + "configurationProvider": "ms-vscode.cmake-tools" + } + ], + "version": 4 +} diff --git a/Examples/make b/Examples/make new file mode 100644 index 0000000..ea1bda1 --- /dev/null +++ b/Examples/make @@ -0,0 +1 @@ +RADRunner script BuildAndGet.rad diff --git a/Examples/settings.json b/Examples/settings.json new file mode 100644 index 0000000..ed32c5b --- /dev/null +++ b/Examples/settings.json @@ -0,0 +1,20 @@ +{ + "makefile.configurations": [ + { + "name": "OS3 Debug", + "makeArgs": ["-j4", "DEBUG=1"], + "problemMatchers": ["$gcc", "$unknown"] + } + ], + "makefile.launchConfigurations": [ + { + "cwd": "d:\\Source\\RADRunner", + "binaryPath": "d:\\Utils\\Windows\\RADRunner.exe", + "binaryArgs": [ + "vampire", + "script", + "Examples\\SendAndExecute.rad" + ] + } + ] +} diff --git a/README.md b/README.md index f91fd6e..4e09b9e 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ like this: ```shell $ RADRunner ? -REMOTE,EXECUTE/K,GET/K,SCRIPT/K,SEND/K,SERVER/S,SHUTDOWN/S +DIR/K,EXECUTE/K,GET/K,PORT/K,SCRIPT/K,SEND/K,SERVER/S,SHUTDOWN/S,REMOTE ``` Arguments are not case sensitive but by convention on Amiga OS they are typed in upper case, at least in examples. But @@ -77,13 +77,13 @@ on port 80. In client mode, usage tends to follow the pattern: ```shell -$ RADRunner \ COMMAND +$ RADRunner \ COMMAND ``` -\ is either the name of the server or its IP address. COMMAND is one of the commands shown by the ? request. +\ is either the name of the server or its IP address. COMMAND is one of the commands shown by the ? request. A basic session at the command line, including commands typed and text output by RADRunner during development might be: -``` +```shell $ RADRunner vampire SEND Debug/MyL33tCode send: Sending file "Debug/MyL33tCode" send: Transferring file "Debug/MyL33tCode" @@ -94,7 +94,7 @@ execute: Executing file "MyL33tCode" On the server, the following would be ouput: -```script +```shell $ RADRunner.exe server Starting RADRunner server Listening for a client connection... connected @@ -144,7 +144,7 @@ shutdown To execute this script, from the command line or inside a makefile, the following command is used: -```script +```shell $ RADRunner vampire SCRIPT SendAndRun.rad ``` @@ -170,7 +170,7 @@ execute WinningEntry.exe $1 To use this script, one would type the following on the command line: -```script +```shell $ RADRunner vampire SCRIPT "SendAndRun.rad fullscreen" ``` @@ -188,6 +188,19 @@ at a time and scripts won't be necessary, or perhaps the script system will be e This is a list of the commands currently supported by RADRunner. +## DIR/K \ + +Lists the contents of the given directory on the remote server. For example: + +```shell +d:\Source> RADRunner vampire DIR RAM: +``` + +> Note: Using `DIR ""` will cause RADRunner to return the contents of the current remote directory (i.e. The directory +in which RADRunner is executing). However, the Amiga OS versions of RADRunner use a wrapper around the dos.library +argument parsing functions, which don't allow "" to be passed in. (they consider this to be a missing argument). This +can be worked around by using `DIR """"`. This applies to all commands that refer to the current directory. + ## EXECUTE/K \ Executes a file on the remote server. Both the EXECUTE keyword and the filename must be specified. If the filename @@ -197,14 +210,14 @@ be executed. Arguments can be passed to the command by including both the filename and the arguments inside quotes. -```script +```shell d:\Source> RADRunner vampire EXECUTE "MyL33tCode.exe highres" ``` When the command is executed on the remote server, its output will be captured and displayed by the client. Here is an example of using RADRunner to build itself remotely. -```script +```shell $ RADRunner fastpc EXECUTE "make DEBUG=1" execute: Executing file "make DEBUG=1" Compiling RADRunner.cpp... @@ -221,6 +234,28 @@ Downloads a file from the remote server. The same rules for path handling apply received, the file will be written into the current directory and its timestamp will be set to match the timestamp on the original file. Protection bits such as the script bit (on Amiga OS) are not currently preserved. +## PORT/K \ + +This command is meant to be used in conjunction with other commands, to direct RADRunner to use a different port to the +default, which is port 80. This is useful when that port is being used for something else or is blocked. + +For example, to start a server on port 68000 (every Amiga user's favourite number): + +```shell +$ RADRunner SERVER PORT 68000 +``` + +And to use that from a remote computer: + +```shell +d:\Source> RADRunner vampire PORT 68000 DIR RAM: +``` + +## SCRIPT/K \ + +Executes a number of commands inside the RADRunner script file specified by \. See the section "Script Support" +for further information. + ## SEND/K \ Uploads a file to the remote server. The filename can specify an absolute or relative path on the client computer, or @@ -230,7 +265,7 @@ itself is sent to the server, resulting in it being written to the server's curr The logic behind this is that the directory structure on the client (development) computer doesn't make sense on the server. For example if you are cross compiling using Windows then you might type: -```script +```shell d:\Source> RADRunner vampire SEND d:\Output\Debug\MyL33tCode.exe ``` @@ -244,23 +279,260 @@ command to execute a script that is already on the target computer, which can mo Like the GET command, the timestamp is preserved during the transfer, but protection bits are not. -## SCRIPT/K \ +## SERVER -Executes a number of commands inside the RADRunner script file specified by \. See the section "Script Support" -for further information. +Starts RADRunner in server mode, causing it to listen to incoming connections from other instances of RADRunner. ## SHUTDOWN Shuts down the remote instance of RADRunner, when it's 3 am and time to go to bed. -## SERVER +# More advanced uses -Starts RADRunner in server mode, causing it to listen to incoming connections from other instances of RADRunner. +You may have noticed that some examples use "$ RADRunner" and some use "d:\Source> RADRunner". This is to show that +RADRunner is truly a cross-platform utility and can be used on Amiga OS, Linux, Mac OS or Windows, with any of these +platforms acting as a server and any platform acting as a client. + +This allows some imaginative uses of RADRunner, to suit the way that _you_ want to work. Here are my (Colin Ward AKA +Hitman/Code HQ) two favourites. + +## Favourite 1: Remote integrated development from Visual Studio Code on a PC or Mac + +In this scenario, we wish to use Visual Studio Code and its wonderful code lookup features to edit and compile our code, +but we need to run it on either a real Amiga or an emulator. + +To begin with, you need to install the VS Code extension for building using make. Click the "Extensions" icon in the +Activity Bar and search for "Makefile Tools" by Microsoft. It's ironic that we are using an extension by Microsoft in +a Microsoft IDE to program our beloved Amigas! :-) To build using this extension, you need to create a settings.json +file in the .vscode folder. This instructs the extension how to build using make and how to launch the project once it +has been built. The settings.json file that is used for building RADRunner itself has been included in the _Examples_ +directory. Copy this file to the .vscode directory and open it to view in VS Studio. + +Note that the paths are configured for the author's computer (files such as settings.json in the .vscode directory are +not really meant to be shared), so you will have to tweak them for your system for the example to work. In particular, +the "cwd" (current working directory) and "binaryPath" properties need to be changed to suit your system, as shown +below: + +```json +"makefile.launchConfigurations": [ + { + "cwd": "d:\\Source\\RADRunner", + "binaryPath": "d:\\Utils\\Windows\\RADRunner.exe", + "binaryArgs": [ + "vampire", + "script", + "Examples\\SendAndExecute.rad" + ] + } +``` -# More advanced uses +You also need to configure the Makefile Tools extension to tell it which build and launch configuration to use. To do +this, click the extension's icon in the Activity Bar and in the window pane that appears, click the pencil item and +choose the following: + +``` +Configuration: OS3 Debug +Build target: all +Launch target: ..\..\Utils\Windows\RADRunner.exe... +``` + +The "Launch target" will be a long string that changes on different systems (the Makefile Tools extension is a little +bit quirky) - the important thing is that the path to your local RADRunner executable should be included in the name you +select. + +You may also need to configure the version of make to use, depending on your system. + +Of course, for this to work, it assumes that you have an Amiga cross compiler installed and in your path. At Code HQ, +we use [Bebbo's GCC](https://github.com/bebbo/amiga-gcc) for OS3 and [ADtools](https://github.com/sba1/adtools) for OS4. + +By default, the makefile will use any native version of GCC that it finds on the system, so in order to cross compile +for Amiga OS3 or OS4, you must export the _PREFIX_ environment variable. Choose one of the two exports, depending on +your desired target: + +```shell +export PREFIX=m68k-amigaos- # For OS3 +export PREFIX=ppc-amigaos- # For OS4 +``` + +Or for Windows: + +```shell +set PREFIX=m68k-amigaos- # For OS3 +set PREFIX=ppc-amigaos- # For OS4 +``` + +This needs to be accessible to VS Code, so it's usually best to set the variable from a shell and then launch VS Code +from that same shell, rather than launching VS Code through the Start Menu or similar. + +The _PREFIX_ environment variable will be picked up by the makefile and used to choose the correct compiler. If you are +interested in writing a makefile that can be used to compile for OS3, OS4 and native Linux and Mac OS, take a look at +RADRunner's makefile. + +Now for the interesting part: Remotely launching the binary you have just built! Take a look at the settings.json file +again. You can see that there is some magic in the "makefile.launchConfigurations" section. Normally, the "binaryPath" +key would be set to the name of the file that was just built by the makefile extension. In our case, this won't work, +as we have cross compiled for Amiga OS. So instead, we tell the extension to launch the native (Windows, Linux, Mac OS) +version of RADRunner, using this to send the Amiga OS binary to the Amiga and to execute it. For instance: + +```json +"makefile.launchConfigurations": [ + { + "cwd": "d:\\Source\\RADRunner", + "binaryPath": "d:\\Utils\\Windows\\RADRunner.exe", + "binaryArgs": [ + "vampire", + "script", + "Examples\\SendAndExecute.rad" + ] + } +``` + +You can see in the "binaryArgs" array that we pass in the arguments "vampire script Examples\\SendAndExecute.rad". +"vampire" is the name of the host Amiga that we want to communicate with. The author's Amiga is a Vampire 4 Standalone +that is called "vampire" on his home network, so change this to the name or IP address of your Amiga or WinUAE emulator. +Of course, this Amiga needs to be running RADRunner in server mode: + +```shell +RADRunner server +``` + +The second argument, SCRIPT, tells RADRunner to run a script file, and the third argument, "Examples\\SendAndExecute.rad" +is the name of the script to run. This script enables you to perform multiple steps in a single execution of RADRunner. +First, it will transfer the recently built binary to the remote Amiga system and then, it will instruct the remote system +to execute it and to return the output via stdout. To run the launch configuration inside VS Code, select __View -> Command Palette...__ +and start typing __Makefile: Run the selected binary target in the terminal__. Select this, and it will build the +executable and run the _Launch target_ you set previously. If all goes well, the Amiga executable will be remotely +launched and its stdout will be displayed on the remote Amiga's shell and also in the terminal of VS Code. In this case, +you should see something like the following: + +```shell +D:\Source\RADRunner>"d:\Utils\Windows\RADRunner.exe" vampire script SendAndExecute.rad +Parsing script "SendAndExecute.rad"... +Sending request "send" +send: Sending file "Debug/RADRunner" +send: Transferring file "Debug/RADRunner" +send: Transferred 235.424 Kilobytes in 0.47 seconds +Sending request "execute" +execute: Executing file "RADRunner" +Error: REMOTE argument must be specified +execute: Command complete +``` + +If you get the output "Executing file "RADRunner"" and "REMOTE argument must be specified" then the native version of +RADRunner that was just built is being executed successfully. It is not actually useful, as RADRunner can't be used to +develop itself, but it shows how the end-to-end system works, so you can copy these configuration files to your own +project's directory and use them there. + +As a bonus, RADRunner can also be built with CMake, which makes it possible to hit \ to build the local +Windows/Linux/Mac OS version and \ to run it, and then you can bind \ and \ to do the same +thing for the Amiga OS build. The author finds that this works quite seamlessly! So please feel free to have a look at +how the RADRunner build works in VS Code and try to build it yourself, to get some ideas of how to configure your own +multiplatform project. + +As an extra bonus, take a look in the _.github/workflows_ directory to see how RADRunner is built for Amiga OS3, OS4, +Windows, Linux and Mac OS on GitHub using Code HQ's Amiga OS3 and OS4 builder actions, and feel free to use them in +your own projects! + +And as an extra extra bonus, the author's _c_cpp_properties.json_ file is included in the Examples directory. This file +enables you to easily get syntax highlighting, code lookup and code completion working in Visual Studio Code, when +developing for Amiga OS. This allows you to type in an Amiga OS type or function name and to hit \ to see its +definition. You will need to copy this file to your .vscode directory and tweak the compiler paths to suit your system. +It can also be used when building the same project for other targets, such as Windows, and can be adapted easily for +Linux and Mac OS. To activate Amiga OS as a target, simply open a .cpp file in your project, open the _command palette_, +type __"C/C++: Select a Configuration..."__ and select "AmigaOS3", or activate it from the "Select Language Mode" button on +the bottom right of the VS Code window. + +## Favourite 2: Native development on Amiga OS with remote compilation + +In this scenario, we wish to develop on the Amiga itself, using our favourite text editor, with the source code on a +remote PC or Mac. + +To begin with, you need to mount the PC or Mac drive remotely, so that you can edit the source remotely on the Amiga. +This is sadly not easy on Amiga OS, as modern networking is not the Amiga's strong point. Some options are Samba and +FTPMount. The author of RADRunner has used both of these methods on OS3 and OS4. + +Once the PC or Mac drive is mounted and you've edited some files, you can execute the commands below to perform a remote +compilation from the Amiga. + +On the PC, start a shell and ensure that you are in the directory that contains the source code that you wish to +compile, and start RADRunner in server mode: + +```shell +RADRunner server +``` + +On the Amiga, request the PC to perform a compilation: + +```shell +RADRunner execute make +``` + +At this point, you will see the results of the compilation displayed on the Amiga's shell, as though the compiler was +running natively on the Amiga itself (that's the beauty of this system). Now, you can fetch the executable that was +just built: + +```shell +RADRunner get +``` + +### Wrap it all up + +This can be automated so that you don't have to type multiple commands every time. Simply add the EXECUTE and GET +commands in a script that you can execute with RADRunner's SCRIPT command. Then, create a script file that can be run +on the Amiga called "make", that just calls RADRunner with the SCRIPT command. Ensure that the s bit is set, and then +you can build on the Amiga as follows: + +```shell +9.Work:NewStuff> make +Parsing script "BuildAndGet.rad"... +Sending request "execute" +execute: Executing file "make DEBUG=1" +Compiling ClientCommands.cpp... +Compiling Execute.cpp... +Compiling RADRunner.cpp... +RADRunner.cpp:488:6: warning: unused variable 'unusedVariable' [-Wunused-variable] + int unusedVariable; + ^~~~~~~~~~~~~~ +Compiling ServerCommands.cpp... +Linking Debug/RADRunner... +execute: Command complete +Sending request "get" +get: Requesting file "Debug/RADRunner" +get: Transferring file "RADRunner" of size 241064 +get: Wrote 235.424 Kilobytes to file "RADRunner" in 0.165 seconds +``` + +The output above is cut and pasted from a Vampire 4 Standalone running Amiga OS 3.1, performing a remote build of +RADRunner. You can see the steps of requesting the build, the remote PC performing the build, the compiler outputting a +warning (of course this has been added for demonstration purposes - RADRunner compiles with zero warnings on warning +level 4!) and finally fetching the executable for local testing. Once you get used to saving changes in your text +editor, switching to the shell and typing "make", it "feels" very much as though the compilation is actually being done +on the Amiga - which is the whole point of RADRunner! + +Take a look at the "make" and "BuildAndGet.rad" files in the [Examples](https://github.com/hitman-codehq/RADRunner/blob/master/Examples) +directory. They work with RADRunner by default, but you edit and use in your own projects. Just change \ to +the name or IP address of your PC and \ to the name of the executable that is built. Remember to type +"protect make +s" on the Amiga to make the "make" script executable, as this can't be saved by git! # Compiling +To build RADRunner, you need a cross-platform framework called "The Framework" (yes, a very imaginitive name!), which +is available on GitHub [here](https://github.com/hitman-codehq/StdFuncs). Clone both repos to the same directory, like +this: + +```shell +git clone https://github.com/hitman-codehq/StdFuncs.git +git clone https://github.com/hitman-codehq/RADRunner.git +``` + +When building RADRunner, it will depend on The Framework headers and libraries being found in ../StdFuncs, so first, +you should build StdFuncs, and then you should build RADRunner. See the documentation in The Framework's GitHub +project [here](https://github.com/hitman-codehq/StdFuncs#compiling) +for information on how to build for all platforms. Once built, come back to the RADRunner directory and build RADRunner using the same mechanism. + +If you are building RADRunner on Windows, simply load the RADRunner.sln solution into Visual Studio and The Framework +will be automatically built as a dependency when RADRunner is built. + # Future The creation of RADRunner was prompted by my purchase of a wonderful Vampire 4 Standalone system and the desire to @@ -268,6 +540,5 @@ program it in a more modern way than what was provided natively on an OS3 based - Add support for preserving protection bits such as the Amiga script bit - Allow multiple commands to be specified on the command line -- Capture stdin, stdout and stderr when running the EXECUTE command on Amiga OS and UNIX - Add the ability for multiple clients to connect simultaneously - Improve the script parser