DevelopmentWithCodeBlocks
The intent of this section is to guide you through the setup steps for developing and debugging AGC/AEA applications like Colossus,Artemis,Luminary,FP6 or your own application with the integrated development environment Code::Blocks. This IDE (based on wxWidgets) is a cross platform development environment with a graphical debugger. These steps have been verified on Linux (Code::Blocks version 13.12) and MacOS X 10.10 (Code::Blocks version 12.11)
Note: readline (version 6.3-5) may corrupt the values in the watches window. To solve this build yaAGC with NOREADLINE=yes.
You need the following software and files to develop and debug AGC/AEA applications:
- A binary install of Virtual AGC (May 2009 or later)
- Code::Blocks (12.11 or later)
- AGC/AEA lexer files for source highlighting (See SVN Contributed).
This tutorial assumes you have a properly working Virtual AGC setup (i.e. you can run yaAGC and interact with it using the virtual DSKY) and have Code::Blocks installed for your specific platform.
To work with the AGC/AEA sources and development tools in Code::Blocks one must:
- (Optional/Recommended) Configure AGC/AEA Syntax Highlighting
- Configure the AGC/AEA Debugger for development
- Configure the AGC/AEA Compiler for development
- (Optional) Configure the pheriperal devices (e.g. yaDSKY2, yaACA3)
The following sections outline how to configure the toolchain and project specifically for Luminary131 and the AGC debugger but similar steps need to be made for AEA tools.
Code::Blocks uses Scintilla source editing and so uses the Scintilla methods for enabling syntax highlighting capabilities. To create a real AGC/AEA lexer would require patching the Code::Blocks lexer from Scintella to make it aware of the new lexer capabilities. Since this is not desirable the approach taken here is to reuse and existing lexer and only configure the lexer with a configuration file. The lexer configuration files provided as part of Virtual AGC for AGC/AEA are (ab)using the "Makefile" lexer. These files can be found in virtualagc/Contributed/SyntaxHighlight/CodeBlocks/lexer.
To install the lexer configuration files just copy the .xml and .sample files for both the AGC and AEA to the lexer folder of Code::Blocks (e.g. /usr/share/codeblocks/lexer or on ).
To verify the proper installation start the Code::Blocks IDE and launch the "Editor..." dialog from the Settings menu. In the dialog select the Syntax highlighting section and subsequently select either AGC Assembly or AEA Assembly in the Syntax highlighting for field. A correct configuration will show sample code for either AEA or AGC with syntax highlighting. In addition to verifying the installation you can also customize the colors to your liking.
To work with the AGC tools one must setup and configure the AGC Debugger first. From the Settings menu select the "Debugger..." option from the settings menu. This will launch the Debugger settings dialog.
In the Debugger settings select the GDB/CDB Debugger to be used as the basis for our new compiler definition. Use the Create Config button to create the AGC Debugger configuration. Next select the newly create configuration and set the executable path to point to the yaAGC binary and set the type to GDB. Only select the "Do not run debugee" option.
Now from the Debug menu select the active debugger-> GDB/CDB Debugger: AGC Debugger
Next create a new compiler configuration. Select the "Compiler..." option from the settings menu. Pick the GNU GCC Compiler as the basis to copy and create the new AGC yaYUL Compiler configuration. Make sure no compiler flags are selected.
For the Toolchain executables do the following:
- Specify the directory of the Virtual AGC binary distribution as the compiler installation directory.
- Add an additional path to the directory that contains the yaYUL binary.
- Set the Compiler and Linker fields (i.e. 4 fields) to yaYUL.exe or yaYUL based on your platform.
- Set the Debugger to "GDB/CDB debugger: AGC Debugger" .
- Leave the resource compiler set to its default value
- Set the specific Make program which you use for your makefiles. If your make tool is not in the search path then add the location of the make utility in the Additional Paths tab. Under MinGW you probably want to specify mingw32-make.exe instead of the default make.
Not yet specified because yaAGS and yaLEMAP still need to be converted to handle gdb and gcc parameters.
The Code::Blocks IDE allows you to integrate the launching of user defined tools. This is a convenient location to configure the launching of a Lunar Module DSKY or Lunar Module DEDA.
To add these tools select the Configure Tools option from the Tools menu:
- Press the Add button to create a new user tool
- Specify the name (e.g. Lunar Module DSKY)
- Specify the executable yaDSKY2.exe or yaDSKY2 (use a full-path to the executable)
- Specify the tool options (e.g. --port=19697)
- Set the Working directory to the Virtual AGC Resources directory
- Set the radio button launching option to tool visible detached
To launch the user tool make sure you start with a running AGC or AEA. Continue adding the DEDA as well as the ACA (The ACA you may want to launch from a console if you use ACA3).If you experience connection issue with the AGC or EAE try varying the base port.
When you work on a AGC project you need to define in Code::Blocks the project space, which sources are part of the project and what tool chain is used. The steps below help you to accomplish these steps.
This section of the tutorial uses Luminary131 as an example. Obviously when you have your own application you can adjust and customize the values to your liking.
Select from the File menu the option New/Project and select the Empty project Wizard.
- Provide the Project Title (e.g. Luminary131)
- Specify the location of where the Luminary131 folder is located (i.e. the folder containing Luminary131)
- Leave the Project filename untouched
- Verify the Resulting filename field ( Luminary131.cbp project file in the folder of Luminary131 )
- Press the Next button.
Specify the compiler tool and which configuration to enable for your project:
- Select the AGC yaYUL Assembler
- Enable the Debug configuration and name the configuration (Don't leave the name Debug"): default
- Clear both the Output dir as well as the Objects dir field.
- Press the Finish button.
First configure the new assembly extension .agc and .aea before associating these extensions with the internal Code::Blocks editor. Right-click on your project (e.g. Luminary131) and navigate to the Project Tree option. On the sub-menu select the option 'Edit file types and categories...'. This brings up a category window. Select the 'ASM Sources' category and add the '.agc' and '.aea' extensions.
Next configure which editor can open these new extensions: From the main menu select the 'Settings' menu and pick the 'Environment' option. In the dialog's left pane select the 'Files extension handling' section. Then add the '.agc' and '.aea' and specify that these extensions shall be opened with the Code::Blocks editor. You maybe required to add the star wildcard in front of the period of the extension.
Add the Sources:
- In the Projects pane Right click on the Luminary131 project
- Select the Add Files option from the Popup Menu
- Specify for Files of type the AGC/AEA Assembly files
- Select all assembly files (i.e. .agc)
- Press the Open button.
Now the appropriate sources are part of your project and can be opened in the editor by just double clicking the respective assembly file. If you try you will notice the syntax highlighting in the editor pane.
To allow the IDE to compile and debug the code some of the Project Properties must be changed:
- In the Projects pane Right click on the Luminary131 project
- Select the Properties option from the Popup Menu
- In the Project settings tab specify your Makefile (e.g. Makefile)
- Check the "this is a custom Makefile" checkbox.
- Leave the Object names generation unchecked.
- Set the execution directory to where the Luminary131 files are located
On the Build targets tab make sure the following are set for the default target:
- Set Platforms to All
- Set Type to Native application (yes this matters for the IDE)
- Set Output filename to Luminary131.bin
- Uncheck both the Auto-generate prefix and extension check boxes.
- Set the execution dir to . (i.e. the directory of the sources)
Next you must set the proper make commands:
- Right click on the Project icon in the treeview and select "Build options..."
- select the "default" target and then the "Make" Commands tab
- Set the following for the 4 fields: Build project/target: $make $target Compile Single file: $make Clean project/target: $make clean Ask if rebuild: $make -q
Once these steps are completed you should be able to build and clean the target files. To try use the Ctrl-F9 or select from the Build menu the option Build. You should get two warnings when building Luminary131. Check the Build Messages to see these warnings and double click to jump to the specific location in the assembly source file where the warning occurred. If you get an error you might want to remove the diff command from the default target in the Makefile
Now you are in principal ready to start debugging. If you don't have any breakpoints set it is advisable to just use the Step-into Debug option (or the equivalent button) on the Debug menu to start debugging. Step into at least twice to ensure that you see the current pointer point to the location in the assembly code of where the current inner stack frame is ready to execute next.
This section is intended only to show some capabilities of the GDBM/MI console interpreter being used within Code::Blocks.
- Start Code::Blocks and load the Luminary131 project if you have not already done so
- Ensure the Luminary131 build is up to date
- Start bebugging by twice executing the Step-into function of the Debugger (notice the change in pane layout)
- From the Debug menu go to the Debug windows option and enable the CPU Registers,Call Stack and Running threads windows. You can either dock them all in the main window or leave them floating.
- Now continue single stepping (i.e. press F7) for some time and examine the CPU registers and Call Stack as you go.
- Open the File INTERRUPT_LEAD_INS.s and set a breakpoint at line 35 (i.e. T3RUPT)
- Now select Continue (i.e. Ctrl-F7)
- The system will halt execution when the TIMER3 interrupt occurs.
- Examing the Running threads window
- As you single step the T3RUPT handler watch the CPU register values.
- In the Call Stack window double click the visible stack frames to jump to the line of code from where the jump was made to the next stack frame.
- Continue single stepping.
- Open the Watches window
- Add some watches (either right click on a variable or use the Debug Edit Watches option).
- Keep single stepping.
- Open the Examine memory window
- Specify an address (either hexadecimal,decimal, octal or a banked address ) to start dumping from (e.g. 0x6c or 0154 or E0,0154).
- Send a console debug command to the debugger by selecting option Send user command to debugger (e.g. next 500)
After these steps you can start examining and learning the full AGC software and extend your capabilities in Code::Blocks. Also not that if the debugger Stop function is not working that you should just kill the yaAGC process. No need to bring down the complete debug environment.