PxPlus Version Control System using TortoiseSVN v10
From PxPlus
Pvx Plus provides integration with TortoiseSVN, a free open-source Windows client for the Subversion source version control system. A version control system manages files and directories and the changes made to them over time. It serves as a repository for the source files; it keeps a history of the changes and allows the recovery of previous versions. It also manages changes from multiple users, merging simple modifications or facilitating user intervention with more complex modifications.
PxPlus integration includes utilities to import ProvideX application programs into a TortoiseSVN or SVN repository, checkout source from the repository, commit source changes to and update application programs from the repository.
Contents |
About TortoiseSVN
TortoiseSVN is free, easy-to-use source control software for Microsoft Windows. It is integrated into the Windows Explorer, where the file status is displayed in the file icons, and all TortoiseSVN commands are available from the right-click pop-up menu. To learn more about TortoiseSVN, visit one of the many web sites available to download software and documentation:
http://tortoisesvn.net/ http://tortoisesvn.tigris.org/
Note: TortoiseSVN Version 1.4 or later is required.
Background
Source programs are imported into the SVN repository where they are stored and become available to be checked out by other users. The source programs are stored as text files to facilitate comparison and merging. However, since a ProvideX application consists of tokenized programs, screen library files, data files and miscellaneous other files, these files must first be extracted into a format that is usable by the version control system.
Once the source files have been imported into the repository, this step need not be repeated for this source directory. The source files are now available to be checked out by other users working with the same files or project.
When source files are checked out by a user into a source directory (also referred to as the working copy by Subversion or the sandbox by CVS), it is the text version of the programs and screen library files that is copied into the source directory, as well as hidden directories and files used to manage the files. The source files must also be converted into usable application files and stored in the application directory. As well, PxPlus requires some administrative files to be set up in both the source and application directories to manage its side of the integrated version control system.
Setup and Installation
The steps involved in setting up the Version Control System consist of installing TortoiseSVN (and possibly Subversion) and setting up a repository location, the one-time administrative task of preparing an application directory and importing the application into the repository, and finally, the users checking out the source files.
Install TortoiseSVN
TortoiseSVN software and documentation can be downloaded from various web sites. If you have already installed TortoiseSVN, be sure that it is Version 1.4 or later in order to work correctly with the PxPlus Version Control System. TortoiseSVN is a Windows client that can access a repository set up locally using the TortoiseSVN>Create repository here item from the Windows Explorer pop-up menu, or a remote Subversion (SVN) repository. The repository must be created before attempting to import files.
Importing an Application
The first step in importing an application into the repository is the job of the Version Control System administrator. First, prepare an application directory with the all the sub-directories, tokenized programs, screen libraries, data files, etc. that are to be included.
Next, start pxplus and check your parameter settings. Some parameters, such as case sensitivity settings ('LC', 'LD', 'MC', etc.) can have an effect on how your programs are saved. The 'V+' parameter can be used to control how the text of programs will be 'saved' into the source control files. Its value consists of a mask consisting of:
0 - SVN source will use lower case variables and directives and suppress LET (default)
1 - SVN source will use upper case variables and directives and suppress LET
2 - SVN source will use the 'LD', 'LC' and 'NL' parameters in effect
+4 - Adding 4 to the value of 0, 1 or 2 will force the format of a SAVE to a serial file
to match that of a standard SAVE.
If 'MC' is set, this will override the case settings for variables.
While certain aspects of the Version Control System run in your current session, there are some tasks that are spawned. If you set your parameters in your START_UP program, be sure there is a START_UP program for both your current session as well as the spawned sessions (in the directory where the pxplus executable is located).
Finally, to import the application, invoke the PxPlus TortoiseSVN Setup utility from the ProvideX base window Utility menu, from the Version Control menu in the Integrated Toolkit (IT), or using the SVN SETUP command program.
Important: Do not attempt to import the application using the Windows Explorer TortoiseSVN>Import option on the pop-up menu as it will not set up a proper source directory that can be used by the Version Control System.
Select the Import Source to Repository option.
You must enter the main path of the application directory that contains the programs and files that you wish to import into the repository. You must also enter the main path of the source directory where the source files will be stored. The directory will be created if it does not exist. This directory will be loaded with the text version of the programs and panel directories and files, etc. that will ultimately be imported into the repository. When the Apply button is pressed, the Version Control System extracts the files from the application directory and converts programs and screen library files into the proper format for the source directory, and copies the rest of the files into the source directory. Program files will have a .pxprg extension, while a directory will be created for each screen library file, containing individual panel definition files with a .pxpnl extension.
When a password protected program is encountered, the system will prompt for the password. If you give it the proper password the program will be converted to plain text and copied with its password header. If you do not supply the password but press the Copy Asis button, the program will be copied in binary form. The extraction process maintains a list of passwords you supply and tries the same passwords on subsequent programs. This means that if multiple programs have the same password, you will only be prompted once.
When the extraction process is complete, the TortoiseSVN Import procedure is automatically initiated to import the contents of the newly loaded source directory into the repository.
Enter the URL of the repository and any notes you wish to record and press OK. When the import procedure has ended, the repository will hold the contents of the source directory, ready to be checked out and used by the development team.
Note: The import task for the application is completed once by the Version Control System administrator, but in order to use the system, the administrator must also perform the Checkout procedure to add the administrative files required by both TortoiseSVN and PxPlus to manage the source and application directories.
Checking Out an Application
For most users, this is the only setup step required. While the import procedure is performed once by just the administrator, the Checkout step is performed once by all developers involved in writing the application. This is the step that creates source and application directories using of the latest versions of the files in the repository.
To checkout the application, start pxplus and check your parameter settings. Some parameters, such as case sensitivity settings ('LC', 'LD', 'MC', etc.) can have an effect on how your programs are saved. (See #Importing an Application for more details on parameter settings.) Then invoke the PxPlus TortoiseSVN Setup utility from the ProvideX base window Utility menu, from the Version Control menu in the Integrated Toolkit (IT), or using the SVN SETUP command program.
Important: Do not attempt to checkout the application using the Windows Explorer TortoiseSVN>Checkout option on the pop-up menu as it will not set up a proper application directory or administrative files that can be used by the Version Control System.
Select the Checkout source from Repository option.
Identify the source and application directories. If they do not exist, they will be created. These directories should be empty for the checkout procedure, although it is not necessary. When you press Apply, the TortoiseSVN Checkout procedure is invoked.
Enter the URL of the Repository and identify the Checkout directory (i.e. Source directory). This procedure will copy the latest version of the source files into the source directory. It will also create administrative files required by TortoiseSVN to manage the files.
When TortoiseSVN has finished the checkout, the Version Control System will proceed to update the Windows registry with new file types, .pxprg and .pxpnl for ProvideX programs and panel definitions. This allows files in the source directory that have these extensions to be invoked with the proper editor or open procedure.
The Version Control System then adds some administrative files to source and application directories needed to manage the files. It pre-loads the name of the application directory, and you are given the option to supply a starting point from which to run the application.
TortoiseSVN hook scripts that integrate SVN commit and update functionality with PxPlus Version Control System procedures are added to Windows registry entries.
The Version Control System then begins the procedure to add the files to the application directory.
When the Application Update procedure is finished, the checkout is complete.
Using the Version Control System
The main purpose of the Version Control System is to track changes and keep your programs and files up-to-date. This generally consists of committing additions, modifications and deletions within your application to the repository, and of updating your application with changes by other developers from the repository.
Editing Files
You can edit programs as you always have, using your favourite editor. You can edit a program in the application directory using the Integrated Toolkit (IT), *e, or using the command line. If your favourite editor is a text editor, edit from the source directory, but this will require an extra step later on. Edit panels from the application directory using the NOMADS Designer. You can also edit programs or panels by right-clicking on the file in the source directory and selecting Edit from the pop-up menu. This invokes the Integrated Toolkit (IT) to edit a program, or the NOMADS Designer for panels.
It is important to keep the source and application directories in sync when modifying files. If you were to modify and save a program from either the application or source directory using IT, *E or the command line, then the PxPlus Version Control System will automatically synchronize the program in the other directory. This is because whenever a program is saved using the PxPlus SAVE directive, special administrative files are accessed (.pluscvs files in the application directory and .cvsplus in the source directory) to determine where to update the corresponding program. Also, when you modify a screen panel using the NOMADS Designer, the corresponding source file is updated automatically as well.
If you use a text editor to modify programs in the source directory, or copy modified programs into the application directory, then the source and application directories will no longer be in sync. In these cases you will have to perform an extra step to re-sync the directories. In the case of modifying source files with an external editor, you will have to manually update the application directory. This can be done using the SVN command line program with the APPUPDATE option, as in SVN APPUPDATE PATH. The path can be a directory or file name, and can reference either application or source directory.
Examples:
svn appupdate c:\development\myapp ! Updates all files in myapp and its subdirectories svn appupdate c:\development\myapp\myprog ! Updates just myprog
In the case of copying files into the application directory, to update existing files you will have to manually refresh the source directory. This can be done using the SVN command line program with either the REFRESH or REFRESHALL options, as in SVN REFRESH PATH. For the REFRESH option, the path argument can be the source or application path of a directory or file. If a directory is specified, only the files in that directory level are processed; processing is not recursive. To process the directory and its sub-directories, use the REFRESHALL option which requires a directory path as an argument. The refresh options only affect files currently existing in the source directory. If a new directory, panel library or resource file is added, you will have to use the ADD option of the SVN command line program to extract it into the source directory and then add it to the Repository, as in SVN ADD PATH. (See Adding Directories and Panel Libraries, below).
To add a new program, create and save it in the application directory, or source directory if created in a text editor. If the new program is created using IT, *e or the command line, the source directory will automatically be updated. If using a text editor or copying the new program from elsewhere, you will have to sync the directories as described above. New programs will be added to the repository when they included in a commit command, or you can use the SVN command line program with the ADD option.
Examples:
svn refresh c:\work\mysrc ! Refreshes files in mysrc svn refreshall c:\work\mysrc\progs ! Refreshes files in progs and its subdirectories svn add c:\work\myapp\libs\scrnlib.en ! Adds a new screen library or panel svn add c:\work\myapp\images ! Adds the images directory and subdirectories
To undo all changes made in a file or directory since the last update, use the SVN command line program with the REVERT option. Be careful if you revert a file using the TortoiseSVN>Revert menu item in the pop-up menu, as this does not update the application directory; you would have to manually invoke the SVN command line program with the APPUPDATE option to sychronize the source and application directories.
Deleting Files
To delete a program or resource file, it should be deleted from the source directory by right-clicking on the file and using the TortoiseSVN>Delete menu item in the pop-up menu to remove it. Deleted programs will be removed from the application directory and repository when the directory in which it was located is next committed. To undo a deletion, you must revert the parent directory, as the deleted file no longer exists.
Committing Changes
After you have modified your programs and screen library files, added new files and deleted unwanted ones, etc., these changes exist only in your application and source directories until you commit them to the repository. Before you commit your files, however, you should make sure that your files are up to date with changes made by others, so you should update your files first to determine if there are any conflicts and resolve them. (See #Updating your Files, below.) When your files are up to date and there are no conflicts, you are ready to commit your changes.
There are several ways to commit your changes:
- The SVN command line program has a COMMIT option, as in SVN COMMIT PATH, to commit the specified file or directory to the repository. The path can be a directory or file name, and can reference either application or source directory. E.g.
svn commit c:\work\project\src\prg
It also has a UCOMMIT option, as in SVN UCOMMIT PATH that updates the source files prior to committing them. This is useful if you have modified resource files or copied program or library files into the application directory, as it synchronizes the files before committing them.
- Select TortoiseSVN Commit from the Utility menu on the PxPlus base window. This will invoke the TortoiseSVN Commit procedure to commit any modified files in the current directory.
- If you are using the Integrated Toolkit (IT) to edit your programs, the Version Control menu has entries to commit the current program, all open programs, a specified program or file, or a specified directory. There are also buttons on the toolbar to commit the current program or all open programs. Be sure to save any program changes before you commit them.
- In Windows Explorer, select the directory or files in the source directory that you wish to commit. Right-click and select SVN Commit from the pop-up menu.
The TortoiseSVN Commit procedure will present a change list of all modified files in the specified directory and its sub-directories. You can check the files you wish to be committed. If files are specified to be committed, they will appear in the change list if they have been modified.
When committing your files, be sure to include a brief description of the changes you have made to the files for future reference. Once committed, your modifications will be available to other developers when they update their files from the repository.
Updating your Files
If there are many people working on the same code base, you should periodically update your source and application directories to ensure that changes done by others are incorporated. An update consists of merging any changes done by others into your source directory files, keeping any changes you may have done to the same files. Conflicts can occur during an update, however, if others changed the same lines in the same file as you. TortoiseSVN has an external merge tool to resolve such conflicts. After the TortoiseSVN update is complete, the PxPlus Version Control System automatically updates the application directory with the new program versions. The repository is not affected by an update.
There are several ways to update your files:
- The SVN command line program has an UPDATE option, as in SVN UPDATE PATH, to update the source and application from the repository. The path can be a directory or file name, and can reference either application or source directory. E.g.
svn update c:\work\project\src\prg
- Select TortoiseSVN Update from the Utility menu on the PxPlus base window. This will invoke the TortoiseSVN Update procedure to update files in the current directory.
- If you are using the Integrated Toolkit (IT) to edit your programs, the Version Control menu has entries to update a specified program or file, or a specified directory. There is also a setting in the Option menu to Auto-update Version on OPEN, that will automatically update the program being loaded. If a conflict is found, TortoiseSVN will report it so that it can be resolved.
- In Windows Explorer, select the directory or files in the source directory that you wish to update. Right-click and select SVN Update from the pop-up menu.
If a directory path is specified for an update procedure, processing will be recursive to sub-directories.
Adding New Directories and Panel Libraries to the Application
When a new directory is added to the Application, a corresponding directory must be created in the Source, then the contents of the new directory must be extracted into the new Source directory, then added and committed to the Repository. This can be done in a single step using the ADD option of the SVN command line program, as in SVN ADD PATH. New panel libraries and resource files may also be added this way.
Examples:
svn add c:\work\myapp\images ! Adds the images directory and subdirectories svn add c:\work\myapp\libs\scrnlib.en ! Adds a new screen library or panel
To retrieve a new directory or screen library, do a source update on a directory containing the new directory/files, and the Source and Application files will be added automatically.
SVN Command Line Program
The SVN command line program has a number of options that allow you to execute almost every aspect of the Version Control System. The following table outlines the available options:
| Command | Option | Argument | Description |
|---|---|---|---|
| svn | [?] | Help description | |
| svn | setup | Same as TortoiseSVN Setup item in the Utility and IT Version Control menus. Interactive interface to choose import or checkout functionality. | |
| svn | import | Interactive interface to extract files from application directory into source directory, then import into repository. | |
| svn | checkout | Interactive interface to checkout source directory from repository and convert into application files. Also sets up administrative directories and files used by the Version Control System. | |
| svn | add | [appPath]* | Extracts files from the application directory or panel library into source directory, then adds and commits the directories into the repository. Can also be used for individual program and resource files. New panels are added by adding the panel library. |
| svn | commmit | [path]* | Commits the specified directory/file to the repository. |
| svn | ucommmit | [path]** | Updates the specified source directory/file and commits it to the repository. Does not add new files. |
| svn | update | [path]* | Updates the specified directory/file from the repository to the source directory and updates the application files. |
| svn | refresh | [path]** | Refresh the specified directory/file in the source directory from the application directory. (Not recursive). The source directory/file must exist. (Use the add option to add new files.) |
| svn | refreshall | [dirpath]** | Refresh the source directory and sub-directories from the application directory. The source directory must exist. |
| svn | revert | [path]* | Undo all changes made in the specified directory/file since the last update. |
| svn | extract | Extracts application files into source files. Runs *plus/proj/extract. | |
| svn | appupdate | [path]** | Updates the specified directory/file from the source directory to the application directory. Runs *plus/proj/update. |
| svn | register | Sets up registry entries required to integrate TortoiseSVN and the PxPlus Version Control System. Also creates the TortoiseSVN hook scripts required to integrate the TortoiseSVN commit and update functionality with the Version Control System. | |
| svn | target | [srcdir]** | Creates administrative files required by PxPlus Version Control System integration. Runs *plus/proj/target. |
Note:
* Paths are optional and default to the current program if omitted. If no program is loaded, default is the current directory. ** Paths are optional and default to the current directory if omitted.
Paths can reference either source or application directory unless otherwise specified. When directories are specified, processing is recursive to sub-directories.
Examples:
SVN checkout SVN commit c:\development\svnsrc\proj\browser.pxprg SVN update c:\development\svnsrc SVN refresh browser
