HELP POP_UI_PROJECTTOOL                        Julian Clinton, June 1995

Using the Poplog Project Tool.


         CONTENTS - (Use <ENTER> g to access required sections)

  1   What Is A Project?
      1.1   The Base Directory
      1.2   Description & Workspace

  2   What Is The Project Tool?

  3   Creating A New Project

  4   The New Project Dialog

  5   The Project Tool Window

  6   Adding Files To A Project

  7   Operations On Files
      7.1   Editing & Viewing Files
      7.2   Saving & Closing Files
      7.3   Compiling & Running Files
      7.4   Information About A File
      7.5   File Categories
      7.6   Changing File Information

  8   Building Saved Images
      8.1   The Build Script
      8.2   The Loader File
      8.3   Example

  9   The Project Tool Menu Bar
      9.1   The Project Menu
      9.2   The Selected Menu
      9.3   The Edit Menu
      9.4   The Build Menu
      9.5   The Help Menu

 10   The Preferences Dialog
      10.1  General Options
      10.2  View Options
      10.3  Auto Save/Update Options
      10.4  Save Workspace Options

 11   The Image Tool
      11.1  Runtime Options
      11.2  Image Options
      11.3  Script Options

 12   The File Information Dialogs
      12.1  The File Information Dialog Buttons

 13   Ved Commands


-----------------------------------------------------------------------
1  What Is A Project?
-----------------------------------------------------------------------

A project is a collection of files which will usually be combined into a
program. The files may be program source code, documentation or command
scripts. A project provides a simple mechanism for associating related
files together and since a project will normally contain information
about all source code files in a project, it becomes easier to generate
saved images and build scripts automatically.


1.1  The Base Directory
-----------------------

A project is stored on disk in a project file (a file with a '.prj' file
extension). The location of the project file defines the base directory
of the project.

When a file is added to the project, the pathname of the file is either
stored relative to the base directory (if the file is below the base
directory) or as the full path.

Keeping files within the project base directory allows you to move the
whole project to a different location simply by moving the base
directory.


1.2  Description & Workspace
----------------------------

You can think of a project as being made of two parts. One part contains
information about the project (the project file, which is the name of
the project with a '.prj' file suffix). This information includes the
list of files in the project, preferences which control appearance and
behaviour and so on. The second part can be used to save information
about the project workspace (stored in a file which is the name of the
project with a '.pws' file suffix). This includes the layout of windows
when the project was last closed and what part of a file was being
displayed within an editor window. These are both updated when a project
is closed.


-----------------------------------------------------------------------
2  What Is The Project Tool?
-----------------------------------------------------------------------

The Poplog Project Tool provides a simple way of accessing and
manipulating a project. It allows you to add and remove files, perform
actions on the files and customise the behaviour of the Project Tool.

The Project Tool window displays a list of the files in the project. You
can select one or more of these files and perform the action you require
by choosing an appropriate option from one of the menus on the menubar.
Having a permanent list of files available allows files to be selected
and edited easily and quickly.

The Project Tool also provides some help in creating saved images for
the program being developed. This is normally used towards the end of
development if the compiled program has to be delivered or made more
generally available.

Only one project can be open at a time. If you have a project open and
you want to create a new project or open a different project, the
current one will be saved and closed.


-----------------------------------------------------------------------
3  Creating A New Project
-----------------------------------------------------------------------

A new project can be created using the Project|New menu option on the
main Poplog control panel or on the Project Tool itself. The 'New
Project' dialog will appear, prompting you for a project name and the
base directory (the directory where the project file will be saved).


-----------------------------------------------------------------------
4  The New Project Dialog
-----------------------------------------------------------------------

The New Project dialog contains two text fields used to specify the name
of the project and the base directory.

The project name is used as the basis for filenames and other support
facilities. The name should start with an alphabetic character and
contain only alphanumeric characters.

