From: Ornella Di Rosa Subject: CMZ & FAQ To: dalamb@qucis.queensu.ca Date: Fri, 29 Oct 93 16:22:43 MET Mailer: Elm [revision: 70.85] For more information on CMZ please contact me at the following e-mail address: codeme@cernvm.cern.ch Thank you, Ornella Di Rosa s.a.r.l. CodeME 14, Rue de l'Eglise fax: +33 50 42 09 14 F-01630 St Genis-Pouilly e-mail: codeme@cernvm.cern.ch ============================================================================= What is a Source Code Management and Version Handling System for ? ------------------------------------------------------------------ CMZ is a source code management system (SCMS). However, the word 'code' here signifies any kind of source text to be manipulated - be it a compilable program (the more familiar case), documentation or data. Thus, CMZ can benefit a publishing house as well as a software factory if version tracking is required. In the case of software, consider the development of a one-person, single-variant project which evolves with time. Here, the basic requirements of the SCMS are the use of a good interactive editor (preferably your usual one), the ability to audit the advancing source code versions, and a rebuild facility which will reliably generate the corresponding application versions. If the project is large, the rebuild must be incremental - recompiling the modified modules. Naturally, a history file should be kept so that one can immediately see how and why updates were made. As everyone knows, new updates are not always perfect so it is highly desirable that the SCMS allow any previous update to be easily canceled or corrected. If there are several developers working on the same project, it becomes necessary to implement some form of synchronization control to prevent them from 'treading on each others feet'. In a local environment, a simple source file locking mechanism may suffice by preventing any two developers from simultaneously working on the same module. However, this is too restrictive if developers and maintenance engineers work independently (for instance, in the case of geographical isolation), so the SCMS should be able to merge individual modifications - localizing any 'conflicts' of course. The application may, as well, be multi-variant - for example the development of a multi platform product or a baseline system to be customized. This is the difficult case where the SCMS needs to allow the easy generation of any required variant/version from the relevant source code. It is important that the source code be structured in such as to LIMIT THE DUPLICATION OF COMMON CODE to avoid the subsequent escalation in maintenance costs. Finally, with the trend towards open computing, the SCMS should also be available over the widest possible range of computers and operating systems. How does CMZ score ? -------------------- CMZ and its underlying philosophy were conceived in the domain of High Energy Physics where many software projects fall into the 'worst case' scenario. It is not surprising, therefore, to find that CMZ is very strong on configuration management and change control. The text to be managed is, in fact, structured into a hierarchical database which exactly reflects the evolution of the application. Consequently, complex situations can be handled in just as natural a way as simple ones. Update sets do not physically modify the target modules so that various updates can be tried out in parallel. This fact and the facility for 'merging' update sets makes CMZ equally powerful in either a local or distributed environment. With its fully integrated macro facility, the CMZ user interface offers the possibility of 1) a basic command mode operation, 2) a script mode (with logic, arithmetic and looping) for experienced users, and even 3) the 'point and click' mode for beginners and casual users. The diversity of computer platforms in the physics world is reflected in the fact that CMZ is already available and running on the most important operating systems - MS-DOS, WINDOWS/NT, UNIX, VMS, VM and MVS. In short, CMZ is the kind of powerful, portable tool needed in today's world of increasingly complex, multi-vendor computing environments. The Design Strategy ------------------- CMZ sees the whole pool of text to be managed as a set of nodes in a hierarchical data structure - 'DECKs' in the CMZ terminology. The leaf nodes correspond to the original material (compilable units, ...) whilst the inner nodes contain update sets, variant alternatives and the structural links defining the different versions and variants. All update sets are stored as differences (simple line edit commands) so that they can also be the object of future updates: +------+ /-----------| u11 |---------{ m1 } +--------------+ / +------+ | Variant A |/ +--------------+\ \ +------+ \ -----------| u21a |------\ +------+ \ \ \ \ +--{ m2 } / / / +------+ / /------------| u21b |------/ +--------------+ / +------+ | Variant B |/ +--------------+\ \ \ +-----+ +-----+ -| u32 |--------| u31 |----{ m3 } +-----+ +-----+ <-----Version 1--------- <-----Version 2------------------- In this example, the project comprises three original text modules m1, m2, and m3 . Module m1 belongs to variant A, m3 to variant B, and m2 to both A and B. For version 1 release of variant A two update sets are provided - u11 (acting on m1) and u21a (on m2). Version 1 release of variant B includes u21b and u31. It is the structural links which select the appropriate update for m2 depending on the project variant. As we have already stated, the update sets are textual and can themselves be the object of further modification. But, this is not all. The variant definitions and the structural links themselves are also textual so the whole project structure and content is completely visible and controllable. Updates are usually a response to unexpected problems encountered during development and maintenance. On the other hand, variant differences which are recognized at the design phase are implemented differently using one of the other CMZ features - language independent optional code: +IF,variant_A CALL the_doctor; +ELSE CALL the_priest; +ENDIF or code inserts of the type: +IF,variant_A INCLUDE text_A; +ELSE INCLUDE text_B; +ENDIF With these 'push and pull' capabilities, it is easy to see that any level of variant complexity can be accommodated and in the most appropriate manner. Needless to say, the more effort allocated to the initial design the fewer headaches at maintenance. Most SMCS's can handle single variant software up to a limit. But even here, not many offer full control over previous update sets - for instance restoring deleted code. However, with CMZ, this is trivial since an update set can also act on previous updates as well as original material. In the example, u32 may well cancel a delete instruction in u31 without having the user re-type the deleted lines. Do I Need to Use All This ? --------------------------- Although CMZ offers all this power for source code maintenance, you can use as little of the functionality as is necessary without learning everything. Not everyone tracks multiple releases, merges independent correction patches or deals with multi variant software. On the other hand, most users need an auditable update history and an optimal, reliable re-compile and build facility. Many existing CMZ users work for a short duration and so the learning curve for CMZ had to be rapid. As the basic principles are quite logical and the interactive commands easily customized, new users usually have very little problem setting up a comfortable, safe working environment in a relatively short time. The comprehensive build-in help facility answers most immediate questions. Import and Export ----------------- To facilitate the integration of existing software applications into CMZ, an Import command will read existing text (code, data, documentation, ...) and automatically divide it into logical DECK's before converting it into CMZ's internal structure. The user may then interactively introduce the module dependencies to automate the build process, or to define application variants if these exist. So it is not necessary to wait for your next project before benefiting from CMZ! A corresponding Export function is provided for extracting raw code or data from a CMZ structure. This is useful both for documentation and the transfer of code to an installation not equipped with CMZ. An Interactive Session ---------------------- The users login file usually defines the command aliases and author identification (for the update history). Then one normally opens one or more CMZ files depending on the size of the project. The next step could be to define the project and possibly the variant of the software or documentation to be treated: "SELECT PROJ DOS DEBUG" will select project PROJ, variant DOS, with optional DEBUG included. The decks are disposed in a two level directory type structure with such commands as CD for navigating between directories. The command DIR lists all the DECKS in the current directory (with cycle numbers). Multiple cycles are normally kept for security. DECKs can be edited, using the users normal editor, either by name or via the buffer list. The buffer is a list of DECK names and is typically filled via commands such as GREP (SEARCH) for localizing all occurrences of the given text string (including regular expressions). The command MAKE will recompile all out-of-date modules (normally those modified during the current session). When the updated code seems satisfactory, YCORR can be used to generate an update set of the differences between the latest and previous cycles of the modules contributing to the project variant. It is worth mentioning that it is sometimes desirable to edit in the 'deltas' manually (the previous case of deleting a delete instruction). Automatic Builds ---------------- An efficient way to use CMZ is to make an object library which corresponds to the latest 'freeze' of the software. Henceforth, each user keeps his modifications locally. These may take the form of completely new versions of modified modules or they can be converted to update set deltas using the command YCORR. The fact that update sets can act on earlier ones raises an important issue concerning the incremental build. Because successive update sets are 'chained' in this way, it is mandatory that any new update commands should be tracked through to the end so that all the compilation units ultimately modified are flushed onto the output stream (for compilation). CMZ does this - even to the extent of outputting those modules whose 'included' text material is changed. No other SCMS offers this power. Audit Trail ----------- As we have said, a user wishing to use CMZ identifies himself either by the AUTHOR command or via his setup procedure. This allows CMZ to keep the modification history up to date DECK by DECK. This history is inserted into each DECK as comments and is visible along with the contents of the DECK. This information is often useful when analyzing a new update. The command LMOD displays all the modifications made by a given user - optionally between any two dates. For example 'LMODS Smith 13.15' lists all modifications made by user Smith since today from 13h15m and 'LMODS -Smith -V 1.28/03' lists all modifications by all users except Smith after the version 1.28/03. The UPDATE Feature ------------------ CMZ permits the storage of updates to any level. This feature is extremely important in an industrial environment where a large application must be maintained concurrently over many release cycles. However, in the initial development phase, the code evolves so fast that this approach is not the most ideal. In this case, it is better to regularly use CMZ's UPDATE facility which physically merges correction sets into the original modules thus effectively effacing the update history of the application and starting again with a clean system. Macro Definition Language ------------------------- The CMZ user interface package includes a powerful macro facility which, amongst other things, allow the customization of commands (dir