Draft: MLDesigner and LinCVS

Draft: MLDesigner and LinCVS 17th April 2003 Daniel Zinn zinn@mldesigner.com MLDesign Technologies, Inc. 2230 St. Francis Drive Palo Alto, CA 94303 support : www.mldesigner.com/support http : www.mldesigner.com

Contents 1 General Overview 1-1 2 Preparing your system for CVS 2-1 2.1 System setup for using CVS........................... 2-1 2.1.1 Required software beside MLDesigner................. 2-1 2.1.2 Configuration............................... 2-1 2.2 User setup for using CVS............................. 2-2 2.2.1 Repository is accessible through local filesystem............ 2-2 2.2.2 Repository is accessible through ssh/rsh................. 2-2 3 Working with CVS 3-1 3.1 General information on how MLDesigner stores model information...... 3-1 3.2 Using a library that is maintained by another person.............. 3-2 3.2.1 Check a library out from the repository................. 3-3 3.2.2 Synchronizing your copy with the latest version inside the CVS repository 3-5 3.3 Managing a library with CVS.......................... 3-7 3.3.1 Importing a Model into CVS...................... 3-7 3.3.2 Changing a single module or primitive.................. 3-9 3.3.3 Changing a library............................ 3-10 3.3.4 Commit your changes.......................... 3-10 3.3.5 The log tree................................ 3-10 3.3.6 Adding files to the repository....................... 3-12 3.3.7 Creating a new primitve and adding it to the CVS repository...... 3-12 3.3.8 Removing files from the repository................... 3-14 3.3.9 Moving files inside the repository.................... 3-14 3.3.10 More people working on the same library................ 3-14 4 TODO!! 4-1

List of Figures 3.1 LinCVS showing the Checkout dialog..................... 3-3 3.2 LinCVS showing your library at the Workbench................ 3-4 3.3 MLDesigner showing the library view after checkout.............. 3-5 3.4 LinCVS showing Read only files which seem to be up to date......... 3-6 3.5 LinCVS showing Readonly files which are up to date............. 3-6 3.6 LinCVS showing files which need patch.................... 3-7 3.7 The MLDesigner File View dialog with the library to put under CVS control.. 3-8 3.8 LinCVS showing the Import dialog....................... 3-8 3.9 LinCVS modified files.............................. 3-10 3.10 Diff window showing differences between sandbox and repository....... 3-11 3.11 Providing a comment on the changes....................... 3-11 3.12 a sample Revision Tree.............................. 3-12 3.13 LinCVS showing a new directory in the Non-CVS files tab........... 3-13 3.14 Adding three new files to the repository..................... 3-13

List of Figures 2 LinCVS Documentation

List of Figures This document describes how to use MLDesigner with CVS via the LinCVS gui. It is illustated with example scenarios. You will be able to combine the powerful GPL-tool CVS with MLDesigner however, sometimes you have to take special care for CVS, but I think the version control mechanisms CVS provides are worth some unconvinience. 3

Chapter 1 General Overview CVS provides a common repository to store files and track of all changes that are made to the files inside the repository. Once the files have been loaded into the repository, CVS controls access to them and manages the update and revision process. Users can check files out of the repository for use and for editing/development with LinCVS. LinCVS also manages the process of updating files in the repository and adding new versions of the files to the repository. CVS allows multiple users to checkout and use the same file(s) simultaneously. The first step in using CVS is to import your MLDesigner model files into the repository. Once the files are stored in the repository, you (and your colleagues) can use LinCVS checkout copies of these files for local use, to update files in the repository, and to add new versions of these files to the repository. Since you do not work directly on repository files, the first step in working with these files is to check out your own copy of the files into your home directory. This local copy is called sandbox, since you are allowed to freely play with the model when it is in your home directory. For example, you can: use your copy inside the sandbox read only as additional library for MLDesigner synchronize your copy whenever you want to the newest version inside the repository (update) make changes to modules inside your sandbox and synchronize these changes with the repository s version (commit) At the beginning, this document describes the steps you have to perform as administrator and as user to be able to use LinCVS together with CVS. The following paragraphs describes the basic CVS operations you can perform: import, check out, update and commit focused on using CVS for MLDesigner models. At the end of the document, some special features of CVS are shown. You will be able to profit from the advantages a revision control system provides, however this small document can not cover all issues related to the CVS system. An all covering documentation for CVS is avaiable at www.cvshome.org 1. 1 every minute you spend in reading documentation will pay off, especially when starting using CVS.

