Changing Multics

From Multics Wiki
Jump to: navigation, search

Changing Multics

This page discusses tasks involved in changing code of the Multics operating system. Such code changes would be distributed to other Multics site as a Multics Release.


File a Multics Bug

The first step in changing Multics is to enter a bug (aka Multics Ticket) describing the desired change or enhancement.

Interface with the Multics Ticket subsystem using the following link:

This subsystem will assign a ticket number to your description of the desired change. That ticket number will be referenced in later steps of this process.

If you are only requesting a change but do not wish to make the code changes yourself, then skip the remaining steps. Your request will be considered by other developers as part of the next Multics Release development cycle.


Change Multics Code / Build Revised Objects

Making actual code changes is most easily done on the Gold Hill Multics (GHM) site on which new Multics Release candidates are developed. That site holds the latest source code in its Multics Libraries. However, if the code has not been changed since the most recent Multics distribution (at the time of this writing, that is Multics 12.6f), then code changes could be performed on any other Multics site running that latest Multics Release.


Changes to the kernel could be developed and tested most easily on your personal Multics site. This would permit creation of your own test system, with its own disk image files, etc. You then control rebooting the test system using a revised Multics System Tape (MST); interrupted operations to enter BCE for kernel debug purposes; special configuration of simulated hardware; etc.

Once kernel changes were tested, your revised code could then be moved to the GHM site for integration with other pending changes, culminating in System Tests of a new Multics Release distribution.


Changes outside the kernel might be easier to accomplish on the GHM site on which new Multics Release candidates are developed. The mbuild subsystem simplifies development builds, but has not been included in an official Multics Release as yet. It has been installed on the GHM site.


Multics Code Fetch Example

Starting a Multics change often begins with finding code that performs a given function or provides a Multics service. Once this code is located, an experimental version containing code revisions can be prepared.

The following example shows fetching an existing library source, and the bind file for its containing bound segment. The bind file is needed because a new entry point will be added to the existing source; this entry point must be retained when the compiled source is bound into its containing bound segment. Only the fetch operation is shown here.

The example begins in an empty directory. The library_fetch (lf) command extracts a copy of the existing Multics source modules that will be changed. Since a new external entry points is being added, this example also fetches the bind file for the bound object to which that source will be added. It includes translator_temp_.pl1 and its bound_proj_admin_.bind into an empty directory.

Note: library_fetch can be used to fetch source modules, source include files, bind files, and info segments. The default library_fetch search directories include source and include files. Specify "-library object" control argument to select bind files; specify "-library info" to select info segments. 

ls
Directory empty: >user_dir_dir>Multics>GDixon>w>temp
r 16:10 0.103 0

lf translator_temp_.pl1
r 16:11 0.498 44

lf -library object bound_proj_admin_.bind
r 16:21 0.364 14

ls

Segments = 3, Lengths = 5.

r w    1  bound_proj_admin_.bind
r w    2  translator_temp_.pl1

r 16:21 0.121 0

This example does not show editing the new/existing source files to implement the change. Many editing systems exist on Multics (emacs, qedx, ted).


Multics Code Compile Example

The next example shows using the mbuild command to compile revised source file(s) with symbol tables. You may need to fetch and compile related source modules with -table (even if those sources are not being modified) to obtain a set of executable objects that can be tested using probe. If your modified source references entry points in other objects of the bound segment, that other object may need to be fetched and compiled if those entry points are not retained in the bound segment.

In this simplest case, mbuild is used to compile translator_temp_.pl1 with symbol tables for probe debugging. translator_temp_ is self-contained, with no references to other objects in its bound segment. A revised translator_temp_ containing a new entry point may be tested by compiling the revised source without binding the resulting object into its bound segment. The example stops after the mbuild compile request has been performed. 

mbuild

Installation_directory: >udd>m>gd>w>temp

           Scanning, with read of any build_script...


mbuild:  analyze

---------- clean -all


---------- progress


   COMPLETED   REQUESTS for Builds
   ---------   ----------------------------
               set -desc   or    read -desc
      yes      scan      and/or  read
      yes      analyze
               compile
               archive_prep
               install_ec

mbuild:  compile -table

---------- pl1 translator_temp_.pl1 -ot -table

PL/1 33f

mbuild:  ls

Segments = 3, Lengths = 7.

re     2  translator_temp_
rew    3  translator_temp_.pl1
rew    1  bound_proj_admin_.bind

mbuild:  quit
r 16:15 3.869 232

Use the help command to obtain more information about using the mbuild subsystem. To get information about entering mbuild, type the Multics command: help mbuild

