ktransw

A wrapper around Fanuc Robotics' command-line Karel translator (ktrans.exe) that makes it work a little more like a modern compiler by adding some missing functionality (like support for multiple include paths and dependency file generation).

As of v0.2.4 support for FANUC dictionaries and forms has been added to support preprocessor directives, multiple include paths, and functionality to build using rossum.

Installation

Install Git & Python
(optional) Create a python virtual environment python -m venv <name>
Clone the repo git clone https://github.com/kobbled/ktransw_py to a user specified directory. If using an python virtual environment this can be cloned within your venv is you so choose.
Run the install file in a powershell terminal, with the optional argument specifying the path to your created venv.

. ./install.ps1 <path\to\venv>

Alternatively a convenience distribution for Rossum can be downloaded and installed, which includes ktransw. Goto https://github.com/kobbled/rossum/releases for details.

If ktransw, and kcdictwit is not on the PATH, its location must be provided by using the --ktrans command line option with each invocation.

[!NOTE]

On windows machines the python alias can be overwritten by the py launcher where python is started in the terminal with py -3. The batch files are written with the python key. To create the alias type this into powershell:
Set-Alias -Name python -Value "path\to\Python\Python39\python.exe"
replacing the value with the full path to the python executable in your PATH environment variables.

[!WARNING]

If you installed ktransw with the "install.ps1" script the steps in Requirements, and Dependencies are not needed. If you are trying to setup in a linux/unix environment follow the steps below.

Requirements

ktransw was written in Python 3. Python dependencies can be installed with

pip install -r requirements.txt

Add the ./bin directory of ktransw to your environment Path

The script itself requires the the Fanuc tool ktrans.exe to compile the code into a binary form for the robot controller to read. ktrans.exe should be installed with a copy of Roboguide or OLPCPro. The standard location of the Fanuc tools is C:\Program Files (x86)\FANUC\WinOLPC\bin. Make sure this is on your environment Path if you run into troubles.

A robot workcell also needs to be created in Roboguide, or OLPCPro in order to operate. See the manual for Fanuc Roboguide for details. Once a workcell has been created, and robot.ini file needs to be generated. The robot.ini file is a set of file pointers to tell the ktrans compiler where to look and gather resources during compilation. The robot.ini file can be generated by typing setrobot into a terminal, and selecting the appropriate workcell. The robot.ini file should be in the root directory where the karel code you are trying to compile lives.

Dependencies

ktransw relies heavily on the GPP Preprocessor. A prebuilt .exe is supplied in "./deps/gpp". Simply add the location of the exe file to your environment Path to use. If the supplied .exe file does not work on your machine, or if it needs to be upgraded, please follow the compilation guide for windows: ./deps/gpp/WINDOWS_SOURCE_BUILD_README.md

Usage

usage: ktransw [-h] [-v] [-q] [-d] [-E] [-M] [-MM] [-MT target] [-MF file]
               [-MG] [-MP] [--ktrans PATH] [--gpp PATH] [-I PATH]
               [ARG [ARG ...]]

Version 0.2.3

A wrapper around Fanuc Robotics' command-line Karel translator (ktrans.exe)
that adds a C-like preprocessor, support for multiple include directories,
conditional compilation, include guards, macros and more.

positional arguments:
  ARG                   Arguments to pass on to ktrans. Use normal (forward-
                        slash) notation here

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         Print (lots of) debug information
  -q, --quiet           Print nothing, except when ktrans encounters an error
  -d, --dry-run         Do nothing, except checking parameters
  -E                    Preprocess only; do not translate
  -M                    Output GCC compatible dependency file
  -MM                   Like '-M', but don't include system headers
  -MT target            Change the target of the rule emitted by dependency
                        generation (default: base name of source, with object
                        extension (.pc))
  -MF file              When used with -M or -MM, specifies a file to write the
                        dependencies to.
  -MG                   Assume missing header files are generated files and add them
                        to the dependency list without raising an error
  -MP                   Add a phony target for each dependency to support renaming
                        dependencies without having to update the Makefile to match
  -k, --keep-build-dir  Don't delete the temporary build directory on exit
  --ktrans PATH         Location of ktrans (by default ktransw assumes it's on the
                        Windows PATH)
  --gpp PATH            Location of gpp (by default ktransw assumes it's on the
                        Windows PATH)
  -I PATH               Include paths (multiple allowed)
  -D  /D                Define user macros from command line
  /config               Location of the workcells robot.ini file

