AmigaOS4SDK Plugin Quick Reference

The project information window is specific to the type of project currently being worked on. The example project uses the AmigaOS4SDK type of project, so this overview covers the options available that apply to it. Options for other project types will be similar in their application, and can be found from the above menus.

Top Tip

While it is possible to type a path into the relevant string gadgets, a file requester can be invoked by clicking the GetDir gadget button making it easier to select paths from the resulting requester.


General Settings

General AmigaOS4SDK Project settings

The General settings allow basic options to be set, the following is a complete description:

  • Project Name
    This sets the name of the project which will be displayed in the title of the CodeBench screen and the project window. It is also used as the name of the project file on disk, which will be added to the recent project list.

  • Project Base Directory
    This sets the base directory that all files will be loaded from. Files can be loaded from anywhere, but this directory will always be the default in the file requester when adding files.

  • Header files Directory
    If a directory is supplied here, it will be the default directory in the file requester when adding header files. Again, files can be loaded from anywhere, but some projects may opt to keep header files in a specific directory. If no directory is set, the project directory will be used instead.

  • Debugger Name
    A different debugger can be specified from the default here, if the project uses a specific one. "GDB" is currently the default debugger for the AmigaOS4SDK project type.

The Synchronisation settings allow you to configure how the files in your project interact with remote servers.

  • This project uses a local file repository
    Specify if this project should be synchronized with a remote file server.

  • Synchronise plugin name
    CodeBench currently includes plugins for CVS and SVN use. You may enter the name in the string gadget, or easier, select it from a file requester which is opened by the button on the far right.

    The included example plugins are by no means complete, and as such a developer kit and documentation has been included to allow development of different plugins. The SDK includes an example, which when compiled, creates the cvs plugin supplied. The SVN plugin is also based on the same example code but is slightly more advanced as it offers a system to get the user name and password via a prompt requester. Once this option has been selected, the plugin then does its job, and it runs synchronously meaning that CodeBench will wait until the plugin has finished transferring files. Please see the example documentation in the "sdk/synchronising_plugin" directory for more information.

    As a far more useful and complete example of what can be done, CodeBench also includes a full plugin for synchronising with Subversion servers, and is known as SVNBench. This is explained in detail in the relevent document.

    Synchronising the project is done via the "Synchronise" menu item.

  • Base directory for Synchronising
    Most simpler projects will probably not need to use this feature, but some more complicated and deeper projects may need to change the "Base" directory used during the synchronising phase.
    Like most directory gadgets here, you can either enter the path manually, or select it from the file requester which appears by clicking the button.

    Usually, when launching the synchronising plugin, the projects "Base" directory is used. That is usually just fine, but if your particular files are in a different directory, you may enter that here, and the synchronising plugin will use that instead.

    Point to note: If you have files that are under the control of the repository in the directory you are navigating away from, these files will not be found by the plugin, and will not be kept in sync with the server. Use this feature with caution!

  • Check for repository update after loading
    If the current project being loaded is specified to be synchronised with a remote repository, then this option will automatically scan that repository to determine whether any files need to be updated into the local "working" copy before proceeding with the project.

  • Check for repository commit when closing
    Again, if this project uses a remote repository, then this option, when enabled, will check to see if any files in the local "working" copy have been changed and should be committed to the repository before closing the project.

    As an added bonus, a fully featured plugin has been included for use with SVN servers, and more details can be found here.

  • Commit Message Preamble
    When committing files to the repository, you can add a comment here that will always be added to the commit message. You may still edit the message as normal, but adding some common text here will save you having to enter it each time you upload your files.

The Reboot Settings section specifies how this project controls what happens after building.

  • Reboot after build
    This feature is useful when developing binaries that get "locked" into memory, like libraries, gadgets etc.
    You may choose between: , or .

    Once the project has been successfully built, the specified reset will be performed. If there are any errors or warnings during the build, no reset will occur.

  • Add To WBStartup
    As it suggests, using this feature will add this project into the list of programs to be started when the computer boots up. As expected, this will run CodeBench and load this project automatically. This can save some time if you work on this project a lot.

  • Open WBStartup Prefs
    This provides an easy way to open the preferences editor for programs that are run when Workbench boots up. From here you may configure any projects you may have added with the previous option.


back to the top




Make Settings

