AmigaOS4SDK 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 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 of the AmigaOS4SDK project type.

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

  • Synchronize plugin name
    CodeBench currently includes plugins for CVS and SVN use. These are by no means complete, and as such a developer kit and documentation is included to allow further development of these 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. Manual synchronising is done via the " Synchronise" menu item.

  • 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 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.

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 centric around a script called a "makefile". These options affect that script, and are as follows:

 

  • Create Makefile
    This option enables the creation of the makefile. Automatic script creation happens when the Build button is clicked if the script is deemed to be "stale". This usually occurs when changes to the project affect 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 script, 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.


  • 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 Contents. Certain extra aspects of the script can be configured, as follows:

  • Configure Includes

    Configure makefile 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 included here. Select New to specify a file to be included, or select one in the list to edit its name and/or path. These included files will be added near the top of the created makefile for you.

  • 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 New will allow you to set up a new variable and define its contents. You may select an item in the list and click Edit (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 make 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 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. Creating a New rule, Deleting a rule that is no longer required, or changing the order they will be added to the makefile by using the Up and Down buttons is all possible.

    Probably the most important button is the Edit 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 name of the rule 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.

    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.

    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:
    AmigaOS4SDK_locale.h: AmigaOS4SDK.cd
    catcomp AmigaOS4SDK.cd CFILE AmigaOS4SDK_locale.h NOCODE NOARRAY
    catcomp AmigaOS4SDK.cd CTFILE AmigaOS4SDK_locale.ct


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

    • Before building the target
      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 program.

    • After building the target
      This option will include this rule in the "all-after" rule. This means it will be executed automatically after the program 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", "NativeVBCC" 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.

  • 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.

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 building of the project can have some extended help to explain why such errors happen. In the case of the AmigaOS4SDK project type above, the project settings allow you to edit or add to this dictionary. The AmigaOS4SDK 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 in it. 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 "Edit" (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 "return" or "enter". 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.

The entries in this editor are also used for the HelpHints in the build window. After building, any errors in the build window can be explained by hovering the mouse over the line of interest. The help hint will show you the match found for this error. 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).

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

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 match the error from 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 "Add", "Edit" or "Remove" 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.

We regard this functionality as a major boost to inexperienced programmers in getting help for the more common errors while producing working source code. We would like our users to share their additions to this dictionary with other users via the CodeBench forums, and hope to make this a great resource to aid new programmers in their endeavours.

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 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, 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 procedures, 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 New 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.

  • 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 programs, one without symbols, and one with, which will be named <target name>.debug.

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

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 Add button. 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.

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

back to the top

 

 

Environment

These settings specify ways to affect the environment that we will be working in. There are two sections, the first deals with how the "Quick-Link" window is presented, and the second affects how the editor interprets lines after which to automatically add or remove indentation in lines of text.

The Quick-Link section

  • Identify user labels ...
    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 label. 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 function 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 label section
    This setting will allow the label 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 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.

 

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 ending with 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.

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

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

  • 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 "Add Lextra..." 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.

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.

back to the top

 

 

Project List Popup Menu

Extra File Menu Options The AmigaOS4SDK project type adds some extra items into the popup menu from the project list when invoked over a file. The extra items are in the "File" menu, 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.

back to the top

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