Chapter 2 Preparing your system for CVS 2.1 System setup for using CVS 2.1.1 Required software beside MLDesigner You need the GNU Concurrent Version System (CVS). All major linux distributions ship CVS so if the cvs command is not avaiable on your computer you simply install the required packages with the help of the tools coming with your distribution 1. There are also versions of CVS avaiable for solaris. If you cannot find any binary packages suitable for your sytem configuration you have the posibility to compile your own binary by using the sources provided at www.cvshome.org. 2.1.2 Configuration As described in sec. 1, CVS stores all controlled data at a centralized position - the CVS repository. Before you can start using CVS you have to decide where the repository should be located. This location can be a central file server that exports its filesystem to all user workstations via a network filesystem like nfs or afs. But even if the user workstations have no shared directory with a dedicated server, it is possible to use CVS. The CVS repository should be stored on a dedicated server and the access is done via remote shell programs like ssh or rsh. Once you have decided where your repository should be stored you can create a directory (usually called cvs) that will contain your CVS repository. After directory creation you should set the shell variable CVSROOT to this directory 2. Now you can initialize the repository with the command: cvs init. If there were no errors during execution a new directory called CVSROOT has been created inside the $CVSROOT directory 3. The next step is to create a file called.cvsignore inside your home directory. This file should contain the following text data: *.lvx *.fvx *.htm 1 A simple test, to determine if you already have CVS installed is to type cvs in a command shell. If a brief help is displayed CVS is already installed on your system. 2 for example: export CVSROOT=/home/cvs as command for the bash 3 assuming your CVS directory was /home/cvs, /home/cvs/cvsroot has been created

2 Preparing your system for CVS *.html *.cc *.h.depend* *.o *.mld.fvx A more detailed description on how cvsignore works can be found in sec. 4. Every user using CVS should have his CVSROOT variable set correctly. This can be done via an entry in the login scripts 4. If CVS is used on a server that does not export its local filesystems, ssh or rsh can be used. After the correct set up for this procedure it is fully transparent to the user whether the CVS repository is accessed by a network filesystem or via ssh/rsh. Necessary configuration steps for using CVS together with ssh/rsh coming soon 2.2 User setup for using CVS 2.2.1 Repository is accessible through local filesystem Only the correctly set shell variable CVSROOT is necessary. As described in sec. 4, it is possible to create a user cvsignorefile. The LinCVS tool can be started by typing mldcvs in a command line shell. 2.2.2 Repository is accessible through ssh/rsh coming soon login. 4 For bash users, an entry like export CVSROOT=/home/cvs in the.bashrc will set the variable on every 2-2 LinCVS Documentation

Chapter 3 Working with CVS 3.1 General information on how MLDesigner stores model information I think it is easier to understand why which steps must be executed if you have an idea how MLDesigner remembers your model informations on the hard disk 1 : MLDesigner stores the models you create on the hard disk of your computer like MLDesigner s File View shows it to you. In the File View each entry with a small square in front, corresponds to a directory on your hard disk. The icons in front of the entries symbolize what the entries are. You will find icons for a library, a model, a primitive, a fsm a probe, for primitive sources, htm files and so on. The File View of MLDesigner displays all directories on the hard disk, even if MLDesigner doesn t know what s inside. If MLDesigner cannot determine what is in this directory, it shows you a map-icon. If you have created some directories inside your model hierarchy where you store statistical outputs, or inputs for some of your models or some pictures as labels for your models, you can find the directory in the File View of MLDesigner. In contrast, MLDesigner shows only those files MLDesigner knows: In the directory you have stored only pictures in, you won t find entries in MLDesigner s File View. If you control a directory with CVS, you will find a directory called CVS in it. This directory contains information for the CVS managing process. You must not change content of these directories, all the necessary changes are done by CVS itself. In addition you must not call modules CVS because the modeldirectory will interfere with the CVS system which can result in loss of module informations. Each model is stored as a directory, and the model s mml-file inside the directory. If you have a primitive the files which contains the primitive information are the mml file (containing the general primitive information), the pl file (containing the primitive code itself) and a makefile (describing how a primitive should be compiled). If you consider a system, then there would appear a sml file which contains special information of the system s simulations. MLDesigner generates more files inside the hierarchy to speed up access to the models and libraries, these files are generated out of the files mentioned above. Example for those files are.mld.fvx, *.lvx and the *.htm files. Htm files contain the model s automatically generated docu- 1 Of course, I am thinking about the host s file system. It is not necessary that it is located on your hard disk - it also can be on a file server s storage media and exported to you via a network file system. I use hard disk as a synonym for at your hosts file system.