The Make Settings concentrate on how the finished program is created. In the context of the AmigaOS4SDK type of project, building is centered around a script called a "makefile". These options change the contents of that script in different ways, and are as follows:


  • Create Makefile
    This option enables the creation of the makefile. Automatic script creation happens when the Build button is clicked and the script is deemed to be "stale". This usually occurs when changes to the project effect the script, like adding or removing files.

  • Builder name
    This sets the name of the builder, and in this context, it would be the "Make" program.
    "Make" takes the created makefile, and executes the commands specified within it. The default is correct for the AmigaOS4 SDK, but any builder of choice can be specified. For example, the AmigaOS4 SDK includes a program called "gmake" which gives more compatibility to makefiles written with the Linux development environment in mind.

  • Makefile name
    The name of the makefile can be specified here, and the script can be called any name. This name is passed to the builder automatically when the Build button is pressed.

  • Build log File
    A log of the build process can be written as a plain text file by selecting the option in the Build window, and the log will be saved to this location. The default, as can be seen above, is a file called "Build.log" in the "RAM Disk" volume. This can be changed from the default by entering the path and name of the file into the string gadget, or by selecting the file in the requester by clicking the gadget at the far right hand side.

    A log of the build process may be very handy when lots of errors and/or warnings occur, as this makes it far easier to scan and search the compilation results.

  • Stack size
    The amount of memory assigned as the stack for the build process can be set here. Generally, compilers require lots of memory, especially multi-threaded ones. The default value has been optimised for best usage performance, although larger projects may need more, lots more!.

  • Dependency depth
    When creating a makefile, each source file is scanned for other files included within it. As these "layers" extend down through many depths, this value specifies just how deep to bother going. "3" is a reasonable default and going much higher than this usually does not yield any more results but does significantly slow down the makefile generation and compilation.

  • Show Compiler Commands
    When creating a makefile, a "rule" is created for each part of the project which tells the compiler how to create this particular part. By default, the makefile uses some pattern matching techniques to create one rule for all parts which hides the actual compiler command from the Build window and simply shows which part is being compiled. When this option is enabled, the makefile will contain a separate command for each rule, and will show that command in the Build window. This option also effects the Linking stage, which is also similarly hidden by default. If you are going to create a more complex build system, then the separate commands may be useful in customisation.