The base directory specifies where the project description and
workspace files are saved. This does not have to be the same directory
as the files containing the program source code, documentation etc.
although as explained previously, there are advantages in keeping all
associated files within the base directory.

When you are satisfied that the project name and directory are correct,
press Create to create the project. The Project Tool window will
appear with the name of the new project in its title bar. If you are
already using a project, this will be saved and closed first.

When a new project is created while another project is open, certain
attributes of the existing project are also copied. These are the
options displayed on the following Preferences Dialog sheets: View, Auto
Save/Update and Save Workspace.

If you don't want to create a new project, press Cancel.


-----------------------------------------------------------------------
5  The Project Tool Window
-----------------------------------------------------------------------

The Project Tool consists of a menu bar, a scrolling list of files,
a message line and a Cancel button.

The scrolling list displays the names of all files in the project. Using
the mouse or keyboard, you can select files that you wish to perform
actions on. You can also double-click over a file or press RETURN when
it is selected to open the file for editing.

The menu bar allows you to perform actions either on the project or on
the files within the project. The menu contains the buttons

    Project  Selected  Edit  Build  Help

which are described in more detail below.

Some menu actions are only available under certain circumstances. For
example, you can only open a file using Selected|Open when at least
one file has been selected from the files list. Similarly you can only
close a file from the Project Tool when at least one of the selected
files is being edited or viewed.

The message line displays text which provides feedback about the status
of the Project Tool.

The Cancel button can be used to interrupt certain operations (such as
compiling a set of files). Normally the Cancel button is disabled.


-----------------------------------------------------------------------
6  Adding Files To A Project
-----------------------------------------------------------------------

To add files to a project, you can use the Edit|Add option or the Ved
<ENTER> project commands add, addmr and addall. For example, to add the
current Ved file to the project, do

        <ENTER> project add

If you use the Edit|Add option, a file selection dialog will be
displayed allowing you to select a file to be added to a project. You
can add a the name of a file which doesn't yet exist to the project.

You can add multiple files to a project easily by creating a list of
filenames in a Ved buffer on separate lines (for example, using the
<ENTER> ls command), marking the files you want and doing

        <ENTER> project addmr

Other Ved <ENTER> commands are described below.


-----------------------------------------------------------------------
7  Operations On Files
-----------------------------------------------------------------------

The mouse can be used to select files from the files list and to perform
a variety of tasks listed under the Selected and Edit menu buttons.


7.1  Editing & Viewing Files
----------------------------

You can edit a file by selecting it from the files list and using
Selected|Open or by double-clicking on the file entry with the mouse.
To view files, use Selected|View instead.

If a file is already being displayed in Ved, the value of *vedwriteable
for that buffer will be changed to reflect the action (e.g. set false if
the file is now being viewed). This can create the situation where a
file has been changed but not saved before being made non-writeable.


7.2  Saving & Closing Files
---------------------------

If one or more of the selected files is open, the Selected|Close option
can be used to close the selected files. You can also use the
Selected|Save option to save any changed and writeable files in the
selection.


7.3  Compiling & Running Files
------------------------------

You can compile files whose type is a Poplog language and whose
subsystem is loaded. Currently it is not possible to compile a file for
a non-Poplog language although this facility will be available in a
future release of Poplog.

If you want to compile all files in a project, it is recommended that
you use the Build|Compile All menu option rather than selecting all
files and using Selected|Compile. The reason as that the options from
the Build menu take note of the category of each file and will exclude
files which are not of type "source". This means that if you have a
utility file which compiles several other files in the project, these
will not be included. Options from the Selected menu do not check the
category of files and so you may end up re-compiling files.

You can run certain kinds of file such as Bourne shell and C shell
scripts under UNIX and DCL command files under VMS. The Run option is
only available if at least one file in the selection is runnable.


7.4  Information About A File
-----------------------------