To obtain information about mbuild requests while inside mbuild, use its list_requests (lr) or help requests.

For detailed information with examples for the mbuild subsystem, see: MTB-1003: mbuild Command


Volume of a Proposed Multics Change

The process for changing Multics operating system software differs depending upon the magnitude of the change: the change volume. Several factors determine change volume:

  • lines of code changed.
  • extent of modified or new algorithms used in the change.
  • use of new or controversial strategies/approaches/conventions in the change.


For small-volume bug fixes following existing algorithms, the change needs only a Multics Change Request (MCR).


For larger changes, a Multics Technical Bulletin (MTB) gives details about the change, more carefully describing content of the change, documenting new user interfaces and include files, etc. Other reasons for an MTB include the following.

  • A small hardcore change might require a complex test plan to verify the change in all of its use cases. The MTB would describe those use cases, with test strategy for each case.
  • An over-arching MTB might be needed to describe a broad set of changes involving multiple MCRs. The MTB might list the planned MCRs, covering relationship between the changes, best order of installation, etc.


Once the design has been reviewed and accepted (perhaps with a revised MTB), then one or more MCRs are needed to request approval to make the large-volume change.

It may be necessary to actually make code changes and build the changed object segments to determine the volume of a change.


Creating a Multics Technical Bulletin (MTB)

[This subsection will be supplied in the future.]


Creating a Multics Change Request (MCR)

A Multics Change Request (MCR) document briefly summarizes purpose of a change to the Multics system, nature of the change, location of code and documentation to be changed, and testing planned to prove correctness of the change. The readers of each MCR use this information to judge whether the proposed change is a suitable addition to Multics software. The change auditor of each MCR uses the information to judge whether the proposed change: is implemented as stated; includes only items described by the MCR; follows coding standards and guidelines; adheres to Multics security and privacy rules; etc.


This subsection outlines the steps for creating an MCR document.

Download one of these templates to your personal computer.


Fill in the template with information describing the Multics change. Information needed for this template includes the following:

  • An MCR Number (identifying the new MCR)
  • A Multics Ticket Number (summarizing the change/repair)
  • Description of the change in the MCR
  • An mbuild build script identifying which Multics code will change.
  • Documentation for any changed user interface(s).
  • Discussion of how the change has been tested.


All of these items are needed so the Multics community can review and understand the change, and judge whether it is an appropriate new Multics feature, repair, or deletion. And so the auditor can understand the intended change and compare it with actual lines of code changed, documentation and testing results presented in the MCR, etc.

Other than Multics Ticket Number (described above under File a Multics Bug), the method for obtaining each item is described in the subsections below.


Once the MCR is completed, export it to a PDF segment which will be added to the Multics Wiki web site for review and comment.


Getting an MCR Number

MCR numbers are reserved/registered using a web service located at https://swenson.org/multics/mcrs/. This web service is maintained by Eric Swenson. In order to register an MCR, you must have an account on this web service. Send email to Eric Swenson to ask for an account.

You can read the instructions on the main page of this web site (unless you already know how), and select the "Allocate New MCR" menu item to allocate a new MCR. Provide a title and description of the change. You do not need to specify one or more ticket numbers in the description, since once you press the Allocate button, you will be presented with another form that allows editing of the information you submitted. That form will also show you your newly allocated MCR number.

On the MCR Edit form, you can press the "Add ticket" button to add a ticket (either a Multics Trac ticket or a DPS8M Gitlab ticket). When adding a ticket, you can specify either the ticket URL or simply the ticket number. If you choose the ticket number option, be sure to specify which type (Multics or DPS8M), and the URL will automatically be generated. The Multics Ticket number should have been obtained as the first step in Changing Multics: the step called File a Multics Bug.

You can also edit various fields, and provide the URL to your MCR PDF, if it has been hosted somewhere. You will not be able to add installation IDs or hardcore designators to your MCR -- this is done by the person who will eventually install your MCR-approved code on the Gold Hill Multics (GHM) system.

If you make any changes to the MCR fields, be sure to click the Update button to save those changes.

Once you have an MCR number allocated, open your downloaded MCR Template to begin a new MCR.

Place the MCR number (obtained above) in the new MCR document:

  • in the master heading line.
  • in the Subject line of the new MCR document, along with a title for this change.

Place your name in the Author line of the new MCR document.

Place the current date in the Date line of the new MCR document.