The second section affects the Makefile Content. Certain extra aspects of the script can be configured, as follows: Configure makefile Includes

  • Configure Includes
    This window allows the addition, and removal, of included files within the makefile.

    Some projects may rely on external files that may contain some default variables pertinent to the project, or perhaps a set of common rules to perform specific tasks. These files can then be included in the makefile, and will appear as part of the makefile. This can be a time-saver, as it saves having to repeatedly configure the same rules for each project or component.

    Luckily, such files can be included here. Select to specify a file to be included, or select one in the list and its name and/or path. These included files will be added near the top of the created makefile for you. Of course, you can always "includes" that are no longer required, or change the order in which they appear.

  • Configure Variables
    Configure makefile Variables It may be necessary to sometimes define some variables that should be listed in the makefile. These may be "switches" that control some function within the source, or they may be to control conditional compiling. Whatever the reason you may need to include some custom variables, this editor is where you define them for inclusion.

    Configure makefile Variable As with most other editors in this section, the buttons down the right hand side give you the options to control and define any custom variables. Clicking the button will allow you to set up a new variable and define its contents. You may select an item in the list and click the button (or doubleclick an item in the list). Either way, this will open the variable editing window where you can set up your new variable.

    The "Name" and "Contents" fields define how the variable will be defined in the makefile, and with what contents it should have.

    The "Enabled" setting specifies whether the variable will actually be used in the makefile. Turning this option off means that the variable will still be present in the makefile, but it will be commented out. This allows you to define a variable which can be turned on and off easily, even by editing the makefile directly.

    Once you have defined your variables, there are a number of ways they can be used within the makefile. They can be referenced from the compiler or linker switches, for example. You may even want to reference them from a custom rule.

    In our above example, we could reference the OPTIONS variable but specifying $(OPTIONS) in one of the switches or rules sections.

  • Configure Rules
    Configure makefile Rules "Rules" in a makefile are instructions that are passed to the builder (usually "Make") telling it how to create certain objects. Apart from compiling parts of the program, rules can also be used to create distribution archives, locale catalogs, copying files for installation etc, the list is endless.
    By default, there is only so much that CodeBench can internally predict about what operations the makefile should carry out.

    To allow extra functionality, more rules can be explicitly defined and customised to suit the project or environment.

    After selecting this option, the Configure window will open. Any custom rules that may be configured will be listed. Here, one rule has already been set up, called "AmigaOS4SDK_locale.h". Selecting the rule in the list enables various options. You may create a rule, a rule that is no longer required, or change the order they will be added to the makefile by using the Up and Down buttons.

    Probably the most important button is the button. Pressing the button, or double-clicking the name in the list, will open the edit window.

    Edit makefile Rule This is where the rule is configured to carry out the actions required. The window is divided into sections, and each one is described below.

    Firstly, the Rule Name is shown at the top. The rule can have any name, but it should not clash with any other rules by having the same name, as this will lead to an error when building the project. You may also set this rule as a "phony".

    The next section deals with any Dependencies for this rule. Dependencies are files that are checked, and if any of them have a more recent date than the target of the rule (usually the name), then the rule is deemed to need executing. In the above case, the file "AmigaOS4SDK_locale.h" is checked to see when it was created. Then, in turn, each of the dependencies are also checked, and if any of them are "newer" than the target file, the rule should be executed. In our example, it means that one of the files used to create the locale file has been changed, but the catalog has not been updated. The rule could equally just have a name which signifies what it does, and does not need to be a file. This is usually the case for rules that create a distribution archive, or an installation script.

    In this case, the rule is classed as a "phony", which means that the rules target does not actually point to a file, and in this situation no dependent files are required or checked. "Phony" rules are listed as such in the makefile so the builder knows not to try and check the date of the rules target.

    Once the rule is to be executed, any Commands specified will be carried out in turn to create the target.

    In the above example, the rule would be added to the makefile like so:

      catcomp CFILE AmigaOS4SDK_locale.h NOCODE NOARRAY
      catcomp CTFILE AmigaOS4SDK_locale.ct

    In the last section, the choice can be made when to Execute this rule. (Whether it actually runs or not is subject to the outcome of the dependency checks). The current options are:

    • Before building any targets
      Selecting this option will make this rule be included in the "all-before" rule. This means it will be executed automatically before trying to build the project.

    • After building any targets
      This option will include this rule in the "all-after" rule. This means it will be executed automatically after the project has been built.

    • Manually only
      This option will not include the rule in any others, and means that this rule will only be executed when the builder is specifically told to do so. It can be selected from the build options window, apart from other ways.

It is also possible that each project type may add some extra items into the popup menu from the project window when over each file and in the editor popup menu. Please check the relevant sections of the documentation for each project type for further information.

back to the top




Compiler Settings

The Compiler is the program which converts the source code into an executable that can be run on the host machine.


  • Compiler Name
    To assist the more inexperienced users and get them compiling easier, the compiler choice is now a simple case of selecting the one required. The options are "Native GCC", "Native VBCC" and "Other". For convenience, GCC is selected by default, and everything is set up for that. If a different compiler is required, the "Other" option should be selected. The name may then be changed to the compiler program that better suits the projects particular needs. Selecting either of the pre-defined compilers will result in the name option being unavailable.

  • Compiler Switches
    The Compiler program can accept parameters when it runs, and any switches listed here will be inserted into the makefile, and passed on to the compiler at build time. More information on these compiler switches can be found in the compiler documentation.
    These switches apply to all objects in all targets. If you need specific switches for a particular object, this can be done from the project popup menu .

  • Include Debug Symbols
    This option alters the created buildscript to include the correct compiler switch to enable the inclusion of debugging symbols in the target binary. 3 different variations of symbols are available, and these are "stabs", "dwarf2" and "gdb". Depending on the debugger you intend to use with this project (and the compiler), you should choose the debug symbols most appropriate for it.
    When this option is enabled, the makefile will actually create two target binaries. One will have ".debug" appended to the name of the binary to indicate that this version has the debugging symbols embedded within it. The normally named binary will have the debugging symbols stripped out, and is intended for distribution purposes. During development, it is advised to always run the ".debug" version, as the symbols it includes can be used by the GrimReaper tool to assist the debugging of created programs.

  • Compiler Paths
    Extra directories can be added that the compiler will look in for files specified by the "#include" directive. Some included files can be specified by their absolute or relative path, while files simply called by name are located in the compilers path. This can be extended by adding locations to look in from the Paths requester.

    Compiler Paths
    Adding and removing paths is a simple case of selecting the function required, and in the case of adding, choosing the correct path from the directory requester that will appear. The order of the paths can be changed in the buildscript by using the Up and Down arrows. Select the path entry that is to be moved, and press the Up or Down button accordingly. Items at the top of the list will be added to the compiler path first, with the bottom item being last. These are added to the INCPATH variable in the buildscript.
    Changes made to this list are relayed to the system as they are made, so canceling the project information window will NOT undo the changes made here, and will require opening this requester again to undo changes.

