Project List Quick Reference
The project window forms the hub of the project management. It lists all of the files of the project,
and allows a quick and easy way to load files into the editor and gives a simple way to add or remove
files from the project.
The project window will track the status of the build scripts used to
create the finished program. When adding or removing files from the project, the
build script will be internally marked as "Stale",
basically meaning that the script no longer correctly reflects the files which are part of the project,
and you will be notified that the script needs remaking.
The build script will also take into consideration that the source files in the project may depend on
the status of other files. This is known as "
", and is currently set internally to 3 levels deep.
What this means is that if a source file requires information from a header file, and that header file
is changed, the build script will force the relevant source to be rebuilt automatically.
Not all project types require a build script, so the above should be read in conjunction with the project
type you are using.
Each project loaded will have an associated tab. When the project is modified in any way, and requires
saving back to disk (as above), a small red flag will appear on the tab for that project. This serves
to highlight the fact that the project has been changed and needs to be saved to disk in order to avoid
loosing those changes.
Moving down the window, the next area is the main list, which is the center of information for the
project. The list is organized into sections which are applicable to the type of project you are
working on. In our example you can see we have header files,
source files, linker objects, and other.
In an Arexx project, for example, these categories would be named differently, but for our example
( an ANSI C project), the categories are as follows:
- These are text files containing definitions of variables and structures which are "included"
by source files. You may place any header files in here that you may need, and by doing so it makes it
easy for you to reference or edit them. They will not be automatically included when the project is built,
you will still need to use the correct directive to achieve that. Editing or viewing these files is a
simple matter of double clicking the name and it will open in the editor.
- This is where you place the files that contain the source that makes up your program. All the
files in this category will be placed into the build script (if the project type requires one)
in the order that they are listed. You can add files as needed, or remove them, but by doing so
you may be affecting the build script. If the script is considered to be out of date because
files in this category have changed, you will be notified, unless you have the option enabled to
create a new build automatically when required. Again, a double click on the name
will open it in the editor for you.
- ANSI C and C++ projects will create objects when the program is compiled, but this category is
not designed for those, you should place here any external objects (also known as libraries) that
your program may need. Usually, compiling a program against a library is done by including the
library name in the linker command line, but you may also add libraries into this category and
have the project built with these libraries included. These objects (in the context of C/C++) are
pre-compiled sections of code that your program may use as though it was part of the main source.
An example of this is the libauto library that is present in the AmigaOS4 SDK. You will not be able
to open any of these files in the editor as they are deemed to be not editable.
- And finally, if it doesn't fit into any of the above category, it goes here. This section is used
for things like documents or other miscellaneous files. Again, double-clicking these files shows
them in the editor.
back to the top
These main categories, as well as any subcategories that may have been added, can be "folded", and this
state is saved when the project is saved or snapshot.
Whilst managing the files that form the project, the user also has a dedicated file attached to the
project that may be used as a "ScratchPad". The purpose of this file is to give
the user a convenient place to write all kinds of notes or text that apply to the particular project.
You may use this file for anything you like as it does not actually form part of the project,
ie: it is not compiled with the other source files. A typical use is to write down lists of
things to do, or bugs to fix etc. You may access this file, which is called "
from the Project/Open project notes file menu item. This file
is created automatically, so creating it manually is not necessary. The default file header includes
information about the project, and some predefined sections ready for use.
back to the top
Any files that may be open in the editor are reflected in the main list. It will change the background
colour of the item to white to indicate that the file is open. Double clicking a file that is open will
not open in the editor again, (multiple views of the same file are not supported yet) but it will bring
the editor to the front for you. If you have lots of files open, this saves you from having to find the
correct tab to select.
back to the top
Project Window buttons
Let us now move on to the vertical toolbar and the function of each button. For convenience, most of the
toolbar buttons are mirrored in the Project menus.
This button allows you to "SnapShot" the project. What that means is that not only
does this save the project, but the order of the files in the list is saved too. On top of that, any
files that are flagged as open are saved and the cursor position recorded. By snapshot'ing the project
you can reload it just as it was when you left it, right down to which file you were currently working
on and which line. This functionality is mirrored by the Save Project
button in the main toolbar. This also applies to the Project Notes file and the
if either (or both) are open at the time you snapshot the project, they will be automatically opened next
time you load the project.
This button allows you to easily perform a project-wide search. This will cause the Search window to open
with the "scope" defaulted to the entire project.
More information on the search scope and operation can be found here.
This button allows you to add files to the project. The type of file added to the project is related
to which item, or category, is currently selected. Files in the list are categorized by the type
specified in the project defaults. For example, if you have the
category selected (or any files in it), this button would, in our example project, add any file that
has a .c or
extension. The Header files category would add, again
in our example, any files with a
.hpp extension. If no categories
or files are selected, then this button will not be available, and the "
Add Files" menu should be used instead. It is also possible
to add multiple files and these would be sorted automatically, which is useful in the event of creating
a project from an existing program where all the source and header files already exist. More information
on the addition of files can be found in the Getting Started
This button removes a file from the list. Select the file to be removed, and this button will become
enabled. Removing files from a project may prompt you to create a new build script if one is required
for the project type.
These two buttons allow the order in which the files are shown in there respective categories to be
reorganized. The reasons for this are two fold:
First, and foremost, ordering source files in the list affects the order in which they are listed in
the build script or the order in which they are compiled. In large projects, where there may be lots
of source files, this can be advantageous to ensure that changed files are built first. If these files
have errors then they will be addressed at the start of the build, rather than having to wait for
source files that are known to be free of faults to build first. This is only applicable if you are
creating a build script each time it is required. The build order is unaffected if you have the script
creation turned off via the project settings as the order listed in the script being used is honored.
When the project is loaded back in, the last saved order will be used. Files at the top of the list will be
added to the editor before the files at the bottom of the list, so by changing the order in the project list,
you change the order in the editor.
back to the top
Right Button Menus (popup)
The project window features a context sensitive (popup) menu which is accessed by pressing the right mouse
button while over the list of files in the project. Items in the menu may not always be available, or even
present, depending on the context of the menu, but all the available options are covered here for completeness.
Some items may differ depending on the project type currently being worked on.
The first 5 items in the menu are the same as their counterparts in the main menus
and are here for convenience to access the more commonly used features.
The "File" menu allows access to functions which are relevant to the item
selected in the list. This includes removing the selected file, and gaining the file attributes.
External change notifications can also be turned on and off for the
file from here too. There is also an option to open the file with another suitable program by selecting the
"Open with..." menu item. Programs selected from here will be remembered
on a project type basis, and will be shown in the menu to save having to locate them each time.
The "Jump to" menu will list all of the functions it finds in the selected
file. This allows a highly convenient way to jump to a function in a file which is currently shown in the
"Quick-Link" window. You can specify whether the just function name or
the function prototype is shown here from the Preferences window.
If an AmigaGuide file is selected, the
"Open in MultiView..." item will be available. This will load the selected
file into MultiView for testing AmigaGuide
documents after editing.
The "Add to category" item will be available when a category was previously
selected, and allows you to add files to it. This has the same function as the
"Add file..." item in the main menus and the
button. You can also
double-click a category item to open the requester for adding files of the applicable type.
The "Remove SubCategory" item will be available if you have previously
selected a subcategory item, and this will remove the category from the list. If the subcategory has files
within it, you will offered the choice between removing those files as well, or pushing them into the
"parent" category, effectively moving
them up a level. This only works with subcategories, you cannot remove a main category for obvious reasons.
The "Add SubCategory" item will be available if you select a category item
in the list. You may enter the name for the sub-category in the subsequent requester and the new sub category
will be added into the correct section for you. You may then shift files in the main category into this new one
by either using the up and down buttons, or by dragging the item with the mouse. Here
you can see we are dragging a source file into a new category we have created, and a green line shows you
whereabouts in the list the item will be inserted when dropped.
back to the top
A particular software product may well be comprised of more than one component, and it is quite common for each
component to have its own project. A good example would be a program that uses a custom shared library, both of
which have their own projects. When working on the program project, it might be desirable to be able to load the
library project at the same time, so that work can continue on both projects simultaneously.
Luckily, CodeBench allows the linking of projects together to form a "
Basically this involves telling CodeBench that the current project should also be linked to other open projects.
Select the master project (the program in our above example) by clicking the corresponding project tab,
and select the "Link..." menu. A window will open that looks like so:
As you can see, we are using CodeBench itself as an example here. We have selected the
"Link..." menu with CodeBench as the current project, and we also have the
library and the AmigaOS4SDK plugin projects open as well.
Any projects that are already linked will have their checkbox ticked by default to show that we are already
linking these projects together (this also includes linked projects that are NOT already open). If we were to
close this window, and open another project, this window would show the new project but it would not be ticked
because it is not yet linked.
It is now a very simple operation to select the projects which are to be linked
to the master (shown in red at the top of the list). Clicking the "OK"
button will save these changes to the project, whereas closing the window with the close gadget will cancel any
changes you may have made. When the master project is reloaded any linked projects will also be loaded ready for
editing. Linking projects like this only applies in one direction. That means that only the master project contains
the chain. If we were to open the library or the plugin project separately, it would not automatically load any other
projects. This makes the linking of projects quite versatile, meaning that some projects can be linked to others
without having the linkage apply in reverse. Naturally, if you wanted the linkage to apply to the library, simply
make it the current project and link as described above.
A word of warning when linking projects together: It can take a while to load a large project chain if each
project is of a reasonable size, so either be prepared for that, or think wisely about what projects to chain together.
This feature is not available in the free-licence versions.
back to the top
The Build script
The build script is an integral part of creating a finished project of certain types.
In our example project which is based on a C/C++ type, the build script is called a
for use with the AmigaOS4SDK, the program that actually takes the source code and creates
the finished binary file is called
and it requires a "makefile" to instruct it what to do in order to build the project. This makefile has specific
instructions listed in it, and these instructions include listing out all the source code files that are
required to create the finished program.
Changes to the source files (ie: removing or adding) means that the makefile needs to be changed to reflect
these changes. By selecting the project option of creating a new build script each time the project is compiled,
it rewrites the script and includes the changes that may have been made, including the order in which the
various files are addressed.
If you have created a project from a program that already has such a build script, the option to turn off
the creation of the script can be done in the Project Settings window.
This can be advantageous if the makefile has extra rules listed in it over what the default CodeBench
script would contain.
can use these scripts to do much more than simply build the program, it can contain rules to create
documentation, or create installation archives, for example, and by opting to let CodeBench create a new
script, these changes may be lost. The ability to be able to tailor the buildscript for each project
individually is beyond the scope of the automatic script creation, and there are plenty of tutorials on
makefile tweaking available on the internet. However, some project types may let you configure more options
than others, so it is wise to check the Project Settings for the project
type you are working with to see just what can be achieved.
You have the option to call the build script any name you like, so it may be an idea to choose a different
name from the default script already supplied, that way the original would always be saved intact.
If the project type requires a build script, you have quick access to it from the
Project/Build/Edit Build Script menu item. Selecting this will load the
script into the editor ready for you. If you want even easier access to the build script, you can add it
to the project the same way as adding any other file, and the script will be added in the
Other category. Then you only need to double-click its name in the list to have it open
back to the top
The Search Function
As previously mentioned, the Search system is context aware, and will react differently depending on where
it has been launched from. Initiating a Search from the Project Window will search all files which are
currently open in the editor for the specified criteria. More information on the Search system is available
back to the top