HELP POP_UI_PROJECTTOOL Julian Clinton, June 1995 Using the Poplog Project Tool. CONTENTS - (Use 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 project commands add, addmr and addall. For example, to add the current Ved file to the project, do 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 ls command), marking the files you want and doing project addmr Other Ved 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 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 commands. The form is: 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.