back to the top




Error Reporting

The following section deals with Error Reporting.

Depending on the type of project you are working with, it is possible that some errors generated during the building of the project can have some extended help to explain why such errors happen.

Extra help for build errors
In the case of the AmigaOS4SDK project type discussed here, the plugin already has a basic error dictionary supplied with it, but you are free to add to it, or edit some of the error descriptions already present. We appreciate not all users are going to want, or feel qualified, to edit these descriptions. It is designed primarily for more experienced programmers to have a way to supply plain language explanations to a wide variety of compiler and linker errors, some of which can be quite misleading.

We shall discuss what each part of this dialogue does next.

Edit Error Dictionary The main list shows the entries currently contained in the error dictionary. Each entry has a basic name to identify it, but the actual error condition and descriptive text is accessed by selecting any of the shown entries and clicking the button (you can also double-click any entry to edit it).

At the bottom of this editor you can see a string gadget. You may paste errors from the clipboard to test out whether there are any matches before editing. It can also be used to test an error condition after adding one. Simply paste the error line into this gadget and press or . The editor will then check to see if there are any matches, and if found, it will show you the result in a small requester. It will also highlight the actual entry in the main list that matches what you have entered, just in case you may want to make any changes.

The entries in this editor are also used for the HelpHints in the build window, as shown in the image above. After building the project, any errors in the build window can be explained by hovering the mouse pointer over the line of interest. The "Help Hint" will show you the match found for this error (if any). The same extended help is also used in the editor gadget, and can be viewed by hovering the mouse over any highlights in the left hand info column. (see the Build Window overview for further information).

Edit Error Entry

Here we are editing an entry. Adding a new entry is the same process, it just means filling in the required data from scratch.

The first item is the Name, and this is what is shown in the main list to identify this error.

Next is the actual text used to form the Matches from the error in the build window. We can have multiple entries here to match a number of errors and supply the same text. Depending on the builder program in use, some errors may be caused for different reasons, but the help text may be equally applicable. This way we can match different errors and supply the same extended help.
Use the , or buttons to maintain these matches.

There are a number of options associated with this text, namely how it is used to determine a match. We can use the following ways:

Edit Error Match
  • Contains the above
    This allows us to specify that the error text contains the text we supply here. This can be case sensitive or not depending on the use.

  • Equals the above
    This option does an exact match depending on the case setting. Generally, error strings tend to include variable information, so this match type may not be the most appropriate depending on the build program being used.

  • Matches pattern above
    This type of match which is undoubtedly the most powerful, uses standard DOS pattern matching to determine whether this string is a match or not. All of the standard DOS pattern matching rules apply here, and are explained in detail in the ParsePattern() autodoc.

The AmigaOS4SDK plugin allows us to use either GCC, VBCC or another external program as defaults to build the project. The next gadget allows us to specify which of those defaults the match above applies to. Obviously, different programs will have different errors, so this gadget will check to see which program we are using, and only use this entry if it matches the default builder.

The last section is the actual text that will be displayed when this entry is deemed a match for the error supplied. You can edit it as you like to elaborate on a particular aspect of this error. Just bear in mind that they are designed to fit into HelpHint windows, so try to keep it as short as possible while still being informative.

Share your changes
Sharing Error dictionary changes We regard this functionality as a major boost to inexperienced programmers in getting help for the more common errors while producing working source code. As a result, provided your computer has an active internet connection, you will be offered the opportunity to upload any changes you make to the CodeBench server, where these changes will be verified and added to the Error dictionary you are making the changes for. Once an updated Error dictionary is made available, you will be notified of this, and given the chance to download and install it.

We would like to encourage all CodeBench users to share any changes they make, as this will greatly improve the experience for all users, beginners and experienced alike.

Build Window shortcut
Extra Build Window toolbar buttons As can be seen here, an extra button is available on the Build window toolbar. It has been added by this plugin as a convenient shortcut in order to access the error dictionary editing.