3 Working with CVS mentation in a htm like format. You should not manage these files with CVS - they will only blow up your repository and are not necessary because MLDesigner will generate them when they are needed. You can browse via your favorite file manager in your $MLD USER directory and look into the content of the files to become familiar with the way MLDesigner stores information. The reason why I have told you all that stuff is, that you will see the files inside LinCVS and there you should have an idea what is inside the file. You must decide if you want to add these files to your CVS repository or not. Files you should add are those which contains necessary model information such as mml, pl, sml, makefiles and all the files you have added and which you consider to be important. Until now, we have discussed only the File View inside MLDesigner. The logical view is generated out of the mml files of your libraries. Inside these files there are entries for each entry which should appear in the library in you logical view. So you are able to add references to models even if they are not stored physically in the library where the reference is in. Or you can delete a reference to a model which is physically in the library but you do not want to see it in the Library View. Because all the information about your Library View is stored inside the mml files of your libraries, you must have write permissions to the library s mml file if you want to change something in this View. If you want to make changes to your library you must give you write permissions. This can be done by choosing the edit command in LinCVS. This command will give you write permissions to the files you have selected, or to all files inside a directory hierarchy if you have selected a directory in the Workbench section of LinCVS. How granular you give you write permissions is up to you - you can enable write permissions on your whole library, on sublibraries or only on modules or even only on single files. If you make only minor changes, I suggest to enable write permissions only on a few models or libraries. To detract the write permissions you can say unedit in LinCVS. It is not necessary to restart MLDesigner when you do permission changes. In models you will be able to change things imediatly after you have given you the permissions. Sometimes you must close the models and open them again, or simply say a refresh in MLDesigner s Library View. If you get some routine you will know what is necessary in what changing scenarios to notice MLDesigner that the permissions have changed. Now you might be a little bit confused, but you have some kind of ideas how MLDesigner stores information. I suggest you to go on reading - with the help of these ideas you will be able to understand, why things should be done in the way I have described. 3.2 Using a library that is maintained by another person The library should already be inside the CVS repository. This is done by the library s maintainer 2. The first step is to check out the version inside the repository to your $MLD USER directory: 2 A description on how this is done can be found in sec. 3.3. 3-2 LinCVS Documentation

3.2 Using a library that is maintained by another person 3.2.1 Check a library out from the repository After the library is inside the repository, you can check out your own working copy of this library. To check out the library you can follow these steps: 1. Open LinCVS, select Project - Checkout and fill the dialog with the help of the following description. Refer to fig. 3.1. Figure 3.1: LinCVS showing the Checkout dialog Profile, User, CVS Server, CVS Repository, CVS Access these options equals those in the Import dialog. Please refer to section 3.3.1. Checkout into This entry specifies the directory where your copy will be placed. As we want to check out a toplevel library, this directory should be the same as your $MLD USER. BE CAREFUL, the path where you want to check out your library is your $MLD USER and not MLD USER/SimpleEvaluationSystem 3, because CVS will create directory called like your library and CVS will check out the files into this directory. CVS Module Here you should specify what CVS module you want to check out. In this example we want to check out the SIMPLEEVALUATIONSYSTEM library, so we insert SimpleEvaluationSystem. Checkout as Leave this field empty. use revision, tag or date This option specifies the version of the library you want to check out. Since we want the newest version we won t use this field. You can find a more detailed description on how to check out other versions in sec. 4. checkout readonly We recommend you select this option. 3 Anyhow, the library should be removed out of your MLD USER directory before you check out. 3-3

3 Working with CVS 2. After clicking OK, you can see the output of the cvs command inside LinCVS. U means that a file has been updated - in our case that it has been checked out successfully. Now LinCVS asks if this project should be added to the workbench. Click YES and your library will appear in the Workbench section of LinCVS (Refer to fig. 3.2). Figure 3.2: LinCVS showing your library at the Workbench Now that you have checked out the library, you should select Refresh in the Tree View of MLDesigner to inform MLDesigner that there are new files. If you look into the Library view, the imported library will appear grey which indicates that it is read only. (Refer to fig. 3.3.) After you have checked out the library it should appear inside the Library View of MLDesigner. Note that the library name and the names of all sub models will be grey inside your Library View 4 which indicates that you are not allowed to change something inside this library 5. (Refer to fig. 3.3.) 4 If not, you have forgotten the hook at the checkout readonly field in the check out dialog of LinCVS. Don t worry, you can delete the library and do the check out procedure again. 5 If you check out, all files (including the mml files which contain the model definitions) have readonly permissions. But you can compile the models, because you have write permissions inside the directories. Be careful inside the file view; since you have write permissions in the directories you are to make modifications in the file view. 3-4 LinCVS Documentation