Place a link to the Multics Ticket number(s) associated with this change in the Multics Ticket line of the new MCR document. Both macOS Pages and MS Word will convert entered text that looks like a linkURL into an actual link. Multics Ticket URLs have the form shown here for ticket 214: http://multics-trac.swenson.org/ticket/214


Save the template with this change in a new file: MCRnnnnn where nnnnn is your assigned MCR number.

Describing the Change

First section of the MCR are few introductory paragraphs stating reasons for the change (fix a bug, need for an enhancement, etc.). These paragraphs should describe the nature of any bug; or discuss need for an enhancement with a high-level description.

For a large volume change, provide a link to the MTB giving details of the change.


Second section of the MCR, titled: Proposed Changes, gives details about the change. These include:

  • Description of how main source files affected by the change will be updated, added, or deleted.
  • Discussion of any algorithms used by these source that are new or changing.
  • Discussion of any impacts of the change on other Multics software (if any impacts are known).

An mbuild Build Script describing exact contents of the change.

  • A Description: section (just before the Installation_directory: label) containing a small (bullet/lettered) list summarizing nature of the change. This is primarily information for the installer. This description should refer to this MCR number. (Sometimes, the build script segment name includes the MCR number.)
  • Segments that are changing.
    • bound segment(s) containing sources being UPDATED, ADDED, or DELETED.
      • bind file changes in such bound segments.
      • source component changes.
    • unbound segment(s) being UPDATED, ADDED, or DELETED.
    • include and/or info segments being UPDATED, ADDED, or DELETED.
  • Target library containing each of these bound, unbound, include, and info segments.

See Creating an mbuild Build Script to learn how mbuild helps in creating such Build Scripts.


Third section of the MCR, titled: Testing, gives details of tests run to validate the change, report of testing results, etc.


Fourth section of the MCR, titled: Documentation, gives contents of any new or changed info segments. These might include new or changed info segments describing commands, subroutines, subsystem requests that are changing (or other help topics). Or they might include Multics manual errata files (e.g., ag91.errata.info) describing changes to documentation needed because of the changes.


Final section of the MCR, titled: Version History, is an optional section. If used, it consists of a table describing current and earlier versions of the MCR. Fields include: Date, Revision, Author, and Comment (purpose of each version, or how that version changed content of the MCR from earlier versions, etc.).


Creating an mbuild Build Script

The subsection above titled Change Multics Code / Build Revised Objects gave an example using the mbuild subsystem to build test versions of a changed Multics source module. The mbuild subsystem uses an optional Build Script file to specify: source modules being changed/added/deleted; any bound object containing the source modules; include file and info segment names; and target library for all these items.

  • For changes to segments existing in the Multics Libraries, mbuild can locate library objects with the same name, and can usually supply exact Build Script entries. For some info segments, a library object with the same name as a changed info segment may be found in several different library directories. In such cases, the Build Script can be edited to choose a specific target library.directory value.
  • When deleting segments from the Multics Libraries, the user must edit a saved Build Script file to add the segment name to be deleted (including its containing bound object name, if any) followed by the word DELETE; mbuild will supply the target library. For example:
     Bound_obj: bound_info_rtns_ UPDATE;
      source:   help_rql_.pl1 DELETE;
  • When adding new segments to the Multics Libraries, mbuild tries to guess where in the libraries to place the new segments. It may not have sufficient information to guess properly. The Build Script can be edited in such cases to correct any "wrong" guesses.


The session below shows segments from the earlier example. mbuild recognizes the translator_temp_ object segment created for testing purposes, and asks if it may now be removed from the working directory. Then analyze and print requests show the Build Script lines that mbuild produced by looking for earlier versions of the remaining segments in Multics Libraries. 


pwd
>udd>m>gd>w>temp
r 14:51 0.326 0

list

Segments = 3, Lengths = 6.

re     2  translator_temp_
rew    3  translator_temp_.pl1
rew    1  bound_proj_admin_.bind

r 14:51 0.114 0

mbuild

Installation_directory: >udd>m>gd>w>temp

           Scanning, with read of any build_script...

mbuild (scan): Noting derived segment  Unbound_obj:     translator_temp_

mbuild:  analyze

---------- clean -all

  Derived-content segments eligible for clean:
     Unbound_obj:     translator_temp_

mbuild (clean): Delete the segments above?   yes

---------- progress


   COMPLETED   REQUESTS for Builds
   ---------   ----------------------------
               set -desc   or    read -desc
      yes      scan      and/or  read
      yes      analyze
               compile
               archive_prep
               install_ec