The help texts in this dictionary are used to offer a HelpHint when the mouse pointer is hovered over an error in the Build window. These can help novice programmers greatly, especially if the dictionary is regularly maintained.

back to the top




Target Settings

The linker program takes all of the compiled parts and creates a complete executable program from them. In the case of the "gcc" compiler, the linker is an integral part of it, whereas other systems may have a separate linker program.

Previous versions of CodeBench only dealt with a single target per project. With version 0.47 onwards, we can now define multiple targets. What this means is that more than one complete program can be built from inside the same project. Below is a description of how to set up a default target using the new system.

Multiple targets can be useful when your project contains more than one finished executable, like perhaps a program and a preferences editor. Under the old system, you would need one project for each part, whereas now, both parts may be built from the same project. This makes it easier to switch between files in each part to compare code or functions, as the files that create each target will be present in the same project.

The target, once defined, is created from "Linker objects". A linker object is a pre-compiled binary from one of the source files in the project. When adding linker objects to the target, you should choose all the objects that are needed by the target. The linker objects are named the same as the source file that creates them, except they have a .o extension rather than .c or .cpp etc.

You may also add "Linker libs" to the target. Like linker objects, these are pre-compiled binaries which offer some external functionality required by the particular target being defined. You will need to add any linker libs to the project first in order to add them to the target from the list, as shown below.

In the above view, we can see that a target has been setup for our "Demo" project. The method for adding a new target and editing an existing target is the same. However, when creating a new project, the default target is defined by clicking on the button. This will open the target editing window, as follows:

  • Target Name
    This is required in order to name the created program. A path may be specified as well as a name if we want the created program to be put into a different place than the project directory specified above.

  • Variable Name
    The "Makefile" will use a variable to represent the name of the target. Normally, you shouldn't have to worry about the variable name, but in the event that it may clash with some other used variable, you can change it here. If your project outgrows the automatic makefile creation, this variable makes it easier to change the names of any targets in the makefile by only its name in one place.

  • Linker Name
    If you set the project to use the "GCC" compiler, then you won't need to change this option. Other compiler systems may use a different binary for linking than for compiling, so you can set its name (and path) here.

  • Linker Switches
    As with Compiler switches, the Linker switches are inserted into the makefile and passed to the linker at build time. More information about linker switches can be found in your compiler/linker documentation.

  • Build Automatically
    This option affects when this target will be built. If this option is enabled, then this target will be created when the makefile is called (provided the target requires building due to changes in the targets files). If this option is disabled, the target will only be built when the name of the target is called on the command line. It may also be selected in the Build Options requester from the Build window.

  • Strip target binary
    If you have elected to compile with debug symbols, then this option will allow you to create a "stripped" binary. This basically means that the finished program will have those debug symbols removed, which makes the program smaller and faster. In order for these debug symbols to be useful, the makefile will actually create two targets, one without symbols, and one with, which will be named <target name>.debug.

    If this option is disabled, only one target will be created and it will contain any debug symbols you may have specified in the Compiler Settings.

  • Create a static library
    Enabling this option changes the way your target is linked. Normally (without this option enabled) the linker will create a binary that can be executed. A "static library" is a different type of binary. It basically contains all the functions in your code but will not run as a standalone program. Instead, it needs to be linked with other code that can use the functions in this "library".

    Imagine your code handles everything required for dealing with some image format. When writing an image viewer, the viewer program could be linked with the library to handle those images rather than writing its own code. Once the two are linked together, the viewer can use the library function as though they were its own.

    The term "library" is slightly misleading in Amiga terms, as we normally imagine a library as a true shared library that resides in LIBS:. This precompiled library is actually an "archive", hence the ".a" file extension rather than ".library".


The following two lists work in identical ways, except the first list is used to manage linker objects (pre-compiled binaries for each file in the target) and the second to manage linker libraries which are to be statically linked with your target.

To add either type, simply click the button. If there are objects that can be added, a window will open showing you all of the available objects or libraries currently in the project. You may select all of those which are relevant to the current target. You may select multiple objects by holding down the shift key while making your selection.
In our example here, we only have one object in the project, and it has already been added to the only target, hence there is nothing to add.

however, should be treated with care. Removing objects from a target may well lead to a failure when trying to build that target.

If you have multiple items in either list, then it is possible to change the order that they appear in the makefile by using the arrow buttons. Items at the top of the list will always have priority when the target is being built.

The Linker Objects section also allows some other options, as follows:

Let us first discuss the button. This allows you to specify a different location for the object. Normally the object would be compiled alongside the accompanying source code file, this keeps things tidy.
There may be instances where, for example, you might want to use some code commonly among several projects.

A good example here is the CodeBench plugins. They are implemented as "libraries", and the code for the initialisation is used for each and every plugin. However, the resulting object is not identical from one plugin to another as the source is changed by "#include" files. As a result, by using this feature, we tell the makefile to use our "common" source file, with project specific includes, then put the resulting object in our projects directory, where it is kept separate from the rest of the plugin projects. Not only does this save some duplication, it also allows us to correct an issue in that one file and all projects using it will benefit from.

Lastly is the button. Here you can add and remove files that this object considers a "dependency".

What this basically means, just like the actual target, each object is also made up of other objects. Changes in any of the files listed here will cause that particular object to be remade. You can add or remove, but as was said earlier, it is easy to break the mechanism if you add or remove the wrong files.

We can see here that the Demo.o object is listing Demo.h as a dependency. This has been determined automatically by CodeBench itself. Usually, the automatic detection is enough to get the job done. If you feel you need to add extra dependents, you can do it here.

If it all goes wrong, or the build doesn't work as expected, you can back to using the automatic detection again.

This way of defining targets makes it possible to have all source files in one project for many different parts of the entire program and all of its components, without confusing the "Make" system.

back to the top




Environment Settings

These settings specify ways to affect the environment that we will be working in. There are three sections, the first deals with how the "Quick-Link" window is presented, the next affects how the editor interprets lines after which to automatically add or remove indentation in lines of text. The last section deals with various aspects of the actual code.

The "Quick-Link" window section

  • Identify bookmarks by this string
    This is the symbol string that can be embedded into the source file. When this sequence of characters is found, the text that comes after it is treated as a bookmark. This is useful for marking certain areas of files so that the location can be revisited quickly. The marker needs to be suitable as to not interfere with the general syntax of the source file.

  • Fold functions section
    This setting will allow the function section in the " Quick-Link" window to open in the collapsed state. This setting is relative to the current state of the associated section.

  • Fold bookmarks section
    This setting will allow the bookmarkssection in the "Quick-Link" window to open in the collapsed state. This setting is relative to the current state of the associated section.

  • Fold structures section
    This setting will allow the structures section in the "Quick-Link" window to open in the collapsed state. This setting is relative to the current state of the associated section.

  • Fold Switch/Case section
    This setting will allow the Switch/Case section in the "Quick-Link" window to open in the collapsed state. This setting is relative to the current state of the associated section.

  • Fold User defines
    This setting will allow the defines section in the "Quick-Link" window to open in the collapsed state. This setting is relative to the current state of the associated section.

  • Fold Enumerations
    This setting will allow the Enumerations section in the "Quick-Link" window to open in the collapsed state. This setting is relative to the current state of the associated section.

    Label colours can be changed to suit in the main Preferences editor.


back to the top




The Auto-Indentation section

This section is comprised of two lists of rules, the first for adding indentation and the second for removing indentation (often referred to as "outdents"). Both lists work in the same way, so both shall be described here in the same context.

Adding items can be done by clicking on the "Add Indent" or "Add Outdent" buttons to add to each list respectively. The resulting requester asks for a string of characters with which a match must be made for the appropriate action to be taken. Due to the highly versatile nature of programming languages, in order to simplify this process, the strings can include wildcard patterns exactly the same as used by AmigaDOS. This allows a level of flexibility which should meet the needs of even the most demanding rules. Most languages use braces to delimit sections of code, and the general programming standard is to indent the code inside the braces, which can now be automated. Adding a "{" to the indent list will cause the cursor to be shifted in by a certain amount of columns depending on the size of the "tab" set. A "tab" can either be a real tabulation character, or we may opt to insert a series of space characters instead, and is a case of user preference.

To add flexibility, a string like "case #?:" can also be added. This follows the wildcard convention and results in any line containing a "case" statement should automatically indent.

Items in either list can be removed by simply selecting them, and clicking the "Remove" button.

The Auto-Indentation settings in this section are applicable to the current project type, rather than the project itself. This means that the configuration of these lists will apply to all projects of the same type, and saves having to configure the indentation settings for every project. Both the Indentation type (spaces or TABs) and the tabulation width are applicable to the current project though. This is especially useful when sharing code with others via a repository or other common file server, and means that every one can submit code with a common style.

