Extracting threads & generating thread scripts

Threads are defined and recorded to gather the indicated file/version combinations. The purpose may be to define a set of files for a full compilation of source code or to simply record a "snapshot" of the database at a given time.

If the file group for which the thread is being created contains branches, you may want to consider the extraction results of the multiple version selection for trunks and branches. As described in "Trunks vs. branches" on page 133, the choices are "Allow selection of one trunk OR branch" (default) and "Allow selection of any trunk AND branch".

If a file included in a thread was chosen based on the selection "Allow selection of one trunk OR branch" then the extracted version of the file will be the one indicated in the thread.

Based on the example outlined in "Trunks vs. branches" on page 133, the extracted version of file `apple' would be 1.5 as indicated below:

+       apple           1.5             1.5     
        apple@1.2.1     1.2.1.2         --.--
        apple@1.4.1     1.4.1.6         --.--   
        apple@1.6.1     1.6.1.2         --.--

If files included in a thread were chosen based on the selection "Allow selection of any trunk AND branch" then the extracted version of the file will be the LAST included version that appears in the thread.

+       apple           1.5             1.5
+       apple@1.2.1     1.2.1.2         1.2.1.2 
+       apple@1.4.1     1.4.1.6         1.4.1.6
        apple@1.6.1     1.6.1.2         --.--

In this case, version 1.5 of `apple' will be extracted to the destination directory which will then be overwritten with version 1.2.1.2 and finally overwritten with 1.4.1.6.

The threads program allows users to directly extract read-only copies of included files to a specified location or to generate a shell script which when invoked will extract read-only copies of included files.

Both the Extract Thread and Generate Script options are available from the Utilities menu. This menu is present on both the main display and the Edit Threads window.

If the Extract Thread option is selected, the following panel appears.




The top left corner of the panel contains a list of all the threads for the indicated Razor group. As different threads are highlighted on that list, the scrolling list in the top right of the panel will update to show various versions of the thread. The Title and Description fields will also update as necessary to show what was entered at the time of creation.

The Set output directory button allows the user to navigate to the directory where the files should be placed. The directory will be populated according to the Thread_rules file described in the section entitled "Thread rules" on page 140.

Alternatively, if Generate Script is selected from the Utilities menu, the following panel will appear.




The Thread and Version lists are as described for the Extract Thread panel. The Title and Description fields will also update as necessary to show what was entered at the time of creation.

After selecting which thread/version the user would like to generate a script for, the destination directory for the thread script must be specified. This can be done by either typing it directly into the Output script for field, or by using the Set output directory button (which brings up a nice interface of its own).

The script that is being generated will gather together the indicated files, but it needs to know where to extract the thread to. The Extract thread to field on the panel serves this purpose. Whatever text is entered there is what the script will use as the top of a directory tree. As such, it can be either an absolute path, or it can work relative to where the user is when the script is executed. It may also take advantage of shell environment variables (such as $HOME).

When the Ok button is selected at the bottom of the panel, a shell script will be generated with the name rz_build<threadname>_v<version>. For example, in the screendump shown above, a script named rz_build_Release_v1.2 will be placed in the directory /home/snuffy/ivory. When that script is executed, it will use the directory /local/buildarea as the base for its activity.

Thread rules

All the files within a thread do not need to follow the defined file hierarchy. It is possible to have the files distributed into a directory tree of your design and choosing. We don't recommend use of this approach except in unusual situations.

NOTE: In other words, your thread should emulate your file hierarchy.

The Thread_rules file in the Tables directory establishes the rule set for directing where each file in the thread should be placed. The file itself is similar to a series of case statements which determine the destination subdirectory name based on the attribute settings of each file.¹ A short series of examples are perhaps the best means of illustrating how thread rules would be used.

• If you expect that all of the files within a group can simply end up at the base directory itself, then all that's necessary is a thread rule which catches all cases as the default, as shown here.

  default:.
  
  

If the group contains folders, then subdirectories corresponding to the folder names will be created under the base directory. The individual files will be placed into these folders.


• If we expand on the above idea a little, we can envision a similar situation, except that "Doc" files should be put in a subdirectory called "notes".

  Filetype:
      case Doc:notes
  default:     .
  
  

• It is also possible to use the settings of ONE_OF_MANY attributes as variables that are expanded when the script is generated. If we wanted to implement a directory structure where source code was scattered across one of several possible subdirectories, then we may choose to have configured the group to have a ONE_OF_MANY attribute called "Subdir". We could then use rules such as the following...

  Filetype:
      case Header: #Subdir#
      case C:      #Subdir#
      case Doc:    notes
  default:      .
  

NOTE: The Thread_rules file applies to both the Generate Script and Extract Thread buttons on the Utility menu.

Changing how files are extracted

When new groups are created, a file called Thread_script_template.sh is placed in the Tables directory for the related thread. This template contains the method for file extraction. When a thread script is generated, this file is copied to the destination script name, and the actual commands to get the read-only copies of the files are appended to the file.

The lines that are added to the script are of the form shown below:

get_file <filename> <version> <destination> <is_binary> <new_name>

...where <filename> is the file that is being extracted, <version> is the extracted version of that file, and <destination> is the location to put the extracted file. The parameter <is_binary>, can have a value of either "0" or "1", with "1" meaning the file being extracted is a binary file ("0" means it's a text file). Lastly, the parameter, <new_name>, will only be used if the thread needs to extract a file that had been removed from the database since this version of the thread was created; the archived filename will have to be renamed to the original name.

The actual definition of the get_file command is what is provided by the template. By changing the template file, you can in effect change the natural behavior of what the generated script will do.

For example, using the default template, as the script runs it will overwrite any existing file that happens to already be in the destination. You may opt to rewrite the script such that the get_file command will overwrite the existing file only if it passes some tests (which are up to your discretion).

NOTE: Changing this file will only effect the behavior for extract's that create a script. It does not effect the GUI thread extract.

Before changing the template, it is suggested that you first study and understand the one provided. It is well commented, and should serve as a good example.

In addition to the general template provided (above), a second script is placed into the Tables directory at the time the group is created. Thread_script_after_template.sh. The contents of this file are appended onto the end of the final script being generated.

The sample automatically provided does nothing more than `exit 0'. You are free to change the contents to be whatever you wish. A common example is to have the script kick off a compilation or massive print job after all of the files have been properly retrieved.

¹ It is common to use folders for organizing development projects while extracting and building into a single folder.