mbuild:  print

 Bound_obj:                bound_proj_admin_                 IN: sss  UPDATE;
     bindfile:             bound_proj_admin_.bind             REPLACE;
     source:               translator_temp_.pl1               REPLACE            compiler: pl1 -ot;

mbuild: q
r 14:53 3.611 113


If we now add a new info segment to the directory (one not existing in the Multics Libraries), mbuild does not know in which of the several info-related directories of the Multics Libraries to add the new info seg. mbuild creates a Build Script line for the new info segment, but sets its library.directory to UNKNOWN.info. The developer could save the Build Script to a file and edit the "IN: UNKNOWN.info" clause. A simpler approach is shown below: using the mbuild set request to specify a priv.info value. The set request is also used to add a description to complete the Build Script, which is then saved to a file: temp.mb 

list

Segments = 2, Lengths = 4.

rew    3  translator_temp_.pl1
rew    1  bound_proj_admin_.bind

r 15:03 0.266 0

copy <my_new_info_segs>translator_temp_.info == -name -acl
r 15:04 0.128 2

list

Segments = 3, Lengths = 6.

rew    2  translator_temp_.info
rew    3  translator_temp_.pl1
rew    1  bound_proj_admin_.bind

r 15:04 0.116 0

mbuild

Installation_directory: >udd>m>gd>w>temp

           Scanning, with read of any build_script...


mbuild:  analyze

---------- clean -all


---------- progress


   COMPLETED   REQUESTS for Builds
   ---------   ----------------------------
               set -desc   or    read -desc
      yes      scan      and/or  read
      yes      analyze
               compile
               archive_prep
               install_ec

The following segments have an UNKNOWN library:

  Seg(Info):               translator_temp_.info             IN: UNKNOWN.info  ADD;

Please resolve these library names before doing: compile, archive_prep, or install_ec.

mbuild:  print

 Bound_obj:                bound_proj_admin_                 IN: sss  UPDATE;
     bindfile:             bound_proj_admin_.bind             REPLACE;
     source:               translator_temp_.pl1               REPLACE            compiler: pl1 -ot;

 Info:                     translator_temp_.info             IN: UNKNOWN.info  ADD;

mbuild:  set -seg translator_temp_.info -library priv.info
 Info:                     translator_temp_.info             IN: priv.info  ADD;

mbuild:  set -description
Enter description (ending with a line containing only a period (.) character):
 Changes described in MCR10083:
 A) Add translator_temp_$empty_all_segments as a new entry point.
 B) Add translator_temp_.info to document this subroutine's interfaces
    online.
.

mbuild:  save

mbuild:  ..print **.mb

                    temp.mb   12/01/20  1506.2 pdt Tue


Description:
 Changes described in MCR10083:
 A) Add translator_temp_$empty_all_segments as a new entry point.
 B) Add translator_temp_.info to document this subroutine's interfaces
    online.

Installation_directory:  >udd>m>gd>w>temp;

 Build_script:             temp.mb;

 Bound_obj:                bound_proj_admin_                 IN: sss  UPDATE;
     bindfile:             bound_proj_admin_.bind             REPLACE;
     source:               translator_temp_.pl1               REPLACE            compiler: pl1 -ot;

 Info:                     translator_temp_.info             IN: priv.info  ADD;

mbuild:


Text of the temp.mb Build Script file (shown above) may now be copied into the Proposed Changes section of the MCR document.

Also, compare_ascii output showing any changes to info segments (or print output showing entire text of any new info segments) may be copied into the Documentation section of the MCR document. The mbuild compare request can generate compare_ascii output for any changed segments in the Build Script.

Submitting the MCR for Review / Approval