The width of the TAB (whether it be a real tabulation or spaces) defaults to 4 columns. This allows configuration of different tabulation width settings for each project for the sake of consistency.


back to the top




The Code section

  • Start Folding Label

  • End Folding Label
    These first two items specify what sections of text can be folded by telling the plugin how to recognise the start and end of "foldable" blocks. You shouldn't normally need to change these unless you require something very bespoke.
    Note that changing both of these markers to be the same will have unexpected results, and is not recommended.

  • Edit New File Header Edit New File Header
    When you ask CodeBench to create a new file for you, it includes a section of text at the top with some default information pre-filled in. By clicking the button, you can edit just what information is included in that header.

    As you can see from the default header shown here, the most popular information has been included already. The list on the right hand side includes all of the "Cookies" that can be inserted into the file header for you.

    Simply double-click any entry in the list to have it inserted into the text at the current cursor location.

    Once you have saved it, this custom header will be used whenever you create a new file for use in this project.

  • Edit Constructs
    You may envoke the construct editor from here. More information on code constructs is available from the editor page.


back to the top




Help Settings

These settings allow customization of the "Help-as-you-Type" system.


The "Help-As-You-Type" section

  • Enable "Help-as-you-Type"
    Naturally, this option turns this feature on or off as required.

  • Case-Sensitive
    When searching for entries, the case of the letters is dependent on this setting. While ignoring case can make finding matches easier, it can also generate lots of matches. Use wisely.

  • Show function prototypes
    The list of functions can optionally contain the full prototype, and will be inserted into the text if a selection is made.

  • Include library interface
    Any system functions that match can include the interface of the library they belong in added to it. This option only relates to the system functions in the dictionary.

  • Show vague matches
    Enabling this option will lead to a lot of matches being shown, as the check uses a much wider system for finding matches.

  • The Display section
    As coding projects get larger and larger, the more data the "Help-As-You-Type" system has to deal with. Naturally, this will take longer and longer as the amount of data increases. In order to try and speed things up, you can select here what types of data to try and show in the "Help-As-You-Type" window. By default, each file is scanned for all types as possible matches.By disabling the less interesting types of data, this can significantly speed up the process.

    Obviously, if you turn them all off, then nothing will be shown.



The Dictionary section Edit DictionaryPaths

  • Paths...
    When building the dictionary, the system looks in certain places for files to use to get data suitable for inclusion. This option allows you to add or remove paths that will be searched in for files.
    The defaults are applicable to a standard AmigaOS SDK installation. If you have installed extra development components, then extra directories may need to be checked, and they can be added here.

  • Rebuild...
    The Rebuild button will start to scan the installed system and build the dictionary from scratch. It is not recommended to interrupt this process, and it may take a while depending on how many files it has to check. A confirmation requester will be displayed if an existing dictionary is going to be overwritten as any custom additions that may have made could be lost, which may include any "Lextra"s that may have been added.

    More information about the dictionaries and their usage can be found on the Editor help page.



The Lextras section

The button allows lexicon "extras" to be added to the current dictionary without the need to fully rebuild it. "Lextra"s are simply XML files which contain a set of help definitions that are applicable to a particular library or shared object. Examples of this might be the SDL libraries or the AmiDark Engine, and would contain detailed help for each command or function within it. A file requester will appear after selecting this option asking for the path to the .lextra file, and once loaded it will start the process of adding the contents of it into the dictionary. It is advisable to keep copies of any "lextra" files that may be downloaded, as these will probably need to be added again in the event that the dictionary is rebuilt for any reason.


back to the top




Editor Popup Menu

Extra File Menu Options The AmigaOS4SDK project type adds some extra items into the Editor popup menu. The extra items are in the "File" menu, and are as follows:

  • Source Code Formatting
    The use of this menuitem is covered in the Assistants section.

  • Generate prototype header file
    This option is a direct mirror of the option found in the Project popup menu.
    It is covered in detail in the Assistants section.

  • View preprocessed source
    This option is a direct mirror of the option found in the Project popup menu.
    It is covered in detail in the Assistants section.

  • View compiled source
    This option is covered in the Assistants section.

  • The last two options allow synchronising with the repository.
    More details are available in the Synchronisation section.

Other items in this menu are covered in the Editor section.

back to the top




Project List Popup Menu