3.2 Using a library that is maintained by another person Figure 3.3: MLDesigner showing the library view after checkout Now you can use this library in all your new models. 3.2.2 Synchronizing your copy with the latest version inside the CVS repository You can always check the current status of your copy by using the LinCVS s Status command 6. There are different status possible: seems up to date (Refer to fig. 3.4) These files have not changed inside your sandbox. But it is possible that they have changed inside the repository. LinCVS provides you with this information without looking inside the repository. If you want LinCVS to examine the files in the repository you should give the status command. up to date (Refer to fig. 3.5) This means the files you have in your sandbox equal the latest version inside the repository. You can see this status only after LinCVS has interacted with the repository (for example by using the status command. needs patch (Refer to fig. 3.6, Note that the icon left to the filename have changed, and that there are exclamation marks in the Workbench all the hierarchy up. These will help you to recognize very quickly if and where files are that need to be patched.) This means, that the version in the repository has been changed (the maintainer or someone else has committed changes to this file) and you must choose update if you want to get the latest version. Your copy of the library in the sandbox will not change until you advise CVS with an update command. So you can keep an older version if you do not trust the maintainer s last commit. If you decide to update this library, we suggest, that you update the whole library to ensure that all dependencies are updated. In addition, we recommend that you close all models inside MLDesigner while doing the update. 6 in the menu which appears if you do a right click on a library name or filename inside the LinCVS Workbench 3-5

3 Working with CVS Figure 3.4: LinCVS showing Read only files which seem to be up to date Figure 3.5: LinCVS showing Readonly files which are up to date 3-6 LinCVS Documentation

3.3 Managing a library with CVS Figure 3.6: LinCVS showing files which need patch 3.3 Managing a library with CVS This chapter shows you how to maintain your library with LinCVS. You should be familiar with the sections above before reading this. The first step is to create the library inside MLDesigner. After this you can import your new library into the CVS repository by following the steps described in the following section: 3.3.1 Importing a Model into CVS We recommend that only whole MLDesigner libraries are imported into the repository. Follow the steps below to import a library into CVS. 1. Decide what library you want to import into CVS and find this library in the MLDesigner Fileview (refer to fig. 3.7). 2. Open LinCVS, select Project - Import and fill-in the dialog with the help of the following description. Refer to fig. 3.8. Profile If you have specified profiles you can use this filed to set default access parameters. (see section 4) User This field should be set to your login name. CVS Server Leave this blank because Method is Local. CVS Access Select Local/NFS 7. Import dir Select the directory where the MLDesigner library is located. Import as This field specifies how the library will be named inside CVS. Set this field to the name of the library. Vendor Tag you can keep the default settings 7 How to use LinCVS with a repository located on a non-local filesystem is described in section 4. 3-7

3 Working with CVS Figure 3.7: The MLDesigner File View dialog with the library to put under CVS control Figure 3.8: LinCVS showing the Import dialog 3-8 LinCVS Documentation

3.3 Managing a library with CVS Release Tag you can keep the default settings Commit info Use this field to add a comment which will be shown in the history tree. This is mandatory. 3. After clicking Import you can see the output of the CVS import command 8 : CVS import: Importing /var/lib/cvs/simpleevaluationsystem/application N SimpleEvaluationSystem/Application/Application.mml I SimpleEvaluationSystem/BurstTest/BurstTest.htm... No conflicts created by this import An N means that the file has been added to the repository, an I means that the file has been ignored 9. If you did not add files into the model directories, the CVS system ignores only those files you do not need to put under version control 10. Make sure that there were no errors by checking the outputs of the CVS commands that LinCVS invokes. A copy of your library should now reside in the CVS repository. The next step is to delete the library in your $MLD USER and replace it with a checked-out copy from the CVS repository so it can be managed via CVS. How to check out the library is described in sec. 3.2.1. You should now have your library back in MLDesigner with write protection on the models. This protection reflects in the green icons in the LinCVS s file view as well as the gray symbols in MLDesigner s Library View. In the following the most common scenarios for working on the library are described: 3.3.2 Changing a single module or primitive You must give you write permissions to the module s files via LinCVS s Edit command by applying the Edit command on the whole directory which contains the model information. Now, you can change the module like you want inside MLDesigner. Be aware that changes on the interface of this module (its ports, its exported shared elements or parameters) will effect other modules which instanciate the changed module. For example: you change the name of an exported parameter save the model A and open another model B which instanciates the changed model A The save model button in MLDesigner will become active indicating that there are changes in the model B (MLDesigner changes the parameter name of the instance in model B). You now can give you write permissions to model B, too and you can save these dependent changes. Of course if you have already write permissions to model B (i.g. you have given you write permissions to the whole library) you can simply save this changes. 8 in the lower right window of LinCVS 9 Refer to section 4 for cvsignore handling and to sec. 3.1 for a description on the various file types. 10 How the CVS system should be installed is described in chapter section 2.1. 3-9

3 Working with CVS 3.3.3 Changing a library You must give you write permissions to the library s mml file, after this, you can add references, new models, sublibraries, or primitives. 3.3.4 Commit your changes When you are finished with changeing your library, you should save all your changes inside MLDesigner. The modifications you have done are only in your working copy. The LinCVS workbench shows that you have changed some files (refer to fig. 3.9). Figure 3.9: LinCVS modified files You can review your changes with the help of the LinCVS gui. After selecting the modified file and saying Diff side-by-side a diff window appears showing the modifications you have done on the file. Figure fig. 3.10 shows the diff window with a small modification on the pl-file. To propagate your changes to the repository you must commit the changes. This is done via the commit command inside LinCVS. You can either select whole directories or single files, press the right mouse button and select commit within the context menu. Now, a small window appears in which you can document the changes you have done (refer to fig. fig. 3.11). These comments are saved inside the repository and can be accessed via the LinCVS gui. In the log window of LinCVS you can watch the output of the CVS command invoked by LinCVS. Every commited file raises a message like: /home/dz/cvs/mld/berkeleysockets/basics/close/declose.pl,v <-- DEclose.pl new revision: 1.2; previous revision: 1.1 done Possible errors during the execution of the commit command are also shown in this window. You should have a short look on these outputs to ensure that there were no errors during the commit procedure. 3.3.5 The log tree CVS remebers all versions inside the repository. The history of a file can be accessed via the Log Tree command. In figure fig. 3.12 the graphical revision tree is shown. Each rectangle represents 3-10 LinCVS Documentation

3.3 Managing a library with CVS Figure 3.10: Diff window showing differences between sandbox and repository Figure 3.11: Providing a comment on the changes 3-11

3 Working with CVS a version of the inspected file. Above the version number, the user who modified the file is shown (dz in this example). You can select two different versions (via the left and right mouse button) and press the Diff button. A diff window showing you the differences will appear. Figure 3.12: a sample Revision Tree 3.3.6 Adding files to the repository Adding files or directories is straight forward inside LinCVS. Directories and files that are not yet inside the repository are shown in the Non-CVS files tab of LinCVS 11. Inside the context menu Add ASCII file and Add binary file should be used to add textfiles (mml, pl and makefiles and binary files (graphics like png or other binary files). The following chapter shows the procedure on the example of creating and adding a new primitive. 3.3.7 Creating a new primitve and adding it to the CVS repository write permissions to library You should have write permissions to the library where you want to create the primitive. To get those permissions you should apply the edit command at the library. create the primitive in MLDesigner After you have the permissions, the library is shown black rather then gray inside the library view of MLDesigner. Now you can create the primitive using MLDesigner. You can modify and work with the primitive. 11 Unless they are not ignored by CVS. For a full description on how the ignore mechanism works, refer to sec. 4. 3-12 LinCVS Documentation

3.3 Managing a library with CVS adding the primitive to the repository When you decide to publish the new primitive you should add the primitive to the repository. Go to the LinCVS gui and select the library in that the new primitive is located. In the tab Non-CVS files the primitive s directory appears (refer to fig. fig. 3.13). Figure 3.13: LinCVS showing a new directory in the Non-CVS files tab After LinCVS has reread the directory structure of your library you can add the necessary files 12. For standard primitives the mml, pl files and the makefile should be added as ASCII files. Refer to fig. fig. 3.14. Figure 3.14: Adding three new files to the repository After adding the files, they appear in the CVS files tab of LinCVS. Now you should commit your changes to the repository. The icon in front of the files will turn into the green sheet of paper that shows that these files are now inside the repository and readonly in your sandbox. commiting the upper library While creating the primitive MLDesigner modifies the mml file of the upper library 13. To complete the procedure you should commit the changes to the upper library s mml file, too. 12 refer to sec. 3.1 for an overview on what files are necessary 13 MLDesigner creates a link in the libraries mml file to the primitive this link is responsible for showing the new primitive inside the logical view. 3-13

3 Working with CVS 3.3.8 Removing files from the repository coming soon 3.3.9 Moving files inside the repository coming soon 3.3.10 More people working on the same library coming soon 3-14 LinCVS Documentation

Chapter 4 TODO!! How to deal with MLD s build in import and export? cvsignore handling general settings in LinCVS repositories on another machines profile management check out other versions TAGs BRANCHES usage of cvs out of the command shell is possible beside using LinCVS