Programmer's ROM - The Computer Language Library

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

/ Programmer's ROM - The Computer Language Library / programmersrom.iso / ada / tools / constrct.doc < prev next >

Wrap

Text File | 1988-05-03 | 30.8 KB | 1,585 lines

DOCUMENTATION OF THE PROTOTYPE ADA TOOLS CALLED CONSTRUCT AND CREATE_CO TABLE OF CONTENTS Page ---- LIST OF ILLUSTRATIONS C-5 1.0 INTRODUCTION C-6 1.1 Purpose C-6 1.2 Scope C-6 2.0 USER INTERFACE WITH TOOLS C-7 2.1 Construct Tool C-7 2.1.1 Function C-7 2.1.2 Invocation C-7 2.1.3 Inputs C-7 2.1.4 Outputs C-11 2.2 Create_CO Tool C-15 2.2.1 Function C-15 2.2.2 Invocation C-15 2.2.3 Inputs C-15 2.2.4 Outputs C-16 3.0 MODIFICATIONS FOR REHOSTING C-21 3.1 Construct Tool C-21 3.2 Create_CO Tool C-23 LIST OF ILLUSTRATIONS Figure Title Page ----- ----- ---- 1 Example Graphs from Construct C-12 2 Example Configuration Object C-18 1.0 INTRODUCTION The prototype Ada tools, Construct and Create_CO, were developed for the Worldwide Military Command and Control System (WWMCCS) Information System (WIS) Joint Program Management Office to begin a collection of tools which might later be integrated with the Ada Programming Support Environment for WIS. The Construct and Create_CO tools provide not only a useful software development capability but also provide an example of the use of Ada. 1.1 Purpose The purpose of this document is to provide a brief guide for the use and maintenance of the Construct and Create_CO tools. 1.2 Scope The scope of this document includes a discussion of the function, invocation, inputs and outputs of both Construct and Create_CO. This discussion reflects the tools as currently implemented on an Intellimac 7000M/UNIX host with a TeleSoft Ada compiler. Information on rehosting the tools is also provided. 2.0 USER INTERFACE WITH TOOLS 2.1 Construct Tool 2.1.1 Function The function of Construct is to perform the minimal number of system commands to bring a project up to date given that changes to project files have occurred. If a project is already up to date, Construct will indicate this and no commands will be performed. Construct can also be used to supply descriptive information in the form of dependency graphs and name lists of project files. The intent of Construct is to provide the foundation for configuration management in a given programming support environment. Even though to date the tool has not been integrated with any specific environment which includes a database management system, the terms "database object" or simply "object" are used interchangeably with the term "file" throughout this documentation. 2.1.2 Invocation To invoke Construct using the TeleSoft Ada compiler on the Intellimac 7000M, the user enters at the terminal: run construct 2.1.3 Inputs One input file is required by Construct. This is the configuration object which describes the dependencies that exist among project files. For example, if a particular Ada package, say PACKAGE_1, has a context clause for another package, say PACKAGE_2, then a dependency exists between these two packages such that PACKAGE_2 must be compiled before compiling PACKAGE_1. Dependencies specified in the configuration object are not restricted to Ada source code compilations; any commands recognized by the given host system and stored in the configuration object can be invoked using Construct. However, for Ada source code files, the configuration object can be automatically generated by the Create_CO tool. The procedure for using Create_CO is discussed in Section 2.2. If Create_CO is not used, the configuration object can be manually entered with an editor. The syntax which must be followed for manual creation of the configuration object is discussed in Section 2.2.4. The name of the configuration object is input as an argument to Construct. Other arguments to Construct include the target(s) names and option(s). The user is prompted for all three arguments. A target is a project file which is to be brought up to date as specified in the configuration object. The given target does not have to be the highest level object described in the configuration object; it can also represent a sub-structure within the project. The options argument allows the user to indicate whether system commands should be executed and/or displayed as well as whether additional graphs and lists should be generated. At each argument prompt, the user is given 3 attempts to make a valid entry. When the argument is a list (e.g., a list of options), the user is given 3 attempts for each item in the list. A list is not a valid entry on any retry. The following characters are recognized as separators in a list: blank, comma, colon, backslash, semicolon, parenthesis, or double hyphen. Note, these characters may not be embedded in the names of configuration objects or targets. Error messages are provided when invalid entries are made. If the user requires help on entering a particular argument, a "?" can be entered to display relevant help information. The configuration object entered as an argument must exist and be accessible to the user. If upper/lower case is significant to the filenaming conventions on the given system as with UNIX, then this and any other conventions must be observed. A default configuration object, named "co_file", may be specified by entering just a carriage return at this prompt. A list of configuration objects is an invalid entry. If a carriage return is entered at the prompt for targets, the default is assumed meaning the first object to appear in the configuration object will be used. If a list of targets is desired, then the list must be explicitly entered by the user with targets separated by any of the special characters mentioned above. Minimal checks are performed on targets at the input stage of Construct's execution. Errors such as the target does not appear in the configuration object or is inaccessible to the user are not recognized by Construct until after the user has entered all arguments. Therefore, if an invalid target is entered by the user, an error message will be displayed but the user is not given an opportunity to correct the mistake. The set of valid options a user may enter includes: 1) Execute - execute the commands needed to update the system. 2) Cmd_Print - print the commands needed to update the system. 3) Top_Down_Graph - print a textual top-down graph of dependencies for the given target. 4) Bottom_Up_Graph - print a textual bottom-up graph of dependencies for the given target. 5) List - print lists of all basic and derived names in the given configuration object. To explicitly turn any of the above options off, the prefix "No_" is entered with the option (e.g., No_Execute). The list of default options includes: Execute, Cmd_Print, No_Top_Down_Graph, No_Bottom_Up_Graph, No_List. If just a carriage return is entered at the options prompt, then all the default options will be used. To change any of these options, the user must explicitly enter the appropriate option. Options may be entered in mixed case or abbreviated. If a list of options is entered, these may be entered in any order. Should conflicting options be entered (e.g., No_Execute and Execute), the last one in the list will be assumed. 2.1.4 Outputs The type of output received from Construct depends upon the options input as arguments by the user. If either of the graph options (i.e., Top_Down_Graph or Bottom_Up_Graph) are entered, a textual graph of object dependencies is displayed where each indentation represents another dependency level. The Top_Down_Graph illustrates dependencies in such a way that the highest level object in the graph is dependent upon all lower level objects. In the Bottom_Up_Graph, the highest level object is a dependent of all lower level objects. Each graph includes only the dependencies related to the specified target. Figure 1 provides an example of both types of graphs for the same specified object (in this case, the target is arguments.sym). The first column of numbers seen in the graphs is the consecutive line number. The following numbers which are enclosed in brackets indicate the line where the current object is expanded into its own sub-graph, thereby providing a more concise graph. If the List option is entered, two lists of object names are displayed. The first is a list of basic names which refer to objects which can not be machine generated (e.g., text files). The other list includes derived names which refer to objects which can be generated given the dependency rules in the configuration object. Note that these lists show all the names which appear in the specified configuration object. ------------------------------------------------------------------------------ 1 arguments.sym 2 arguments.text 3 str_pack.sym 4 .... str_pack.text 5 environs.sym 6 .... environs.text Top Down Graph ----------------------------------------------------------------------------- 1 arguments.sym 2 construct.code 3 bld_graph.sym 4 .... construct.code 5 bld_graph.code 6 bld_lst.sym 7 [ 3].... bld_graph.sym 8 .... bld_graph.code 9 bld_lst.code 10 con_proc.sym 11 .... construct.code 12 con_proc.code 13 display.sym 14 .... construct.code 15 display.code Bottom Up Graph --------------------------------------------------------------------------- Figure 1 EXAMPLE GRAPHS FROM CONSTRUCT When the Cmd_Print option is on (i.e., the default condition), the commands to be invoked by Construct are displayed in the order they would be performed. If in addition the Execute option is set (also the default condition), any feedback resulting from the execution of tools invoked through Construct will appear at the terminal. The presence of cycles in the dependency rules of the configuration object (e.g., a rule stating that the object "Construct.code" depends upon "Construct.code") is always determined by Construct. If cycles exist, an error message showing both the direct and indirect cycles is displayed and execution of Construct is halted. For example, the message may be: Object_1 <= Object_2 <= Object_3 <= Object_1 which indicates that Object_1 is indirectly dependent upon itself and is therefore a cycle error. Some other error messages are provided during the execution of Construct. These generally occur as the result of fatal errors causing Construct to be aborted. The messages are self explanatory and are not discussed individually here. In the event of an unexplainable error, there are two debugging traces of Construct's execution which can be used to isolate the problem. To produce this output, which is routed to a file called DUMP_OUTPUT, the options Dump_Tree and/or Process_Dump must be set during the input of arguments. Dump_Tree traces the parsing of the configuration object while Process_Dump traces the determination of commands to be performed. Neither of these options would be used in production runs of Construct but are briefly mentioned here as Construct is still a prototype tool. 2.2 Create_CO Tool 2.2.1 Function Create_CO reads a set of Ada source code files and creates a configuration object which describes the dependencies that exist among the files. The configuration object is formatted so that it may be read by Construct. In determining dependencies, Create_CO observes the filenaming conventions of the TeleSoft Ada compiler (i.e., filename extensions of .text, .sym, .code) and the compiler's language restriction that specifications and bodies of Ada packages reside in the same file. 2.2.2 Invocation Create_CO is invoked by entering the command: run create_co 2.2.3 Inputs The inputs to Create_CO must conform to the UNIX operating system filenaming conventions. There are two inputs to Create_CO: the name of the configuration object to be created and the UNIX filename pattern describing the set of Ada source code files to be read. The filename pattern may include the special characters "*" and "?", and selectors such as "[aeiou]" which are supported by UNIX. Both inputs are prompted for as shown below: ENTER CO_FILE_NAME => ENTER NAMES OF FILES TO BE SCANNED => A typical response to these prompts would be: ENTER CO_FILE_NAME => co_file ENTER NAMES OF FILES TO BE SCANNED => *.text The above responses cause the creation of a configuration object named co_file which describes the dependencies among all files in the current directory which end in ".text". Note that the user may create a configuration object from files in another directory by including the appropriate path in the filename pattern, for example: ENTER NAMES OF FILE TO BE SCANNED => ada/test_library/*.text However, when files are read from a directory other than the current working directory, all directory paths are stripped from the filenames and are not reflected in the configuration object. 2.2.4 Outputs Create_CO displays the name of each input file as it is being processed. This allows the user to observe Create_CO's progress and to check that the specified filename pattern resulted in the correct set of files to be read. An error message is reported when Create_CO is unable to access a particular file and then that file's dependencies are not included in the configuration object. If none of the specified files are accessible, an empty configuration object will result. The primary output of Create_CO is a configuration object which obeys the syntax recognized by Construct. An example configuration object is shown in Figure 2 to illustrate the following discussion. A configuration object contains one or more dependency rules. Each dependency rule consists of the following ordered parts: - a list of targets - the target list terminator, ":" - a list of dependents - the dependent list terminator, ";" - a list of system commands - the command list terminator, "$" The order of dependency rules within the configuration object is unimportant except that the first rule in the file should have as its first target the most frequently updated target in order to facilitate the use of default inputs when running Construct. Comments may appear anywhere in the configuration file. There should be no blank lines in the file. Comments must be in the form of standard Ada comments. They begin with "--" and are terminated by the end of a line. Thus, just as in Ada, comments may occur at the end of a line or on a line by themselves. All text on the line following the arguments.sym arguments.code :arguments.text environs.sym str_pack.sym\ host.sym environs.sym; ada arguments $ ast_graph.sym ast_graph.code :ast_graph.text calendar.sym str_pack.sym; ada ast_graph $ bld_graph.sym bld_graph.code :bld_graph.text bld_lst.sym ast_graph.sym\ str_pack.sym arguments.sym environs.sym; ada bld_graph $ bld_lst.sym bld_lst.code :bld_lst.text ast_graph.sym environs.sym\ ast_graph.sym str_pack.sym arguments.sym; ada bld_lst $ calendar.sym calendar.code :calendar.text; ada calendar $ con_proc.sym con_proc.code :con_proc.text host.sym ast_graph.sym str_pack.sym\ calendar.sym environs.sym arguments.sym; ada con_proc $ construct.sym construct.code :construct.text bld_graph.sym display.sym\ arguments.sym con_proc.sym environs.sym; ada construct $ create_co.sym create_co.code :create_co.text str_pack.sym host.sym\ environs.sym; ada create_co $ display.sym display.code :display.text ast_graph.sym str_pack.sym\ arguments.sym environs.sym; ada display $ environs.sym environs.code :environs.text; ada environs $ host.sym host.code :host.text str_pack.sym calendar.sym environs.sym; ada host $ str_pack.sym str_pack.code :str_pack.text; ada str_pack $ Figure 2 EXAMPLE CONFIGURATION OBJECT "--" will be interpreted as a comment. The target and dependent lists may occur on a single line or on a series of continued lines. A line is marked as continued when the last character in the line is a backslash ("\"). Objects in either list are separated by any of the following characters: " " "," ":" "\" ";" "(" ")" "--" All extraneous blanks between objects are ignored. The first colon in the dependency rule is interpreted as the end of the target list while subsequent colons are interpreted simply as separators within the dependent list. A semicolon within the dependent list is interpreted as the end of the list while semicolons within the target list are interpreted simply as separators. A typical format for target and dependent lists is: target_one target_two : dependent_one dependent_two; or for longer lists: target_one target_two : dependent_one dependent_two\ dependent_three dependent_four; Note that spacing and the order of objects within a list have no effect on the interpretation of the target and dependent lists. Following each pair of target and dependent lists is a list of system commands. These commands define the relationships stated in the corresponding pair of target and dependent lists. The command list may include any command recognized by the host operating system's command language interpreter. The commands must appear in the list in the order they are to be executed. A "$" must appear in the first column of the line following the command list in order to mark the end of the command list and therefore the end of that dependency rule. Figure 2 EXAMPLE CONFIGURATION OBJECT 3.0 MODIFICATIONS FOR REHOSTING 3.1 Construct Tool The host-specific code in Construct falls into three categories: tool parameter handling, database object timestamps, and command execution. These dependencies are isolated in Construct with the package HOST. Construct utilizes the facilities in HOST without any knowledge of how these facilities are implemented. In order to rehost Construct on a new system, the package body of HOST must be rewritten for the new system to provide the same functionality without modifying the external interfaces of the package (i.e., the specification part). Parameter handling is not used in this version of Construct; instead the user is prompted for all arguments to Construct. However, the boolean function HOST.ARGS_EXIST is included in the present code to enable future versions of Construct to allow a non-prompting mode (i.e., Construct is invoked with a complete command line) in addition to the current prompting mode. This new feature will require that other parameter handling facilities be added to the HOST package. The host operating system must be able to provide Construct with the time that individual files were last modified. The function HOST.MODIFICATION_TIMESTAMP is passed the name of a file (i.e., a target or dependent object as specified in the configuration object) and it returns the last-modified time as the data type CALENDAR.TIME. If HOST.MODIFICATION_TIMESTAMP is unable to determine the last-modified time of the database object (e.g., the file does not exist or is inaccessible), the exception ACCESSIBILITY_ERROR is raised. This exception is handled by PROCESSING_INTERNALS.TIMESTAMPS_OUT_OF_SEQUENCE in the package CON_PROC which is the only subprogram in Construct that uses HOST.MODIFICATION_TIMESTAMP. Any externally visible changes to HOST.MODIFICATION_TIMESTAMP (e.g., a new exception that may be raised) must be reflected in PROCESSING_INTERNALS.TIMESTAMPS_OUT_OF_SEQUENCE. The timestamp resolution (e.g., milliseconds vs. minutes) does not affect the execution of Construct. Construct simply determines if one file has been modified more recently than another file (i.e., timestamp1 > timestamp2). However, timestamp resolution will have an obvious impact on the usefulness of Construct. For example, if the operating system only recognizes the month that files were modified, many inconsistencies brought about by changes to a project may be left unresolved by Construct. Any implementation of HOST.MODIFICATION_TIMESTAMP should return as fine a resolution as the underlying system supports. Also, Construct assumes that the last modified timestamp is a monotonically increasing value, meaning the relational operators "<" and ">" in the package CALENDAR retain their intuitive meaning when used on file timestamps. This assumption must be preserved in any implementation of HOST.MODIFICATION_ TIMESTAMPS. Construct must be able to invoke any command recognized by the host's command language interpreter (CLI). The procedure HOST.EXECUTE_CMDS is passed one line from the a list of commands in a given dependency rule of the configuration object and this procedure in turn passes the entire line as a string to the host's CLI. If an error occurs during the execution of a command (e.g., if the invoked tool terminates abnormally), the exception HOST.EXECUTION_ERROR is raised. The procedure PROCESSING_INTERNALS.EXECUTE_A_COMMAND traps this exception; it is the only subprogram in Construct that uses HOST.EXECUTE_CMDS. Any implementation of HOST.EXECUTE_CMDS should ensure that all signals, exceptions, etc. that occur in the execution of the given command do not propagate back to Construct. Also, HOST.EXECUTE_CMDS should preserve the user's execution environment to the extent possible when executing commands. For example, global CLI variables, search paths, and access rights should be the same for HOST.EXECUTE_CMDS as those that would be available to the user when entering a command directly. 3.2 Create_CO Tool There are two major areas of consideration when rehosting Create_CO: the names of compiler-supplied packages, and the method of determining the Ada source code files to be read. The first merely requires changes to a list of constants, but the second may require a completely revised approach for obtaining the list of Ada files. The extent of the revision depends upon the capabilities of the host environment. The compiler-supplied package names are isolated in the function SYSTEM_NAME. These package names are declared as character string constants. The current list of library unit names recognized by Create_CO is: Text_IO, System, Direct_IO, UNIX_Call, Unchecked_Conversion, and Host_LCD_If. The standard library units Unchecked_Deallocation, Sequential_IO, IO_Exceptions, Low_Level_IO, and Calendar should be added when a validated compiler which includes these units is available. If a TeleSoft compiler is being used, the two Telesoft-specific library units Arg_Parser and Terminal_IO should be added. In general, the function SYSTEM_NAME will need to be modified to reflect all library units supplied by the compiler system on the new host. The code for obtaining the appropriate list of Ada files to be read is isolated in the procedure GET_LIST_OF_FILENAMES. As currently implemented, this procedure prompts the user for a character string to be used as a UNIX pattern for matching filenames. A UNIX directory command is created with this pattern such that the output from the directory command is routed to a file named CREATE_CO.TEMP. The host-specific procedure EXECUTE_CMDS from the package HOST is called to execute the directory command. The matching filenames are then read from the file CREATE_CO.TEMP and inserted into a dynamic string. If the new host environment supports command execution, pattern matching, and redirection of command output to files, this same algorithm may be used with minor modification of character string literals to create the proper directory command. Otherwise, GET_LIST_OF_FILENAMES must be rewritten to implement some new algorithm. Possible approaches are to have the user enter all filenames explicitly, or to have the user enter the name of a file which contains the list of source code files to be processed. Create_CO is also dependent upon the format of the configuration file which may change when rehosted to another system. Separators with special meaning, such as colon, semicolon, and backslash, should be defined as character constants so that they are more easily modified. Likewise, the compilation command (currently "ada filename") should be parameterized to facilitate rehosting.