Release Notes for Cycle Compiler Version 0.0.2

Cycle Compiler v0.0.2

The following release notes are applicable to the above version of the Taurus Cycle Compiler. The copyright notice is applicable to any version of the Compiler unless stated otherwise.

Copyright notice
The Taurus Java Virtual Machine is © Copyright 2003-4, R.H.Thornburrow, Taurus Software and Consulting.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

The Cycle Compiler has been produced without any collaboration with Ultimate Real Robots Magazine, and is not associated with it or Eaglemoss in any way. Please do not contact Eaglemoss regarding any problems with Cycle - these should be addressed to the Help forum on the SourceForge project page.

Java is a trademark or a registered trademark of Sun Microsystems, Inc. All other trademarks are the property of their respective owners.

All references to Taurus Software directly refer to the non-profit freeware/shareware software development unit run from the UK by myself. Any conflict with names of companies inside or outside of the UK is unintentional and should be disregarded.

Purpose
Cycle (CYbot Control LanguagE) is a direct replacement for the graphical programming "language" that comes on CD2 of Real Robots. The Cycle compiler will take programs written in Cycle and convert the to .03p or .03s files which can be used with CDs 2, 3, 4 and 5.

Language Support
All the features of the graphical "language" as supplied with Programmer 03 on CD5 of Ultimate Real Robots are supported.

There are one or two limitations due to the way that links can be made between blocks so that they do not form a single sequence. This is particularly evident where the inputs from two separate sensors blocks are linked to the same motor block. This cannot be expressed in Cycle as the sensor blocks are handled by switch statements and it is not possible to share code between switches. This could be implemented using a 'goto' statement, but this has deliberately been kept out of the language as usually leads to spagetti code. To achieve the same effect simply duplicate the code which you want to share - this has no real effect on the program, other than making it slightly larger.

Platform Support
The Cycle Compiler version 0.0.2 is provided in binary form on the following platforms:

Win32 - should work with any i386 based Microsoft Windows™ OS (95/98/ME/NT/2K/XP)
Cygwin - Cygwin running on Win32

For space reasons is provided without any of the required support libraries (DLLs and .so's). In order to run this software you must install these libraries yourself (they are likely to be already installed on most systems). Binaries for other platforms may follow at some later date.

Installation
The Cycle Compiler is shipped as a ZIP file. To install, simply unzip to a suitable location on your hard drive. e.g. C:\Cybot (or even C:\). This will create a directory called Cycle containing the compiler (in the bin folder, cycbot.cyc (in the include folder) and some example files (in the examples folder.

You may wish to add C:\Cybot\Cycle (or path_to_cycle\Cycle\bin) to your PATH environment variable (this isn't necessary, but means you can run the compiler from anywhere).

Running
Running the Cycle Compiler is very easy, and it is designed to be run in a similar way to any other compiler.

If you do all your work in the Cycle folder, then you can run Cycle as .\bin\cycle. If you run it from the examples folder you would run it as ..\bin\cycle. To run it from anywhere else (if it isn't in your PATH), the you would type path_to_cycle\Cycle\bin\cycle. In the examples below substitute ..\bin\cycle with the appropriate path for your installation (or use the batch file and Makefile provided).

In the examples folder you will find a Cycle source file called flash4.cyc. To compile this file you would enter:

..\cycle -oflash4.03p flash4.cyc

This will produce a file called flash4.03p in the current folder containing a compiled version of the program which can be loaded into Programmer 03 or the Simulator. Note that there is no space between the -o and the output filename. If you do not specify an output filename, then the output is written to output.03p.

Windows and Cygwin users may optionally specify -i to install the compiled output in the Real Robots Robots Programs folder. Be careful, as like most compilers, this will overwrite any file of the same name without warning.

Note: Cygwin users will need to edit the file Cycle/cyclerc so that it contains the paths to your Real Robots, Robot Programs folders. Windows users don't need to do this, as the information is picked up out of the registry.

Also in the examples folder you will find a Makefile (for Cygwin users) and a batch file called build.bat (for Win32 users). These compile all the example programs in the examples folder.

Troubleshooting
If you have problems loading the compiled code into Programmer 03, or you get unexpected results, then the compiler can be run in debug mode and will produce a listing of what it has parsed. To do this, the above example would become:

..\cycle -v -t flash4.cyc

The dumped code should match the input program exactly. If it does not, then please post the problem code (and if possible the output of the above command) to the Help forum on the SourceForge project page along with a brief explanation about what it is supposed to do.

Appendix A - Command Line Switches
The Cycle compiler currently supports the following switches and arguments:

Switch	Meaning
`-d` or `--debug` n	Causes the compiler to emit debugging information. This is primarily for debugging the parser and lexer and is not something you would want to run in normal use. n is a bit mask, whereby bit 0 (1) turns on parser debug and bit 1 (2) turns on lexer debug. To turn on both, you would set bits 0 and 1 (1 + 2 = 3).
`-e` or `--ignore-errors`	Ignore syntax and semantic errors and try to produce output anyway. This is usually an very bad idea, but if you have having problems compiling what you believe to be valid code, then using this switch along with `-t` and `-v` you can safely produce a dump of the parse tree to aid debugging.
`-h` or `--help`	Help. Displays a brief usage message describing the valid switches to the compiler.
`-i` or `--install` [cd2\|cd3\|cd4\|cd5]	Install. Cause the output to be written to `Robot Programs` folder in the Real Robots installation directory. This allows compiled Cycle programs to be loaded directly into the Real Robots Programmer and Simulator. Make sure that you use a different filename than any programs you want to keep, as like most compilers, Cycle does not warn if it is about to overwrite a file.
`-m` or `--mode` cd3\|cd4\|cd5	Mode. Cause the compiler to generate output compatible with the named `Robot Programs` CD. If not specified, the simpler CD2 output format (which can be read by the other CDs) is used for programs, but the CD3 format will be used for subroutines as te CD2 format is not powerful enough.
`-n` OR `--no-logo`	No Logo. Causes the compiler to remain quiet when comiling. It normally prints a copyright message each time it is run. This is useful from Makefiles as the only output should then be error messages.
`-o` or `--output` filename	Output. Causes the output to be written to the given filename. filename should be given a `.03p` file extension in order for the Real Robots software to recognise it - `.03p` is not added automatically. If no `-o` switch is specified, then the default filename is `output.03p`
`-p` or `--show-parse-tree`	Display Parse Tree. One `-p` will produce a dump of the parse tree immediately after syntax anaylsis. Two `-p` switches will produce a similar dump, but after the transformation of for loops and assignment statements. Three `-v` switches will produce both dumps.
`-t` or `--translate-only`	Translate only. This switch causes the compiler to exit without producing any output. This is useful for testing that programs compile correctly without going to the code generation stage. It is also useful when used with the `-v` option in diagnosing compiler errors.
`-v` or `--verbose`	Verbose. Causes the compiler to produce verbose output about what it is doing. If specified twice, produces very verbose output.
`-V` or `--version`	Displays the version number of the compiler.

Last updated 14th July 2004
Comments to Help forum on SourceForge project page.