mbuild should support changes to Include segments in a better fashion

[Gary Dixon]

When an mbuild change_set makes changes to an existing Include segment, it currently allows source programs that reference that Include segment to be combined with the change_set in the usual fashion.
Each source program that references the changed Include segment must be examined to determine impact of the Include segment changes on the source program code, and on the data structures referenced by that source program.

• Fetch the including source program into the build_directory.
• Decide what changes may be needed in that source to accommodate changes made to the Include segment.
  • CASE 1: Sometimes the changes made to the Include segment have no impact on the source program or its compiled Unbound_obj segment. So that source program can be removed from the change_set.
  • CASE 2: The source program code must be modified to work properly with the changed Include segment. Both the modified source program and its compiled Unbound_obj segment need to be REPLACEd by the change_set.
  • CASE 3: The existing source program requires no modifications to work with the modified Include segment, but data declarations in that source program will be reshaped by mods to the Include segment. This will affect the Unbound_obj segment compiled from that unchanged source program. So only the Unbound_obj segment needs to be REPLACEd.

While this examination of including source programs proceeds, it can be difficult to track progress of the examination, especially if it cannot be accomplished in a single review session. It can be difficult to remember which including sources have been examined, and what the examination determined. This tracking can be complicated if an including source program is not affected by changes to the Include segment, but needs to remain in the change_set for other reasons. A better process is needed for conducting such examinations.

This change ticket proposes that mbuild be enhanced to support use of a better process for incorporating source programs referencing changed Include segments into the change_set of an mbuild build_directory.

An improved process might include the following steps to divide source programs that reference the changing Include segment into three subsets.

1. Compare changes made to the Include segment to determine what affects those changes might impose on including source programs.
   • If the changes involve only additions of new data structures, or data constants, the developer may immediately decide no referencing source programs can be affected by those additions. Stop the examination.
   • Otherwise, referencing source programs may need to be individually examined to determine if changes are needed. Continue with step 2.

2. Fetch a copy of all referencing source programs into a subdirectory of the build_directory (call it the recompile directory).

Examine each such referencing source program. There are actually four possible determinations that can be made by the examination.

• CASE 0: If the source program is already being REPLACEd by the change_set for other reasons, then examine that modified source to determine impacts of Include segment changes on that modified code. If further changes are needed because of the Include segment mods, make those changes in the copy of that source that is already in the build_directory; and delete the copy of that source from the recompile directory.

• CASE 1: Otherwise examine the library version of the referencing source program in the recompile directory. If it is unaffected by the Include segment changes, then delete that source from the recompile subdirectory. No further examination is needed, and that source is not part of the change_set. Delete the source from the recompile directory to record that exam result.

• CASE 2: If the library version of the referencing source program needs no changes, but its declared data items will be affected by Include segment changes, then the Unbound_obj segment compiled from that source needs to be part of the change_set. Place a symbolic link to the recompile directory copy of that source program in the build_directory to record this exam result. Existence of that link causes mbuild to recognize the source program as part of the change_set. Because the link target points to a version of the source that is identical to the copy in the target_library, the source program does not get updated in the LIBRARY.source directory (or one of its source_arch archives); but the source does get compiled as part of the change_set and its Unbound_obj therefore does get installed into the LIBRARY.object, and incorporated into any Bound_obj segment re-bound by the change_set.

• CASE 3: If the library version of the referencing source program requires changes to accommodate the Include segment changes, then move that source program up from the recompile directory into the build_directory. Make the required accommodating changes in that moved source segment. Being a modified source in the build_directory, the source program then gets updated in the LIBRARY.source directory, and its compiled Unbound_obj does get updated into LIBRARY.object and re-bound into any containing Bound_obj segment.