ARM Club 3/TheARMClub_PDCD3.iso/hensa/projects/imagine_1/!Imagine/!Help

Text File | 1995-12-24 | 20KB | 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
[e-mail]

Snail mail:
The Really Small Software Company
Olivers Hill
Ashburnham
Battle
Sussex TN33 9PE


Comments, bug reports and suggested improvements gratefully received.