Information stored about a file can affect how a file is treated. The
significant pieces of information stored about a file are:

    # category
        The category of a file defines how the file is treated by
        options on the Build menu. Only files whose category is
        "source" are included. See below for a fuller explanation.

    # file type
        The file type defines the basic operations that can be applied
        to a file such as can it be compiled and run.

    # purpose
        The purpose is a simple piece of text which describes what the
        file does. This description can be displayed in the files list.


7.5  File Categories
--------------------

    # source

        Denotes source files containing the main program code of the
        project.

    # utility

        These are used to support the development of the program but
        which are not part of the program itself. For example, a loader
        file which simply compiles other files could be considered a
        utility file. Utility files may be compilable and editable but
        are not included by options on the Build menu when compiling all
        files, building saved images or generating loader files.

    # documentation

        Denotes text files.

    # command script

        Denotes a command file.


7.6  Changing File Information
------------------------------

You can modify the information about a file by using the
Selected|File Info... menu option. A file information dialog will be
created and displayed for each selected file. See the information on the
File Information Dialog below.


-----------------------------------------------------------------------
8  Building Saved Images
-----------------------------------------------------------------------

The Project Tool provides support for creating saved images based on
the files in the files list. The Project Tool runs a * mkimage command
using the parameters defined using the Image Tool. The resulting saved
image can then be invoked and the startup code run.


8.1  The Build Script
---------------------

The generated build script contains a command to invoke a Poplog
executable which will then build a saved image of the project using
mkimage. The image name, the top-level subsystem and the specified
languages are included automatically in the saved image. The command
will also load the loader file (described below) which can also be
generated by the Project Tool.


8.2  The Loader File
--------------------

The loader file is a Pop-11 file which will compile all program source
files in the project. The order in which files are compiled is defined
by the order that they appear in the files list. Only files whose
category is "source" and whose type or contents is a Poplog language
will be included in the list of files.

* subsystem_compile is used to compile the program files to ensure that
any Poplog language can be used.


8.3  Example
------------

Suppose we have a Pop-11 program for computing factorials with a single
file which has been added to the project. The file looks like:

    ;;; Factorial program

    define fact(x);
        if x < 2 then
            1
        else
            x*fact(x-1);
        endif;
    enddefine;

    define start_fact;
        dlocal proglist_state = proglist_new_state(charin);
        dlocal pop_readline_prompt = 'Enter your number > ';

        lvars l;

        until (readline() ->> l) == termin do
            if not(null(l)) and isnumber(hd(l)) then
                spr('The answer is');
                npr(fact(hd(l)));
            endif;
        enduntil;
        npr('Exiting...');
    enddefine;

The start_fact procedure is the startup routine. Since the program will
read input from the terminal, it creates an input stream that can be
used by readline. It also modifies pop_readline_prompt to display a new
string as a prompt. It then loops reading numbers and printing the
factorial of the number until the user supplies the end-of-file
character.

Choose the Image Tool option from the Build menu and select the Runtime
options page. Set the Top-level field to 'Pop-11' and enter the
following as the Eval on startup field:

    start_fact();

Now select the Image options page, where you can specify the name of the
image to be created. Entering 'factorial.psv' as the image path will
create a saved image called factorial.psv in the project's base
directory. The Build using field should be set to 'pop11'.

Press the Done button to apply the changes and pop down the window. You
should now be able to select Build|Make Image menu option to build the
saved image. Some build messages will appear in the base window.

Once the build has finished, you should be able to run the resulting
image. Suspend your Poplog process (e.g. with <ENTER> stop) or start up
another window, change to the directory where the saved image was
created and do:

    pop11 +factorial

The saved image should start up and prompt you to enter a number. When
you do, the factorial of that number will be printed and you will
prompted again. To exit from the program, type the end-of-file character
e.g. Ctrl-D on UNIX or Ctrl-Z on VMS, or interrupt the program e.g. with
Ctrl-C.


-----------------------------------------------------------------------
9  The Project Tool Menu Bar
-----------------------------------------------------------------------

