Project List Quick Reference

 
Project Window

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 losing 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 files. 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 does not fit into any of the above categories, 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.

    It is also possible to add files to your project that may be supported by other installed plugins. For example, you may have some Arexx scripts to accompany the program you are developing and want to add them to the project for easy reference and editing. Again, these will be put into this category, but now, the Arexx plugin will be used to "handle" these files. What this means is that you will be able to use the Quick-Link window to jump to procedures and bookmarks within Arexx scripts, just as though they were source files. The plugins supplied are not just used to master projects, but also individual files as well, making using different types of files within one project more consistent.

Top Tip
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.

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.

Project Snapshot Button

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.

 

Find in 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.

Project Add File

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.

Remove Project File

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.

 

Move File Up
Move File Down


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 are always applicable to the item in the project list that was under the mouse pointer when the popup was invoked. Some items 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.

Project popup menu The first item in the menu offers Project specific functions, and are the same as their counterparts in the main menus and are here for convenience to access the more commonly used features.

Next comes the "File" menu, which offers various functions all applicable to the file. The menu shown here has been created with a C/C++ project. Other project types will show different functions, all relevant to the type of project, or file, being selected. In other words, opening this menu over a C source file will offer different options than if opened over an Arexx script, or PHP file.
The description below is for a C/C++ file, but the options for other file types should be quite obvious as well, We shall cover the options here, in detail, for the sake of completeness.

  • Rename file...
    Opens a file requester and prompts you for the new name (and optional path) to the new file. The name, and path, will be applied to the project, and any required buildscript.

  • Remove file
    This item will remove the applicable file from the project. While it will no longer be part of the project, it is not deleted or moved on disk, so it may be added to another project as you please.

  • Duplicate file...
    This item works in a similar fashion to "Rename file...", except it leaves the original file intact. This allows you to copy the file with a new name either into the same directory, or a different one.

  • Touch file
    "Touching" a file means to set the date and time of the file on the disk to the current timestamp. This can be useful for automated build systems that use the timestamp of the file to check if the source needs to be built.

  • Delete file...
    As the name suggests, this item will permanently delete the file from disk. As a result, it is obviously removed from the project as well.

  • Hide foldable sections for this file
    As we have discovered in the Editor section, CodeBench is able to hide sections of text. If we do not want to use this feature for a particular file, this item will disable that feature on a file-by-file basis. This information is saved along with the project so it may be restored when the project is reloaded. The same feature is mirrored in the bottom toolbar of the Editor window.

  • Attributes...
    File Attributes This is an easy way to view certain properties of the file in question. Apart from the full path and datestamp, it will tell you which plugin is currently handling this file. You may also set or clear any protection bits you feel applicable.
  • Notifications
    CodeBench can monitor files that are part of the project for changes by external programs. This ensures that the files are always up-to-date, and any changes to files from external programs will prompt you to reload the file, or it will be reloaded automatically. You may disable or enable these "notifications" from this menu item.
  • Scan file for "Quick-Links" when loading
    When loading a project, each file is scanned for anything that may be displayed within the Quick-Link window. This includes things like Functions, bookmarks etc. This can slow down the loading of a project, especially on projects with larger files in it. This option can toggle the scanning the file when the project is being loaded. If you disable it, there is no way for CodeBench to know what the file contains, so searching for functions, or the Help-As-You-Type window may be incomplete. It may be useful, however, for larger files that do not contain anything that may be presented in the Quick-Link window.
  • Scan file for "Quick-Links" upon changes
    Similar to the option above, this will toggle the scanning of the file when changes are made. The same caveats apply as those above.
  • Custom Compile Switches
    This option is added by the C/C++ plugin, and allows you to set the compiler switches to something other than the project defaults. Some projects of this type may need certain files to be compiled in different ways (like Altivec support, or dynamic linking), so this option allows you to set the compiler switches specifically for this file.
  • Ignored in Makefile
    Again, offered by the C/C++ plugin, this option will toggle whether the file is to be added to the Makefile as a compiler "rule" or not. Many novice or beginner programmers tend to have files opened showing examples of code they wish to modify or use. While this is a great idea, under normal circumstances, all source files will be added to the Makefile. This item allows you to exclude the file as though it was not in the project.
  • View preprocessed source...
    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.
  • Generate prototype header file
    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.
  • Open with...
    This item is accompanied by child items, each one listing an application that you might want to open the selected file with. Of course, this scope is far too wide to be fully automated, but a few defaults are included, but you can always add your own. Simply select the Choose... menu to select the application to want from a file requester. Alternatively, you can select the Edit... menu, and you will see an editor allowing you to manipulate the applications already added to the menus.

Lastly, is the Jump to item. This 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 Project Add Filebutton. 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.

Dragging Project File 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 so:

Link Projects 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 "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 Settings 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. 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 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

 

 

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