Using Code::Blocks for MTX Development

A request was made on MEMORUUM for:

• A library of C callable routines for writing programs for the Memotech MTX
• The ability to develop MTX programs without having to make extensive use of the command line and makefiles.

The author has done some research and identified Code::Blocks as an IDE which provides a possible development environment, and has begun to develop a library of routines. This document outlines the installation and use of Code::Blocks. The description is aimed at Microsoft Windows users, but all the relevent programs are also available for Linux.

This is a work in progress and is subject to any feedback on the forum

Installation

The following items are required:

• Python - Used to convert the Intel Hex format files produced by SDCC to Memotech MTX *.RUN files. Download Python from here.
• SDCC (Small Device C Compiler) - To compile C code into Z80 machine code. Download SDCC from here.
• Code::Blocks - An Integrated Development Environment which can be used with SDCC. Download Code::Blocks from here.
• MTX_Projects - The package containing this documentation. The latest version should be obtainable from here.

Install Python, SDCC and Code::Blocks in that order. Unzip MTX_Projects ina suitable location for your code development.

Configuration

The first time Code::Blocks is started, it should scan your system and identify which compilers you have. On the compiler selection screen (no screenshot available), select SDCC and then click the button to make that the default compiler. Close the dialog.

Once the main Code::Blocks window has opened, select "Settinss / Compiler..." from the menu. Ensure that "Small Device C Compiler" is selected. Then under the "Compiler settings" tab, and the "Compiler Flags" sub tag, scroll down, and check the option "[CPU] Zilog Z80 (-mz80)".

Next select the "Toolchain executables" tab. Change the "Linker for static libs" from "sdcclib.exe" to "sdar.exe". Then click OK to close the dialog.

It is now possible to test the configuration by compiling the library and demonstration program. From the menu select "File / Open..." and open the "MTX_Projects\MTX_Projects.workspace" file. This will load two projects: "MTXLib" and "demo".

Select "Build / Build workspace" from the menu. This should:"

• Build the library.
• Build the demonstration MTX program.
• Run the demonstration program in MEMU.

This has built the library source. It is not necessary to redo this unless the library is changed.

Context Sensitive Help

The Windows version of Code::Blocks is able to provide context sensitive help. To configure this select "Settings / Environment..." from the menu. On the left hand pane of the resulting dialog, scroll down to the bottom and select "Help files". Then on the right hand side, click the "Add" button. Set the help title to "MTXLib" then click "OK".

At the next dialog, select "Yes" to browse for the file location:

Browse to select "MTX_Projects\MTXLib\docs\routines\MTXLib.html". You will have to select "All files (*.*)" in the file open dialog to find this file. Click "Open" to select the file. The full path of this file will now be shown in the edit box just below the main box. Edit this path, replacing "MTXLib" by "$(keyword)". The full path should then look something like:

      MTX_Projects\MTXLib\docs\routines\$(keyword).html
    

Check the "This is the default help file" option. Optionally (your preference) check the "Open this file with the embedded help viewer". Set the "Default keyword value to "MTXLib".

Click "OK" to confirm the configuration and close the dialog.

Having configured this, if you open a C source file in the Code::Blocks editor, position the cursor on the name of an MTXLib subroutine, and type the <F1> key, then help on that routine will be opened.

Creating a New Program

To create a new program, select "File / New / Project..." from the menu. From the resulting dialog select "Empty Project", then click "Go".

Work through the new project wizard. For the resulting RUN file to be visible to MEMU, the project title should be lower case, have no spaces and be no more than 8 characters. Create a new folder under "MTX_Projects" for the project. The name of the new folder should be the same as the title of the project.

With SDCC there seems to be little point in separate "Release" and "Debug" builds, so just select the "Release" build, and name the output directories "bin\" and "obj\".

Select your new project, then from the menu select "Project / Build options...". From the resulting dialog, select the "Linker settings" tab. Under the "Link libraries" box, click the "Add" button and browse and select "..\MTXLib\lib\MTXLib.lib". When asked "Keep this as a relative path", answer "Yes". Next, in the "Other linker options" box, paste:

      --code-loc 0x8000 ..\MTXLib\lib\crt0.rel
    

Select the "Search directories" tab. Select the "Compiler sub-tab. Click the "Add" button at the bottom and browse and select "..\MTXLib\include". When asked "Keep this as a relative path", answer "Yes".

Next, select the "Pre/post build steps" tab. In the "Post build steps" box, paste:

cmd /c ..\MTXLib\tools\ihx2mtxrun.py $(PROJECT_DIR)$(TARGET_OUTPUT_FILE)
cmd /c ..\MTXLib\tools\mtxrun.bat $(TARGET_OUTPUT_DIR) $TARGET_OUTPUT_BASENAME).run
    

Finally, check the "Always execute, even if target is up-to-date" option. Click "OK" to close the dialog.

You may now add your C source files, and selecting "Build / Build" from the menu should compile, link and run your program.

Structure of MTX_Projects

The folder structure of "MTX_Projects" is:

• MTX_Projects - The top level folder
  • MTXLib - The library of routines for accessing the MTX. Library source is here.
    • docs - Documentation.
      • routines - Help for each of the MTXLib routines
    • include - Include files defining the library routines.
    • lib - Files to link with your program.
    • obj - Compiled library routines.
    • tools - Scripts for building and running the program.
      • ihx2mtxrun.py - A python script to convert the Intel Hex file produced by SDCC to an MTX format RUN file.
      • mtxrun.bat - A batch file to run MEMU with all the options needed to emulate a Memotech with SDX, to use a Windows folder as the A drive, and to load and run a RUN file.
      • mtxrun.sh - A Linux shell script to do the same as the above batch file.
  • demo - A simple program demonstrating the library and build process.
    • bin - The compiled demonstration program.
    • obj - Compilation of individual C source files.
  • MEMU
    • run_time
      • memu-win - A Windows version the Memotech emulator for testing the programs.
      • memu-x - A Linux version the Memotech emulator for testing the programs.

Limitations

Code::Blocks is a complex program, and the author has only spent a few days using it, so with more experience it may be able to resolve some of these issues.

• Code::Blocks is primarilly intended to compile programs which run on the same platform as Code::Blocks itself is running. This results in a number of assumptions that are not valid for SDCC.
• No way has yet been found to make the "Build / Run" menu option run the program. Therefore running the program has been included as a final post-build step.
• Code::Blocks does not support the SDCC debugger. However that would be of limitted use anyway as that uses the Z80 emulator that is part of SDCC, which does not emulate the MTX hardware. It is necessary to rely on the debugging features in MEMU. There is no source level debugging.