9.1  The Project Menu
---------------------

New...
    Displays the New Project dialog box. If another project is already
    open when the new project is created, certain information from the
    existing project is included in the new one. See 'Creating A New
    Project' above.

Open...
    Opens an existing project. Selecting this option pops up the project
    file selection dialog.

Save
    Saves the current project description and workspace.

Preferences...
    Displays the Preferences Dialog (see description below).

Rename...
    Renames the current project. Displays a text input dialog where the
    name of the new project can be entered. The dialog verifies that the
    name for the new project is valid (i.e. starts with an alphabetic
    character and subsequently only contains alphanumeric characters).
    This option will not change other parameters generated automatically
    when the original project was created, such as the names of saved
    images and build scripts.

Close
    Saves and closes the current project. Any editor windows which are
    saved as part of the project workspace are closed. If an editor
    window needs writing, a confirm dialog will appear asking if you
    want to save the file. Clicking on Yes will save the file, clicking
    on No won't save the file and clicking on Cancel will stop the
    project from being closed.


9.2  The Selected Menu
----------------------

Open
    Opens the selected files for editing. If the file is already being
    edited or viewed, the Ved window is opened and raised to the front
    of the window stack. Also ensures that the Ved buffer can be
    written, so if the file was opened with the View option then
    vedwriteable is set true for the file.

View
    Opens the selected files for viewing. If the file is already being
    edited or viewed, the Ved window is opened and raised to the front
    of the window stack. Also ensures that the Ved buffer cannot be
    written, so if the file was opened with the Open option then
    vedwriteable is set false for the file.

Save
    Saves any selected files which are changed and writeable. This does
    not necessarily mean that all changed and writeable files will be
    saved.

Close
    Closes any selected files which are being edited or viewed. If a
    file has been edited and is writeable, a confirm dialog will appear
    asking if you want to save the file. Clicking on Yes will save the
    file, clicking on No won't save the file and clicking on Cancel will
    stop other files from being closed.

Compile
    If the file is compilable and the required Poplog language has been
    loaded, the file is compiled. If the file is currently being edited
    or viewed then that copy is compiled, otherwise the version on disk
    is compiled. Note that if the file includes or compiles other files,
    these are always loaded from disk rather than from editor windows.

Run
    Runs any selected command or executable files.

File Info...
    Creates and displays file information dialogs for each selected
    file. See below for a description of the File Information Dialog.


9.3  The Edit Menu
------------------

The Edit menu is used to make changes to the project.

Add
    Adds a file to the end of the list of project files. A file
    selection dialog is displayed and the selected file is appended to
    the list of project files.

Add After
    This option is enabled if a single file is selected. It does a
    similar task to the Add option except that the file is added after
    the selected file.

Add Before
    This option is enabled if a single file is selected. It does a
    similar task to the Add option except that the file is added before
    the selected file.

Rename
    This option is enabled if a single file is selected. It allows the
    selected file to be renamed. A file selection dialog is displayed
    which you can use to specify the new name and location of the file.
    If the file is currently being edited or viewed, its name of the Ved
    file buffer is changed using * ved_name. If the file is not in a Ved
    buffer then the old file on disk is copied to the new name and
    location.

Remove
    Removes the currently selected files from the project. A confirm
    dialog will appear to check whether the files should be removed, or
    to cancel the operation.

    If any of the selected files is being edited or viewed, the dialog
    will also ask whether any editor or viewed files should be closed.
    selecting this option will also save any files which have been
    changed and are writeable.

Refresh
    Redisplays the contents of the file list. This will also update
    other information displayed about each file such as the modification
    date and size of the file on disk.

Select All (Motif only)
    Selects all files in the file list.

Deselect All (Motif only)
    Deselects all files in the file list.


9.4  The Build Menu
-------------------

Compile All
    Compiles all compilable files. Compilable files are those whose type
    is a Poplog language and the language subsystem is loaded. The order
    in which files are compiled is defined by their ordering in the
    files list.

