====================================================================
What is MM
MM stands for Modules Manager and it is a software module composed mainly of script tools that implement a wrapper layer for accessing the subversion repository for the software developments for CTIO,SOAR and LSST-OCS. In these tools the particular policies and practices of the group are implemented, basically the version control over meaningful software components named modules, which can be re-utilized in multiple applications and projects.
====================================================================
MM usernames and passwords
The user issuing subversion commands into the repository, directly or through MM, must be registered as a valid user in the repository, with a password for that system. The default username to access the repository is $USER. If this username is not registered in the repository, after entering an invalid password the subversion client will interactively request a new username and password. This username/password will be kept cached during the session, and the following commands to the repository will be performed under that name.
====================================================================
How to obtain MM
Provided that the subversion client is installed in the system, MM can be obtained and installed with the following command lines:
svn checkout https://139.229.115.227/svn/trunk/MM cd MM make install
The set of scripts will then be installed in the directory ~/bin/ which needs to exist and to be part of the user's path.
====================================================================
MM configuration
One important file installed in the ~/bin/ directory is MM.config. In here a set of variables are defined for the MM context, and the user may want to modify some of them, for example EDITOR to specify her/his favorite text editor during the annotations.
====================================================================
How to start using MM for archiving new modules.
Most probably your application is composed of several modules that you want to maintain in the repository independently. The repository system requires that the source files of a module are organized inside a directory with the name of the module. MM will handle all the files and subdirectories inside the module's main directory as a single unit, all of them belonging to the same version identifier. The only condition that MM imposes on the module, is that inside the main module's directory there must be one standard file, ChangeLog?.txt, which is used to keep the version number of the module and the whole history of changes. Another standard file, INFO.txt, is automatically added by MM, and it is a keyword-value text file with basic information regarding the module, human readable as well as parseable. The generation and update of these two files is assisted by the command MM_Log from the parent directory of the module in question:
MM_Log module-name-directory
See below for more details on this command. After this the module is ready to be archived in the repository, with the command MM_Archive from the parent directory of the module in question:
MM_Archive module-name-directory
If this is the first committment of the module in the repository, it will be added into the "trunk" directory of the repository under a directory with the module name, as well as in the "tags" directory under a directory with the module name-version. The function of the "trunk" is to keep the official version of the module, while "tags" keeps a copy for each archived version.
====================================================================
How to start using MM to modify an existing module.
First of all you need to get the module from the repository:
MM_Copy module
All the following commands are executed from the parent directory of the module. For the details about each command see the following section "MM commands" in this document.
After applying some changes, you can verify which files/directories of the module have been affected:
MM_Check module
Then you need to analyze and take notes about the specific changes in the affected files:
MM_Diff module
After that you are ready to write the comments explaining the changes, as well as assigning the new version identifier:
MM_Log module
Finally, the module is ready to be archived:
MM_Archive module
The new module-version directory is created into the "tags" section of the repository. If you want to also update the trunk version of the module, you can use this alternate command line with the extra argument "-trunk":
MM_Archive module -trunk
====================================================================
MM commands
MM_Trunk [module] Returns the list of modules already under control in the main trunk of the repository, along with the version identifier for each one of them, corresponding to the official version. If module is provided, the command delivers the official version identifier for that module only.
MM_Tags [module] Returns the list of tags or version identifiers archived in the repository for the specified module. If module is not provided, the full set of tagged modules is returned.
MM_Copy module [version] Checks out the specified module and version from the repository, producing a local copy in the current directory. If the version identifier is not given, the current version from the main trunk is obtained. Normally the trunk version is the last archived version in the tags directory. And it will always correspond to the last archived version if only MM tools are used to wrtie into the repository.
MM_Version [module] Returns the version identifier for the local copy of module in the current directory. If no module is provided, MM_Version returns the version identifiers for all the modules present in the current directory.
MM_Check [module] Returns a summary of the current status of the local copy of module in the current directory; origin of the copy, repository reference, files added, deleted and modified. The output of this command is very suitable as a template for the commentaries to be included in the change-log file for the new version to archive. If no module is provided, the status is given starting from the current directory.
MM_Diff [module] Returns the result of the comparison of the local copy for module against the corresponding version in the repository. For the text files, the differences detail is printed out in the standard output; the user can redirect this output to a file of course. For the LabVIEW files, a special tool is invoked to show the differences in the LabVIEW editor, one file at a time, and only for the affected files. If no module is provided, the differences are given starting from the current directory. This command is finished once the user closes the last LabVIEW-diff.
MM_Log module Opens the change-log file in the favorite text editor (as specified in ~/bin/MM.config) adding in the top a template to be filled by the user with the changes report for the new version before archiving it. The first line includes an automatic time-stamp, and the user must add the new versionn identifier at its end. The version identifier must be composed of alphanumeric segments separated by ".". The character "-" is not permitted. After closing the change-log file, the info file of the module is opened by the editor giving the chance to edit the fields if necessary. Some of the fields such as version and date are updated automatically. The command is finished once the user closes the info file.
MM_Clean module Performs a search in the local copy of module of the temporary backup files such as *~ and gives the chance to the user for deleting them. This command is strictly not necessary because when archiving the new version these files are ignored, but it may help to have a clean local copy anyway.
MM_Archive module [-trunk] [-new] Archives the module in the local copy into the repository. This command checks if the minimum conditions of the local copy are met before proceeding to the check-in. Spaces in the file names are not allowed by default. If the module is a new one, not existing one with that exact name in the repository, it checks if the corresponding change-file exists and it has a valid version identifier. The module is then stored in the main trunk and in the tags directory of the repository. If the module is already present in the repository, it checks if the change-log file has been updated and the new version identifier is not already archived in the tags directory of the repository. The new version of the module is then stored in the tags directory. If the optional switch "-trunk" is used, then the trunk copy of the module is updated with this new version. If the module already exists in the trunk, but the new version is new from scratch, unrelated to a previous archived version, the optional switch "-new" allows to archive it without the need to start applying changes from an older version.
MM_UpdateTrunk module version Updates the trunk version of the specified module (official version), with the specified version previously archived. There is no need for a local copy of the module, this command works only with the repository.
====================================================================
