Overview Installation Getting Started Detailed View Plugins Preferences and Settings Utilities Program Menus Credits and Thanks Licence
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 " Dependency ", 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.

 

Project Tabs

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.

 

File List

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:

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

 

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

 

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

 

  • Other files - 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

 

 

Project Support

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 " Project Notes" 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

 

 

Open Files

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 build script, 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 Source files category selected (or any files in it), this button would, in our example project, add any file that has a .c or .cpp file extension. The Header files category would add, again in our example, any files with a .h or .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 section.

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

 

 

Chaining Projects

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 " Project Chain". 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 this: 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 too.
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 makefile. for use with the AmigaOS4SDK, the program that actually takes the source code and creates the finished binary file is called "Make", 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 Information window. This can be advantageous if the makefile has extra rules listed in it over what the default CodeBench script would contain. Make" 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.

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 for you.

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

back to the top