Make Image
    Builds a saved image of the project. The name of the image, which
    languages are used and other parameters can be set using the Image
    Tool.

Make Scripts
    Generates files which can then be used to build a saved image of the
    project. The names of the files and which files are generated are
    specified using the Scripts options on the Image Tool.

Image Tool...
    Displays the Image Tool window which can be used to modify
    parameters used when building project saved images.


9.5  The Help Menu
------------------

About Project
    Displays a message box giving information about the current project.

About Project Tool
    Displays the Project Tool help file (this file).

About Poplog
    Displays the Poplog Information window.

Search...
    Displays the Help Tool which you can use to search for help on
    different topics (see HELP * POP_UI_OVERVIEW).


-----------------------------------------------------------------------
10  The Preferences Dialog
-----------------------------------------------------------------------

The Preferences Dialog allows you to customise aspects of the current
project such as how files are displayed, what information the project
should save about the workspace etc.

Invoke the Preferences Dialog using the Project|Preferences option on
the Project Tool menubar. The Preferences Dialog (like the Poplog
Options Dialog) contains a number of different sheets which you can
select using the Options menu at the top of the tool. There are also
four buttons arranged along the bottom of the dialog:

    Apply
        Applies the changes you have just made to the current sheet
        without popping down the dialog window.

    Reset
        Reverts any changes you have made to the current sheet to the
        most recently applied values.

    Done
        Applies the changes you have just made to the current sheet and
        pops down the dialog window.

    Cancel
        Pops down the dialog window without applying any changes you
        have made to the current sheet (although changes made to other
        sheets will be stored).

Changing between different sheets has the same effect as pressing Apply.


10.1  General Options
---------------------

The first sheet contains basic information about the project. Two of
these are display-only and one is changeable.

    Description
        This is a simple text field which allows you to enter a brief
        description of the project.


10.2  View Options
------------------

The View options specify how times and dates are displayed and what
information is displayed in the file list along with the file name.

    Time & Date

    Time format
        How times should be displayed.

    Date format
        How dates should be displayed

    File Display

    Show
        Toggles what extra information is shown about each file in the
        file list.

    VMS users should not that the size in bytes will not necessarily
    reflect the number of characters in the file due to the way file
    records are held on disk.


10.3  Auto Save/Update Options
------------------------------

These options specify what actions should be carried out automatically
and at what intervals. These are:

    Save project
        Specifies if and how often the project should be saved. Note
        that this does not automatically save Ved files as this is
        controlled by other facilities such as * ved_autosave and
        * vedautowrite.

    Update project
        Specifies if and how often the list of files in the project
        should be refreshed.


10.4  Save Workspace Options
----------------------------

The Save Workspace options specify what workspace information is
saved when the project is closed. These are:

    Project Tool

    Window location
        Defines whether or not the position and size of the Project Tool
        window should be saved and restored.

    Ved Windows

    Save which
        Defines which Ved windows should have information about them
        saved. The options are windows displaying files in the project,
        all Ved windows or none.

    Window location
        if information about Ved windows is being saved, this option
        defines whether the window position and the position of the
        text cursor in the buffer should be saved and restored.


-----------------------------------------------------------------------
11  The Image Tool
-----------------------------------------------------------------------

The Image Tool can be used to define parameters used to build a saved
image of the project. It provides a simple interface to the mkimage
library (see HELP * MKIMAGE). The tool can generate two files: a build
script and a loader file. The two files can also be added to the project
where they can be edited and then run from the Project Tool.

You should note that the build script and loader file generated by the
tool contain absolute pathnames. If the project base directory is moved,
you may need to re-generate these files. Alternatively, you may prefer
to substitute the absolute pathname for a shell variable.