Review of an MCR involves the following steps:

  • Export the finished MCR to PDF format. (Most word processing applications provide a "Save as PDF", or "Export to PDF" or "Print as PDF" opoeration.) Be sure the file name begins with the MCRnnnnn string (e.g., MCR10083.pdf or MCR10083_v1.0.pdf).
  • Send email to Eric Swenson enclosing the MCR PDF file, requesting that it be added to the Multics-Wiki web page listing MCRs.
    • Eric will reply to this email, giving a URL for that MCR document (as stored on the Multics-Wiki web server).
  • Send email to the mailing lists below requesting "review and approval" of changes proposed in the new MCR. Reviews are conducted via emails between all reviewers on the list. The request for review email should contain the following information.
    • URL for the MCR PDF file (as supplied by Eric's reply, above).
    • Brief summary of the MCR, so potential reviewers will have some idea what software is being changed/added.
    • Method for entering review comments or approvals. Suggested text: Please "Reply All" to this email, giving your comment or approval information.
    • Closing date for the review period.
      • Allow at least 1 calendar week for reviewers to see your request, review the MCR PDF, investigate any potential issues, and reply.


MAILING LISTS:

  • dps8m-users <dps8m-users@lists.sourceforge.net>
  • dps8m-developers <dps8m-developers@lists.sourceforge.net>
  • multicians <multicians@groups.io>


An example of a past request for MCR email is shown below. 

Hello Multicians:
 
Please review and approve/comment on a new: MCR10083 - translator_temp_$empty_all_segments proposing an additional entry point for a tool subroutine interface.  This tool provides extremely low-cost storage allocations for many administrative and user tools.
 
The new entry point will be used by a new version of help_ to speed parsing of info segments.
 
You may comment on this proposal by replying to this email, copying the entire mailing list for points that should be presented to all reviewers.
 
REVIEW ENDS:  Monday November 30  (extra time allowed because of the Thanksgiving holiday)
 
Thanks for your interest and review.
 
Gary Dixon



Announcing Results of the Review

When the review period ends, the developer sends a second email to the mailing lists reporting results from the review. In most cases, this mail simply reports that the review period ended with no one objecting to installation of the change. If there were adverse comments or concerns about the change, those should be summarized in this mail. The mail should answer each issue raised, or give a plan for investigating and addressing particular issues in the near future.


MAILING LISTS:

  • dps8m-users <dps8m-users@lists.sourceforge.net>
  • dps8m-developers <dps8m-developers@lists.sourceforge.net>
  • multicians <multicians@groups.io>


An example of a past review summary is shown below. 

Hello Multicians:
 
MCR10090 is now approved for auditing and installation.  Most reviewers approved this change. 
 
Comments focused on methods to encourage sites to upgrade to a dps8 simulator version including the repair for the underlying problem being avoided, plus many other repairs and enhancements. 
 
The dps8-developers team is merging the repair for the underlying simulator bug into the dps8m master branch; and also investigating methods to encourage upgrades to newer dps8m master branch simulator versions.
 
Thanks for your review efforts.
     Gary Dixon


Final Preparations for Audit

When a change proposal has been approved for installation, the developer should check completeness of the installation directory for the change:

  • Ensure that all source, include, bind, and info segments are properly identified in an mbuild build script file in the installation directory.
  • Ensure that each such file includes a new history comment briefly describing nature of the changes.
    • Include the MCRnnnnn number as the history comment -approve field.
  • Ensure that the auditor has access to the installation directory (and to any sub-directories includes test cases or other supporting materials for the audit).
    • s access to directories
    • re or r access to any object segments or data segments needed for testing.
    • rw access to all source files listed in the build script, so the auditor can add an audit field to each new history comment, indicating that the module has passed the audit.

When preparations are complete, notify the auditor that the changes proposed in MCRnnnn are ready to audit. Give location of the installation directory (Multics site and pathname). Let the auditor know that adequate access has been granted to allow audit fields to be added as source files are audited. Ask the auditor to notify you when the auditing is completed.


Alert Multics Installation Administrator

When changes in the installation directory have been audited, notify the Multics installation administrator that changes proposed in MCRnnnnn are ready to install.


The administrator will copy your installation directory to a staging directory, then install the changes into the Multics Libraries. He will then notify the developer that the changes have been installed.


Finish the Installation

When the Multics Installation Administrator notifies the developer that the changes have been installed, the developer should then finalize the installation.


Update all Tickets (bugs) corrected by this installation:

  • Change the status field to Fixed
  • Ensure that links to the Multics Change Request(s) associated with the change are included in comments for each Ticket.
  • Change the Milestone field to the upcoming (yet-to-be-released) Multics release number, if that release has been defined by the Multics Installation Administrator.
    • If no appropriate release name appears in the selection list for the Milestone field, ask the Multics Installation Administrator (Eric Swenson) what to specify in the Milestone field.


Delete the installation directory associated with the proposed changes:

  • Optional: verify that all change components were correctly installed.
    • Hint: use the mbuild compare request to compare sources in the installation directory with their equivalent files in the Multics Libraries. They should differ only in the new history comments: an installation field will have been added as part of the installation process.
  • Optional: delay deletion of your installation directory for several weeks, in case questions arise about the installation.


This step completes the entire process for making a change to Multics. Thanks to the developer, MCR reviewers, auditor, and installation administrator for their cooperation in enabling a smooth implementation of such changes.

Retrieved from "http://multics-wiki.swenson.org/index.php?title=Changing_Multics&oldid=1310"