The Datafile PD-CD 4

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsf / imagine / !Imagine / !Help < prev next >

Wrap

Text File | 1995-12-24 | 19.8 KB | 640 lines

IIIII M M AAA GGG IIIII N N EEEEE I MM MM A A G I NN N E I M M M AAAAA G GG I N N N EEEEE I M M A A G G I N NN E IIIII M M A A GGG IIIII N N EEEEE Project Management Utility Imagine is S H A R E W A R E (c) 1995 R.F.Windley & The Really Small Software Company Version 1.10 (26th November 1995) If you continue to use it for more than 28 days then you must send £10.00 to the address at the end of this file. This entitles you to keep using the package after this period. Cheques drawn against a UK bank are preferred and should be made payable to 'R.F.Windley'. Failing this £10 cash will be accepted. Note that this software is supplied 'as is'. The author takes no responsibility for any problems or data loss resulting from the use or misuse of this software. Requirements In order to use Imagine the following is required: RISC OS 3.1 or above 2M memory or above A compiler of some sort (eg gcc/Acorn C/C++) A linker of some sort (eg link/drlink) BorderUtil module if RISC OS 3.1 In addition the following are recommended: An ALF generator of some sort (eg libfile/makealf) DDEUtils module A template editor (eg FormEd/TemplEd) Programmers Reference Manuals Note that if you are not using DDEUtils then any generated command lines must be kept under 256 characters. Also, the CSD will be altered from time to time and only one project can be built at once. See the section on Include paths for a way of keeping command line lengths to a minimum. Software used The following was used in the creation of Imagine: DeskLib Zap TemplEd Acorn Desktop C Release 4 & 5 Make link/drlink libfile What is Imagine? There has been a lot of criticism of the quality of programming tools available for RISC OS. Imagine has been written in response to some of these criticisms and although it does not pretend to be the ultimate application generation tool, it is hoped that it goes some way towards making programs easier to write. The Make utility supplied with Desktop C allows the programmer to specify the code and libraries that make up a project. Imagine also allows the resources that make up an application to be specified and maintained. All code and resources are accessed through Imagine so there is no more searching through directories to find a piece of code. Imagine splits projects into different types. Applications are normally RISC OS WIMP applications. As well as source code they have a number of resources associated with them such as a Messages file or window Templates. Libraries are pieces of code that can be grouped together into useful blocks. They are not tied to any one application and may be used many times. For example, you might have a dates library that is used to manipulate dates in a number of different ways. Utilities are like applications except they don't have any resources. They are programs that will most likely be invoked from the command line. An example of a utility is the C compiler. Classes are C++ specific. They may perhaps be thought of as an object oriented version of libraries. Using the dates example above, you would have a date object on which a number of actions could be performed. Note that it is assumed that the reader is familiar with developing applications on the RISC OS platform. As it is necessary for you to have a compiler and linker I do not believe this is an unreasonable assumption. Getting started To load Imagine simply double click on the !Imagine icon in the directory viewer. After a few seconds Imagine will load. Note that if you do not have the DDEutils module you must first edit the !Run file. Simply comment (|) out the first RMEnsure that mentions DDEUtils. Imagine will then load. The icon bar menu Clicking Menu over the icon bar icon displays the icon bar menu. This allows access to the different parts of Imagine. Info Choosing the Info option displays a standard About this program information box. Open Choosing this item leads to the Open submenu. This shows the way in which Imagine separates different types of project. Selecting one of these options will display a list of projects that fall into that category. Preferences This item leads to another submenu. This menu allows the setup of Imagine to be changed and new languages to be supported. Quit The final item on the menu causes Imagine to finish. Managing Projects Much of the functionality of Imagine is the same whatever type of project you are writing. Unless otherwise specified the following applies equally to all project types. Choosing Open->Applications from the icon bar menu produces a project list window. This lists all the projects that are defined for this project type. In order to perform any operation on a project it must be highlighted by clicking Select or Adjust. Clicking Adjust will add to the selection of projects currently highlighted. Clicking one of buttons down the right of the window will then perform the action specified. It is also possible to double click on a project. This will produce the code window and, for applications, the resources window. Application resources Clicking on the Resources button in the Applications window will display the resources for the currently highlighted application. This button does not appear for Libraries, Utilities or Classes. Editing resources Application resources can be edited in a couple of different ways. Either highlight the resource or resources that you want to edit and click on the Edit button or double click on the resource. It will be loaded into the relevant editor for you. Creating resources To create a new resource click on the Create button. In order to create a resource it must already have been defined as a valid resource type. To get a list of valid resource types click on the help menu icon. Choose the resource type that you want and click on the Create button. The resource will appear in the resource window. Deleting resources Resources can be deleted from an application by highlighting them and clicking on the Delete button. You will be prompted to confirm this is what you wanted to do. Project code Choosing the Code button in the project list window will display the Project code window. This window allows all of the code for a project to be managed. The top part of the window shows all of the code for a project. This can be a mixture of different languages such as C, C++ or assembler. In fact, as long as the object file produced by the relevant compiler follows standards, any compiled language can be used. The bottom part of the window shows the header files that form part of the project. Double clicking on a code name or header file name will load it into a text editor ready for you to edit. There are a number of buttons down the side which work as follows: Create Clicking on the Create button produces a small dialogue which lets you create a new piece of source code. The Name field must contain a valid filename. Note that it is possible to type up to 32 characters into this field in anticipation of filing system improvements. It is the responsibility of the programmer to ensure that the name entered is compatible with the underlying file system. The Type field can be filled in by clicking on the help menu icon which will produce a list of valid code types. Clicking on the Create button will create the new code. A default template will be supplied with some details filled in. Clicking the Cancel button will close the window. It is possible to 'create' code in another way. If you already have a piece of source code that you want to include in your project it can simply be dragged to this window. Imagine will attempt to discover the type of this source code. If the source code is in a directory that matches a code type Imagine knows about such as c, cc or s then the code will be typed according to this. Alternatively, if the code has a suffix such as _c, _cc, /c or /cc then the code will be typed according to this. This can be useful if the code is being copied from another system such as DOS or Unix which rely heavily on file suffixes. When code is created in this way a copy of the original file will be taken and placed in the project source directory. If you wish to share source across a number of different projects you should create a library. Delete To delete some code from a project it must first be highlighted by clicking with Select or Adjust. Clicking on the Delete button will, after prompting you, delete the code. Note that this not only deletes the code entry from the window but also deletes the underlying file. Edit This is another way of editing code. Highlight the code to be edited and click on the Edit button to load it into a text editor. Make Make will attempt to compile and link your project for you. If there are any errors the process will stop (although this can be configured differently). While the project is being made an output window will show how far Imagine has got. The process can be paused by clicking on the Pause button, which then changes to a Resume button, or stopped completely by clicking on Abort. Clicking Abort will produce a dialogue box that either allows you to terminate the process immediately, or when it is convenient for Imagine. Terminating immediately can be dangerous in that files can be left open. It is recommend that this is not used unless absolutely necessary. Compile This will only compile the highlighted code and will not link the project. An output window similar to that for Make is displayed. Touch Sometimes it is necessary to force code to be recompiled. If you have to do this the Touch facility can be used. Highlight the code to be 'touched' and click on the Touch button. This will cause Imagine to believe the code has recently been edited and therefore needs recompiling. Flags When compiling there are a number of different flags that can be passed to a compiler. These include options for debugging information and for certain levels of optimisation. The Flags window allows you to specify which flags should be used. The Type field allows you to specify which type of source code the flags are being set for. To select a different code type click the help menu icon. Clicking on OK will store the selections. For details of what the different flags do you are referred to the documentation that came with the relevant compiler. All Some operations need to be carried out on all of the source code. To select each piece of code individually would be tiresome so clicking the All button will select all the the code in one go. Project setup Clicking the Setup button on the project list window produces the Project setup window. This allows some of the details about a project to be altered. The Description field can contain a brief description of what the project does. Libraries Clicking on the Libraries button produces the Libraries window. This is a list of libraries that will be linked into the project. To add a library to the list simply drag the object file to this window. It can be useful to have entries that rely on system variables to form part of the pathname of the form <SystemVariablePathname>.o.library instead of the whole pathname being specified. It is possible to edit the entry by double clicking on it. When the library entry has been edited, click on OK to store the changed. Note that only Utilities and Applications have the Libraries button. Flags Clicking this button produces a dialogue box that allows the flags passed to the linker to be specified. For details of what the different flags do you are referred to the documentation that came with the relevant linker. Include The window produced by clicking on the Include button behaves in a similar way to the Libraries window. The difference being that this window allows you to specify which paths are searched for include files. To add a new path drag the relevant directory to this window. Note that if you are not using DDEUtils then you should keep include paths to a minimum length. One way to do this is to use an environment variable to hold the pathname rather than including the whole pathname. For example: DeskLib: instead of ADFS::HardDisc4.$.Develop.Libraries.!DeskLib This is also good practice in case, in the above example, DeskLib should be moved. Extracting and moving a project Sometimes it is necessary to relocate a project. Simply moving the project directory will not work as Imagine will no longer know where to find the project. Instead, dragging the project icon with Adjust to a directory display will cause the entire project to be moved there. Note that it is important to check that there is enough space in the new location or the project may only be partially moved. Similarly the time comes when the project is finished and you want to produce a 'stand alone' version without any of the source code. To do this drag the project icon with the Select button and a stand alone copy of the project will be created without any code. The original will be left untouched. Creating a new application To define a new application click the New button in the project list window. The Create new application window appears. The Name field can contain a name for the application up to 32 characters long. This name can contain spaces. The Description field can contain a brief description of the application. In the field under the App icon you should enter the name of the application as it will be stored on disc. For example !Edit, !Draw or !Paint are all valid names. The name must start with an exclamation mark (!) to show that it is an application. When all the fields have been filled in the App icon should be dragged to the directory display where you want the application to be stored. If you prefer the whole pathname can be filled in the and Save button clicked on. Clicking on the Cancel button will remove this window. Remaining project functions The two remaining buttons on the project list window are Open and Delete. Open will open the parent directory that contains the project. This allows the project to be run (if it is an application) without having to work your way down the directory structures until it is found. Delete deletes the highlighted projects. Preferences Compiler resources Choosing Compilers from the Preferences submenu produces the Compiler resources window. This allows support for new languages to be added to Imagine. Note that a language must have a suitable compiler. Interpreted languages such as BASIC are not supported. Suffix The suffix is used to identify the different code types. For example c is C code, cc or c++ is C++ code. Clicking on the help menu icon will produce a list of code types already defined. Compiler This should contains the compiler that is used to compiler this type of code. Type This is a brief description of this code type. For example, the cc code type might have the description GNU C++. There are a number of flags associated with a compiler. Imagine does not try to support every single flag, just the general ones. It is possible, as we shall see later, to have some flags that are specific to a particular compiler. Compile This flag specified that the compiler should not try and link the object file. Strict Tells the compiler to be extra strict when checking the conformance to standards of the code. Include This tells the compiler where to look for include files. Output Tells the compiler what to call the output object file. Depend It is possible for some compilers to produce dependency files. These files show which other files a piece of code is dependent on. This flag should tell the compiler to produce a !Depend file. Debug This flag tells the compiler to produce debug information that can be used with DDT (Desktop Debugging Tool). Memory he minimum amount of memory that the compiler needs to run. Most compilers can grab any extra memory that they need but some (such as GCC) need to be given as much memory as they are likely to need on startup. Manager If you try to run come compilers (such as GCC) on machines with small amounts of memory (less than 8M (!)) then you will need some sort of virtual memory manager. This field should contain the name of the virtual memory manager that replace the Taskwindow command. Virtual memory This field should contain the amount of memory that the virtual memory manager is to supply. The following four flags are all user definable. This allows support for compiler dependent options to be built in. The names of these flags can also be specified for use in the compiler flags window. Command The full command to compile a piece of source code using this compiler. Unless you are adding a new compiler it is recommended that this field is left alone. If you are adding a new compiler then copy this entry from another compiler. There a a number of buttons along the bottom of this window. Edit allows a default template for each code type to be edited. Some special fields can be embedded in the template which will be substituted when a new piece of code is created. $name This will be replaced with the name of the code $suffix This will be replaced with the code suffix $date This will be replaced with the date and time of code creation Delete will delete the current code type. Note that any projects which contain code of this type will generate errors if you now try to compile this code. New clears all the fields ready for a new code type. Cancel closes the window. OK stores the choices for the current code type. Linker resources Choosing Linker from the Preferences submenu produces the Link resources window. This allows the flags associated with the linker to be defined. It is unlikely that you will want to change these entries. Archiver resources Choosing Archiver from the Preferences submenu produces the Archiver resources window. This window allows the flags used by the archiver (eg libfile) to be specified. Resource resources Choosing Resources from the Preferences submenu produces the Resources resources window. This allows resource file types for applications to be specified. Name should be the name of a valid resource type such as !Boot or !Sprites. Clicking on the help menu icon will produce a list of currently defined resources. Type is the filetype of the resource. Clicking on the help menu icon will produce a list of valid filetypes. If the filetype that you require is not there the hex value can be typed directly into the field. Treat as text causes the resource to be loaded into a text editor when it is edited. Note that for this to work the text editor must already be loaded. Base is used when creating a new resource type. All resource types must have a file to be based on. This file should be dragged here and the name will appear in the Base field. The buttons at the bottom of the window act as follows. Edit allows the default file for each resource type to be edited. Delete will delete the current resource type. New clears all the fields ready for a new resource type. Cancel closes the window. OK stores the choices for the current resource type. Other preferences There are a couple of other preferences on the Preferences menu. Results causes the compile output window to appear whilst code is being compiled. If this is not selected the results will only appear when compilation has finished. Continue will cause Imagine to keep going even if there have been compiler errors when compiling multiple sources. Delete will delete the current code type. Note that any projects which contain code of this type will generate errors if you now try to compile this code. New clears all the fields ready for a new code type. Cancel closes the window. OK stores the choices for the current code type. ---------------------------------------------------------------- The author can be contacted at: EMail imagine@really.demon.co.uk Snail mail: The Really Small Software Company Olivers Hill Ashburnham Battle Sussex TN33 9PE Comments, bug reports and suggested improvements gratefully received.