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.
- 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 kcdictw
it 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 withpy -3
. The batch files are written with thepython
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.
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.
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: 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.
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.
See also rossum.
See the gpp documentation for more information.
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.
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)
Pre-processor macros can be defined from the command line invoking -Dname=val, or /Dname=val. See [GPP documentation][GPP].
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.
WinOLPC, OlpcPRO and Roboguide are products of Fanuc America Corporation. The
author of ktransw
is not affiliated with Fanuc in any way.