Extra File Menu Options The AmigaOS4SDK project type also adds some extra items into the popup menu from the project list when invoked over a file item. The extra menus are in the "File" section, and are as follows:

  • Custom Compile Switches
    This option, when selected, will present a requester where custom compile switches may be entered. Sometimes this is necessary when compiling for AltiVec or other such instances where specific compiler switches might be required for a particular file. When the requester opens, the default compiler switches will be shown, and these are the general project wide ones entered into the Project settings. These may be changed these to suit the particular requirements. Please note that entering an empty string sets the switches back to their defaults.

  • Ignored in Makefile
    Some users, especially those that are just starting out with C coding, may want to load files into the project to use as reference material. While these files are handy to have around, they will cause problems when it comes to building the project. For this reason, this menu item allows the file the menu was invoked over to be excluded from being part of the build process. Basically this means that when a new makefile is created, any files that are "ignored" will not be added to it. This means the project can be built normally with reference material loaded as part of the project without interference.

  • View preprocessed source
    This feature is covered in the Assistant section.

  • Set Object location...
    This feature is covered in detail here.

  • Generate prototype header file
    This feature is covered in the Assistant section.

back to the top




Built-in Assistants

Each project type adds some specific built-in assistants. Probably the most visual of these would be the Help-As-You-Type system.
Some of these assistants are interactive (the user can tell the assistant how to perform its function), some just carry out their duties quietly in the background.

Listed below are the assistants offered by the AmigaOS4SDK project plugin:

  • Beautify Source Wizard Beautify Wizard
    An interactive wizard that allows the user to change the source code styling.

    This is available from the main
    Editor menu and also from the Editors popup menu as "Source Code Formatting".

    There are a number of options that allow the source code to be changed to suit various styles. All of the options are explained in greater detail by use of "help hints" which are shown by hovering the mouse over the gadget of interest.
    Possible operations are grouped by type in the list on the left. Selecting any of these will reveal available options for each category. You can set up as many options as you want, and the operations will be carried out when the button is pressed. The progress indicator will show how the wizard is doing.

    Once finished, you may close the wizard and continue working, or you can select different options and format the source code again.

  • File Name Wizard
    A non-interactive assistant that reacts when the user changes the name of a file in the project.

    So, you have decided that one or more of the files in your project needs to be changed to better reflect the purpose of the code inside. Under normal circumstances, changing the name of a file is not as straight-forward as you might think. It requires, at least, a change in the makefile, so that other files that reference it know the name has changed.
    This is especially relevant in the case of "include" files, as they can be referenced from many other source files, as well as in the makefile.

    When the file is renamed, this wizard will silently go through each file in the project and check to see if any of them reference the file being renamed. If it finds a reference (perhaps by an #include statement), then it will change it to the new name. It will also make sure that the makefile is rebuilt (providing this option is enabled in the Project settings) so as to update it with this new file name.
    If you are using an existing makefile rather than an automatic one, you will need to edit it and change any references to the old file.

  • Proto Wizard
    A source file can contain many functions which may need to be called from other source files. The usual practice is to create a file containing all of the functions "prototypes" which can be included by other sources. This menu option can scan the source file, and create a header file listing all the functions it finds.

    The prototype file will be named "<filename>_protos.h" and will be displayed in the editor for you.

  • Preprocessed Source Wizard
    Compilers tend to create "intermediate" files when compiling. This basically means that all the data from include files required by the source file, is pulled in and preprocessor directives are expanded etc. By selecting this menu item, you can allow the compiler to create an intermediate file for this source and view it in the editor. This can be useful when trying to find any compiler errors where missing data from include files is causing a failure.

  • Compiled Source Wizard
    During building, the source files within the project are converted from readable text into assembly source code, ready to be compiled into units which are "linked" into the final program.

    By using this wizard, the assembly source file will be generated and displayed in the editor for you. This can be useful to see how, for example, optimisation settings effect the code, and can potentially elliminate bugs.

  • Clean Object Wizard
    When the project is building, this is done asynchronously, meaning you can continue working while this happens. Because of this, it is possible that changes made to source files may not get picked up by the compiler.

    To avoid this, when the source file is saved, the corresponding compiler object is deleted. This may result in a compiler error about an object that could not be located. To fix this, simply build the project again, and the changed source will be rebuilt, and the missing object recreated.

    This ensures that any changes are reflected into the finished program.

back to the top

Valid XHTML 1.0 Transitional This is a W3C checked and compliant webpage.