The Image Tool is organised similarly to the Preferences Dialog, with a
menu button at the top for selecting a particular options sheet and four
buttons arranged along the bottom of the tool window:

    Apply
        Applies the changes you have just made to the current sheet
        without popping down the tool window.

    Reset
        Reverts any changes you have made to the current sheet to the
        most recently applied values.

    Done
        Applies the changes you have just made to the current sheet and
        pops down the tool window without generating or running any
        files.

    Cancel
        Pops down the tool window without applying any changes you have
        made to the current sheet (although changes made to other sheets
        will be stored).

Changing between different sheets has the same effect as pressing Apply.


11.1  Runtime Options
---------------------

The Runtime options allow you to define how the end program should be
invoked and to set various parameters in the runtime workspace. These
are:

    Top-level
        Defines the top-level language used by the application. This
        option defines what language any startup expression is evaluated
        in and also defines the "-subsystem" parameter supplied to
        * mkimage.

    Eval on startup
        An expression which is to be evaluated as the startup expression
        of the program.

    Min. heap size
        Specifies the minimum heap size used by the application. See
        also * popminmemlim.

    Max. heap size
        Specifies the maximum heap size used by the application. See
        also * popmemlim.

    GC type
        Specifies the default garbage collection algorithm. See also
        * pop_gc_copy.

    GC ratio
        Specifies the initial garbage collector ratio. See also
        * popgcratio.


11.2  Image Options
-------------------

These options allow you to specify the name of the saved image, the
executable used to make it and the languages which it must include.

    Image path
        Defines the name of the project saved image. This can be either
        an absolute pathname or relative to the project base directory.

    Build using
        Defines which Poplog command to use when invoking mkimage.

    Languages
        Defines which languages are required for the application to
        compile and run.


11.3  Script Options
--------------------

These options determine what happens when the Make Scripts option is
selected from the Project Tool Build menu.

    Script pathnames

    Build script
        The pathname to be used when generating the build command
        script.

    Loader file
        The pathname to be used when generating the loader file.


    Generate

    Build script
        Defines whether a new build script should be generated and if
        so, whether the file should be added to the project.

    Loader file
        Defines whether a new loader file should be generated and if so,
        whether the file should be added to the project.


-----------------------------------------------------------------------
12  The File Information Dialogs
-----------------------------------------------------------------------

File information dialogs are used to display and change properties of
files within the project. Using the Selected|File Info... option will
display an information dialog about each selected file. The information
that can be changed about the file is:

    Category
        How the file should be treated by the project.

    File type
        What the type of the file is. This defines what operations can
        be carried out on the file (e.g. can it be compiled).

    Purpose
        Text field giving a brief summary of the file's purpose. This
        will appear as part of the file information in the Project Tool
        file list if the description File Display.


12.1  The File Information Dialog Buttons
-----------------------------------------

    Update
        Applies any changes you have made to the file information and
        pops down the file information dialog.

    Cancel
        Pops down the file information dialog without applying any
        changes made.


-----------------------------------------------------------------------
13  Ved Commands
-----------------------------------------------------------------------

A number of project actions can be made using Ved <ENTER> commands. The
form is:

        <ENTER> project command

Commands that modify the current project do nothing if no project is
open.

The commands are:

    add
        Adds the file being displayed in the current Ved buffer to the
        end of the list of files in the project.

    add filename
        Adds the named file to the end of the list of file in the
        project.

    addmr
        Adds the files listed in the marked range to the end of
        the list of files in the project. Each line in the marked range
        should contain a single file name. Leading white space is
        ignored.

    addall
        Assumes the current Ved buffer contains a list of file names
        (one per line) and adds the files to the end of the list
        of files in the project. Leading white space is ignored.

    new
        Displays the New Project dialog box.

    open
        Displays a project file selection dialog which can be used to
        open an existing project file.

    open filename
        Opens the project file specified by filename.

    save
        Saves the current project.

    close
        Closes the current project.


--- C.x/x/pop/help/pop_ui_projecttool
--- Copyright University of Sussex 1996. All rights reserved.