Example invocation:

  ktransw /IC:\foo\bar\include /IC:\baz\include C:\my_prog.kl /config robot.ini

All arguments using forward-slash notation (except '/I') are passed on
to ktrans.

Examples

As ktrans stand-in

ktransw is supposed to be a transparent wrapper around ktrans.exe. Refer for more information on the use of ktrans.exe to the relevant Fanuc Robotics manuals.

Using the pre-processor

See the gpp documentation for more information.

%class pre-processor directive

Object construction or generic templating can be achieved with the %class directive, and proper formatting:

%class <class-name>('<class-file>.klc','<class-header>.klh','<template-file>.klt')

Note : the .klt file is optional, used for creating generic templates but is not needed for creating a class.

See bank_class test in rossum_example_ws to see how to format classes.

Note : Take note of the usage of instances of class_name. This is a pre-processor macro that will be replaced with the class name defined in %class for each object.

In ktransw objects are first created with pure gpp:

%defeval class_name <class-name>
%include <template-file>.klt
%include <class-file>.klc

Running these files through a few cycles of GPP will flatten and replace preprocessor directives with their defined karel code. The user is responsible for managing the namespacing and scoping of members/attributes. The user can do this as they wish by defining multiple header files, one for usage only in %class, and another for outside of the object instantantiation to give member visibility to the main program. The user can also choose to follow the method in bank_class which leverages a third party package ktransw-macros. The only thing that is required is that class_name is included in the .klc, and .klh file for each routine, and program definition so that they resolve to the same definition as outside of the class scope.

Note : If you are building to roboguide < v9.10, you might have a 12 character limit for definitions. In this case it is advisable to use ktransw-macros, and the <class_name>__<function> namespacing technique, giving short alias names to each function.

Note : Processing of %class directives assumes extensive use of GPP mode:

%mode string QQQ "`" "`" "\\"

Using specifically the ` char for defining multi-line GPP functions to comply with the current GPP syntax definition:

'+z',       # Set text mode to Unix mode (LF terminator)

'--includemarker "-- INCLUDE_MARKER %:%:%"',
          # line:file:op

'-U',       # User-defined mode
'""',       # the macro start sequence
'""',       # the macro end sequence for a call without arguments
'"("',      # the argument start sequence
'","',      # the argument separator
'")"',      # the argument end sequence
'"("',      # the list of characters to stack for argument balancing
'")"',      # the list of characters to unstack
'"#"',      # the string to be used for referring to an argument by number
'""',       # and finally the quote character (escapes embedded string chars)

'-M',       # User-defined mode specifications for meta-macros
'"\\n%\w"', # the macro start sequence
'"\\n"',    # the macro end sequence for a call without arguments
'" "',      # the argument start sequence
'" "',      # the argument separator
'"\\n"',    # the argument end sequence
'""',       # the list of characters to stack for argument balancing
'""',       # and the list of characters to unstack

This is done as a return character cannot be used to seperate a pre-processor function without conflicting with karel. The ` string mode is incorperated into ktransw in order to dispose of the leftover ` chars to resolve nested macros.

%from <file-name> %import , , etc...

A "from/import" custom directive similar to that in python is included with ktransw. This is done to decrease cross dependencies between your files by copying the full headers of each repository. If a header routine definition gets changed you may find you cannot load the program back onto the controller. This is because another program think that this program has a different routine definition. To get the program to load back on the controller you must first delete all the programs with a reference to the changed routine. Using "from/import" will limit these conflicts, and make then easier to find.

the %include preprocessor directive will simply copy the file contents into the current file. If you use the karel directive %INCLUDE, this will defer inclusion to the karel compiler which may work easier, however doesn't support macros, or different file specifications (i.e. .klt, .klh, .klc)

user macros

Pre-processor macros can be defined from the command line invoking -Dname=val, or /Dname=val. See [GPP documentation][GPP].

kcdictw

A wrapper tool for kcdict is also included in this package called kcdictw. This tool will compress the .ftx, or .utx dictionary file into the temp directory, %TEMP%, and copy over the output .tx, .vr into the working directory, and the .kl karel include file into the root directory of the .ftx or .utx file. If you would like to keep the other .ftx files created by kcdict, use the --keep-build-dir option as to not delete the temp folder, where yo u can manually copy over the files after.

Disclaimer

WinOLPC, OlpcPRO and Roboguide are products of Fanuc America Corporation. The author of ktransw is not affiliated with Fanuc in any way.

kobbled/ktransw_py