Using a Perl Debugger with Server Side Triggers

By Wayne Blair, Senior Consulting Release Engineer and Development Facilitator

Introduction

This article describes a method to use a perl debugger on trigger scripts without advanced interprocess debugging tools.

Using a perl debugger with a V4.x server side trigger launched by the server is very difficult and encounters two known obstacles:

1. The server will fire the trigger and the debugger will run in a thread of the detached server process; the debugger will start but will probably not communicate with you. However, if you manually started the server via a shell command then the perl debugger will start, accept input from the keyboard, then you will loose contact with the debugger; it does not have exclusive access to the keyboard because it is running in the context of the detached server process. The next command you type will go to the shell, not the debugger.  It gets messy from there.
2. Debugging on your live server means another AccuRev command could launch the same trigger in debug mode and the AccuRev client that issued the command will appear to be “hung” because the server thread for that command has called the debugger.  Also, if you started the server from the shell command, you will now have two debuggers trying to communicate with you. Running two different triggers in debug mode will create madness for you and get your users very upset!

Summary

• Trigger parameter files facilitate communication between the server process and triggers.
• The AccuRev server does not provide a mechanism to preserve trigger parameter files; they are temporary and removed.
• XML is used for most trigger parameter files but some still use flat files. Study the original trigger to know how to process the format.
• Modify the trigger file to capture and preserver the trigger parameter files. There can be many parameter files per transaction. Compose the file name based upon the trigger name, sequence number, and epoch second.
• Practice continuous process improvement! Use a semaphore file to activate and deactivate the feature to capture the parameter data to a file. You will enable the feature for a few minutes to collect samples then disable it.  The semaphore allows you to reuse the feature without editing the trigger script.
• Once you have enabled the facility and have collected a few trigger parameter dump files, choose an interesting one and make a copy; the copy step is important because the trigger you are debugging will reinitialize the trigger parameter file to return data back to the server. NOTE: Some triggers expect both an XML and flat parameter files. Study the trigger to determine the correct calling arguments.
• Use the copy of the parameter file and pass it as a command line parameter to the trigger you run with a Perl debugger.
• You can now single step through your trigger.
• You must make a new copy of the original parameter file before restarting the debugging session because the file you passed into your trigger was reinitialized. You do not need to exit the debugger, just make a new copy of the trigger file before you issue the debugger “R” (restart) command.

Details

I extend AccuRev functionality to support development processes and I create complex triggers that are easier to develop with a Perl debugger; this is especially true when your triggers are manipulating issue tracking data.  The AccuRev CLI manual provides good information about the triggers but you might need subtle details that are beyond the scope of the documentation. Walking through trigger execution with a debugger gives details about the content of the parameter files and what is passed from trigger to trigger.

I am not aware of any special options to allow the AccuRev server to run Perl triggers in debug mode and my attempts to do so create an unworkable environment. Since triggers are driven by parameter files, I’ve added routines to all the triggers to collect their parameter files. Once I have a collection of interesting parameter files I can launch the trigger scripts with my own Perl debugging tool of choice instead of them being launched by the AccuRev server.  I can also inject faulty data via the parameter file for testing.

The AccuRev server creates a temporary parameter file for each trigger it is calling.  The file name will be a relative path to a temporary directory and each filename will be a sequence number. Please note that a trigger can be fired more than once for a transaction. The temporary file name does not indicate the target trigger script; the trigger name and the AccuRev command that fired the script are embedded in the parameter file.

I embrace the concept of continuous improvement so I anticipate trigger debugging will used many times over the years.  I used a semaphore file to enable and disable the parameter dump functionality to eliminate edits to the trigger scripts on the live repository.  I’ve even attached captured parameter files to issue tickets I’ve submitted to AccuRev support.

Capturing Parameter Files

The AccuRev server determines what trigger to launch then creates one or more temporary files in the cache directory of the site slice and passes a relative directory name and file name(s) in the argument list to the trigger. The server process will ensure a unique sequence number when multiple threads launch the same trigger at the same time.

The steps I use are:

1. Set up my environment:
   1. Define the semaphore file name
   2. Define a directory below the accurev root to store the trigger parameter files.
2. Immediately after the trigger has parsed the XML data, call a utility function and pass it the “hook” name and the relative path to the temporary trigger parameter file that was created by the server. The server created file name will be a sequence number.
3. The utility function will look for the semaphore file in the AccuRev root directory and will simply exit when not found. When the semaphore file is found, the function will compose a unique file name based upon
   1. The trigger “hook” name
   2. The  server supplied file name (minus the directory)
   3. The current epoch second
4. The utility function will create the trigger dump directory as needed, create the file name composed in step #3, and write the trigger parameter data to the new file.

Appendix A has an excerpt of my server_admin_trig.pl and trigger utility module. I save off the parameter file immediately after the trigger has digested the XML data.

I strive to write my perl code to be operating system agnostic. I keep my common trigger code in a perl module that resides in the accurev “bin” directory. I like to avoid external environment dependencies so I explicitly state the lib path (in an OS agnostic way) to my trigger utility module.  I do this because the “use” is a compile time directive and is processed before variables are defined.

Debugging the Trigger with the Captured Parameter File

You must make a copy of the captured trigger parameter file before you use it. Triggers re-initialize the parameter file to pass data back to the server so your captured data will be lost.

1. cd $HOME
2. cp $ACCUREV/trigDumpDir/server_admin_trig-0_0-1246634816   test.dat.org

You launch a perl debugger and pass the trigger parameter file into the script as the first command line argument. Debug to your heart’s content.

1. cd $HOME
2. cp $ACCUREV/storage/site_slice/triggers/server_admin_trig.pl    funTime.pl
3. cp test.dat.org test.dat
4. perl -d funTime.pl test.dat

NOTE:  The script will reinitialize the parameter file for output. You must copy “test.dat.org” to “test.dat” before you restart the debugging session.

Appendix A:

Server_admin_trig.pl – You can download this script here

Click to download

Trig_utils.pm – You can download this script here

Click to download

Sample of Captured Trigger Data

Below is the trigger parameter file captured from server_admin_trig.pl for a “mkdepot” command.

This is a simple example. The parameter data gets much more interesting when your objective is to mine transaction or issue tracking details.

Capture file name is: /opt/accurev/ar6060/trigDumpDir/server_admin_trig-0_0-1248023869

<triggerInput>
<depot>test10</depot>
<hook>server_admin_trig</hook>
<command>mkdepot</command>
<principal>ar6060</principal>
<ip>127.0.0.1</ip>
</triggerInput>

Hot Backups and Database Verification Without Down Time

By Wayne Blair, Senior Consulting Release Engineer and Development Facilitator

Hot backups are wonderful but one needs two important sanity checks on the backup:

1. Was this a good backup?
2. Is the live database okay or did we just backup a corrupted repository?

Unfortunately AccuRev v4.x cannot perform a database integrity check on the running repository so you have to schedule down time but you can run the “maintain” utility on your backup repository on a different machine with a minor change to the acserver.cnf file.

These steps can sanity check both your backup and your live repository at the time of backup without any down time using the behavior of the “maintain” utility.

1. Write a backup mark using the command “accurev backup mark”.
2. Replicate your entire accurev installation directory tree to another machine running the same operation system. You want the data, executables, configurations, and license key.
3. Edit ./bin/acserver.cnf and change the machine name from your live repository to the name of the “other” machine”. MASTER_SERVER = your_other_machine.organization.domain
4. Run the command “./bin/maintain dbcheck”.

If the command fails due to a host name error then review your edit for faulty white space (the white space before and after the = is required and you must not have trailing white space after the host name).  If the fully qualified name fails, try using the alias (short) name or IP address.

Assuming a successful dbcheck, you have now verified the integrity of your backup and you have verified the integrity of your live repository as of the time of the last backup mark command.

DETAILS

The AccuRev license is tied to a specific host and port number and you must have a different license file to run the AccuRev repository on a different machine.

The maintain utility performs a sanity check on the license and will exit when the license file is missing. It will check on the host name and will exit when the running host name does not match the host in acserver.cnf but will continue to perform the database integrity check when they do match!

My AccuRev server is Linux based so I run an hourly cron job to write the backup mark then rsync the whole installation to another machine.  I intentionally use the –delete option to ensure the backup is identical every time so the edits I apply to acserver.cnf will be eliminated the next time the backup is run.

Here is a trivial sample script to perform the backup with rsync.  I am writing this from memory so please verify the rsync syntax with the trailing slash on the directories.

# ASSUMPTION: ssh keys are already established between this host
#             and the remote host to allow an automatic login.
#
# NOTE: Be sure the previous run of this script has completed before
#       running again.

/opt/accurev/bin/accurev backup mark
sleep 3
rsync -az -e ssh --delete \
/opt/accurev/ \
wblair:/opt/accurev

About The Author

Wayne Blair was invited to contribute to our Distinguished Lecturer Series because of his experience as a consulting release engineer with multiple AccuRev customers.  Mr. Blair has extensive experience creating and extending software development, release, and installation environments, and helping communicate technical information to non-technical people.

Security Primer – Anatomy of the AccuRev Admin Trigger

by Rob Mohr

Do you have the “Admin Trigger” installed and running in your AccuRev environment?  I hope so!

The “Admin Trigger” is the best way for you to restrict those non-ACE’d (AccuRev Certified Engineer) users from wreaking havoc on the process you’ve meticulously designed and implemented for your organization.  Make sure you lock it down!  It’s really simple to do!

Now, I’m not talking about taking flexibility away from your developers, they’ll need to control certain aspects of the process too.  It’s up to you where the line is drawn in the stream hierarchy and the Admin Trigger is the chalk.

The equator is commonly established on the integration stream.  Since the globe in this case is AccuRev, the line of demarcation runs north and south.  To the West (upstream from integration), ACE’rs set the rules on workflow, code promotion, stream configurations, and general access control.  To the East (downstream from integration), developers and development teams are free to make their own decisions to best support their process, products, projects, components, patches, bug fixing and development activities.

Have you read the private prototyping or stream-per-task blogs by Dave Thomas?  These are good examples of how dev teams and developers control how their activities are organized using streams while adhering to the overall enterprise software development life cycle (SDLC).

The Admin Trigger is a simple if-then-else perl script that fires on the server whenever certain commands are  executed.  Out-of-the-box, the script restricts “admin type” commands such as creating users, groups, depots, etc without needing additional customization.

 @cmdlist = qw/mkuser chref chdepot chslice lsacl addmember
                  rmmember mkgroup mkdepot mktrig rmtrig
                  setacl write_schema/;
    # is the user command in the above list?
    if (grep $_ eq $command, @cmdlist) {
    ...

The admin type commands are typically global in nature, meaning, that a single Admin group is granted permission for these commands.  Stream creation has a more granular scope allowing different groups to control their development process and stream management capabilities.

Simply list the streams in the trigger that only Admins have the ability to “manage.”  By default, other streams not listed are managed by the development teams themselves.  There are 2 sections in the trigger to set this up depending upon the commands to control.

Restricts: lock, unlock, chstream, incl, excl, incldo

    $admin_stream{"replace_with_admin_stream"} = 1;
    $admin_stream{"replace_with_admin_stream"} = 1;
    $admin_stream{"replace_with_admin_stream"} = 1;
    ...

Restricts: mkstream, mkws

    $basis_stream_deny{"replace_with_basis_stream_to_deny"} = 1;
    $basis_stream_deny{"replace_with_basis_stream_to_deny"} = 1;
    $basis_stream_deny{"replace_with_basis_stream_to_deny"} = 1;
    ...

Inside the trigger logic, each command is evaluated and will allow the operation to complete or not.

For example, the following section validates the “mkstream” command:

if ($command eq "mkstream") {
...
 # only a user listed as an administrator can create a new stream
 # based on an existing stream in the "basis_stream_deny" list
 if ( defined($basis_stream_deny{$stream2}) and `$::AccuRev ismember $principal "$admingrp"` == 0 ) {
   print TIO "Basing a new stream on existing stream '$stream2' disallowed:\n";
   print TIO "server_admin_trig: You are not in the $admingrp group.\n";
   close TIO;
   exit(1);
  }
}

There are other facilities in AccuRev to control the process and workflow too. Stream Locks grant users/groups the ability to promote to and from streams and Access Control Lists (ACLs) grant access to entire depots and subhierarchies.  Setting up these security measures combined with the Admin Trigger provide your organization with the flexible and granular security model it needs for the optimum development process.

Drop me a note and let me know the creative ways you’re using the Server Admin Trigger.

Getting the Most out of AccuRev’s Windows Explorer Integration

As organizations become more advanced in their use of software configuration managment (SCM) they typically expand its use to include more than the software developers.  A common addition is around audibility and compliance of the entire development process which may require them to version more than just the source code, but also any requirements, project plans, design artifacts and documentation.  This enables the labeling of the big picture of who, what, where, why and how the software was developed.

With this expansion there are now more users of the SCM tools, many of whom have never used a version control solution before. A few examples of these new user types may be hardware designers, graphic designers, product managers, or the documentation team. These types of users are working with different types of files, and work in different tools than the traditional software developers and because of that may use version control tools in different ways.  These users may have historically created versions of files using naming convention such as:

 ReleaseNotes_v1.doc, ReleaseNotes_v2.doc etc. all on their local computer.  

Obviously this can be an error prone process and also a single point of failure if something were to happen to that user’s computer.  Since many of the files they work on are binary (.doc, .pdf, .ai, .dwg, .vsd etc.) they may want to work on these files in a serial mode so they don’t have to try to manually merge them when someone else makes changes to them in parallel.  So instead of the traditional use of AccuRev, taking advantage of our parallel development features, these users may want to work in exclusively locked workspaces or at least have exclusive locks on certain files to protect them.

In order to make this new type of user successful they need to use an interface that is familiar to them. With many source code control tools they may have to write scripts, manage configurations or interact with a command line interface to be able to get their work done. This type of interaction will likely not work well for these types of users, as many of them may not have the technical know how to work in those environments.  AccuRev can make this transition much more fluid and familiar for these users with the AccuBridge for Windows Explorer. This interface gives the user access to the AccuRev commands needed from within the familiarity of Windows Explorer as seen in exhibit 1.

 

AccuBridge for Windows Explorer

 

Use Case: Fixing the Broken Build

by Rob Mohr, AccuRev

In one of many travels and customer visits, I came across a very cool way that AccuRev was helping to improve the way development teams do their work. To be more specific, this group was using Change Packages integrated with the JIRA Issue Tracking system to manage changes across their various product releases. They also used CruiseControl for continuous integration that would kick off nightly builds and notify the team with the results of the build.

From what they told me, the success of builds has significantly improved since they started using AccuRev because of the ability for the developers to work in their own private workspaces where they can integrate and unit test before promoting their changes for the rest of the team. Although broken builds are, for the most part, a thing of the past, they will still occur once in a while and need to be fixed ASAP.

Here is how they do it with AccuRev

The stream structure below is a simpler view of their overall software development process, but will be sufficient to show the use case.

Promoting to the Integration Stream

To start, the 4 developers below have made changes in their workspaces that will be promoted and associated to 4 different issues.

As you can see below, the integration stream (EntSoft_Client_Int) is “aware” of which issues are active in the stream. These are the new “change packages” introduced in the stream to be included in the next nightly build.

Build Fails in the Integration Stream

The next morning, the team is notified that last nights build failed via an email notification from CruiseControl. They have also scripted CruiseControl to automatically enable a time based stream called the “Temp_Fix_Build” stream and assign the appropriate transaction number to rollback the change packages from last night.

Assign the Developer to Fix the Build

One of the developers creates a workspace on the Temp_Fix_Build and “change palettes” over each change package one at a time.  This gives them the ability to mix and match change packages together to determine which one of them is the problem.

Problem Solved

After the culprit is fixed, the repaired change package(s) are promoted back into the integration stream for all to share.

The AccuRev CLI – Going beyond SCM

By Ryan LaNeve, AVI-SPL

Much has been written on this blog already regarding the ease with which AccuRev allows you to tailor your development process without having to fight with your SCM software. While I could offer yet another account of how simple and straightforward it is to manage our particular process using AccuRev, instead I thought I’d take a few minutes to point out some of the things we’ve done using the tool’s command-line interface and its ability to output results formatted as XML.

Of the various tools we have created over the years, the two we find most useful are what we call “AccuLoad” and “SQL Object Scripter”. The former pulls data out of AccuRev, while the latter puts data into AccuRev. Both were developed in a matter of hours thanks to the extremely intuitive command-line interface which AccuRev provides. Let’s take a closer look at each.

We’ll start with our “SQL Object Scripter”. Anyone whose development efforts involve a database server knows how difficult it is to maintain change logs for the “code” kept within the database. There are a number of “best practices” with regards to maintaining this information within an SCM, but in our experience they are all too time-consuming and involved, which leads to one or more members of the team either forgoing the process due to time constraints or just ignoring the process all together. Maybe we’ve just become spoiled by AccuRev allowing us to work exactly the way we want and otherwise staying out of our way, but we now have a hard time following any procedure which requires us to change the way we do things.

So one day a couple of us sat down and decided to find a new solution. We felt that, at a minimum, what we really wanted was to be able to view changes over time for our database objects, such as tables, views and stored procedures. We knew that if we could just get each change into AccuRev some of our issues would immediately disappear, but we found it too difficult to require the entire team to manually create every script and then manually promote that script into our SCM. We decided that what we needed was a tool that could simply detect changes to our database objects and automatically store those changes within AccuRev. Again, thanks to the simplicity of AccuRev and its CLI, our “SQL Object Scripter” tool was born in a matter of hours. We now have a record in AccuRev of (almost) every change made to any database object we care about, which then allows to use the features of AccuRev to view the history of any object, the differences between any versions of any object and even an annotation of any object to see who is responsible for the make-up of the object. The solution consists of a few parts: a SQL Server table to store DDL change event details, with a DDL trigger on the various databases we care about. The trigger fires whenever a DDL event occurs, such as the creation or alteration of a table, view or stored procedure, and the details of the event get logged to a table. Our custom console app is then scheduled to run every few minutes and checks the table for any records. When a record is found, the console app scripts out the definition of the object to a file and then uses the AccuRev CLI to add/keep/promote the file to our “SQL Scripts” depot – whatever is appropriate depending on whether the object is brand new or pre-existing and has been changed. The AccuRev commands all run within the context of whichever user made the change in the database itself, so all of our AccuRev transactions are associated with the correct team member. While this solution is not optimal and does not provide as much traceability as having each developer maintain and promote database change scripts themselves, we have found it to be an excellent interim solution which was extremely easy to put together.

Another of our tools is the one we call “AccuLoad”. The purpose of this tool is to pull various bits of information out of AccuRev and load that information into a database. We then use the information in the database from several other applications. The tool is a console application which runs in a couple of different modes, but the primary mode is run via an AccuRev trigger. Whenever a promote happens in one of our depots, our custom trigger runs and fires up our console app, passing in a few details such as the name of the depot, the name of the stream and the transaction number of the promote. AccuLoad then takes this information and makes various calls to the AccuRev CLI to gather more details, such as which elements were included in the promote, the version numbers of each of those elements, the user who performed the promote, etc, etc… Additionally, a diff is run against any changed elements, and those details are stored in the database as well. Gathering all of this information from AccuRev was extremely simple thanks not only to the intuitive nature of the functionality exposed by the AccuRev CLI, but also thanks to the option of having the results returned as XML. While I’m sure it would have been possible to create such a tool using any SCM, I doubt we would have ever found the time to do so had we not been fortunate enough to have AccuRev as our SCM. It was, again, only a matter of hours from the time we came up with the idea for AccuLoad and the time our first promotions were being logged in our database.

Having this database detailing the activity in our SCM, we were then able to create several other tools to utilize the information, such as one we call “AccuBrowse”, seen below. This web-based application allows us to browse the database and view any transaction within any stream of any of our depots, and see who performed the promote, the comments supplied during the promote, the elements included in the promote and the differences for any changed element. I should mention that much of this functionality is probably available in the AccuRev Web Interface, though we have not actually used that tool provided by AccuRev. Ours was created a couple of years ago and suits our needs. Beyond just allowing us to browse our SCM history via a web-interface, our database also allows us to perform some analysis, such as frequency of change for elements within a specific depot or stream, which allows to keep tabs on classes within our systems which may have too much responsibility. We can even run queries against the data to find “problematic” code, such as those files most often included in promotions which cause a failed build (not that our builds ever fail, of course…).

In summary, there are a myriad of fantastic features and functionality within AccuRev which make it a great fit as an SCM for any development environment. Once you’ve got your core needs taken care of by the out-of-the-box functionality, I encourage you to explore what can be done with the provided CLI and its XML-formatted output. In our experience, if you can imagine it, you can build it with AccuRev in no time at all.

Our custom AccuBrowse application, viewing a transaction involving a SQL Server stored procedure:

Dr. Strangecode, or How I Learned to Stop Worrying and Love Old Code

by Chris Boran

Several years ago I happened to be browsing in my favourite local bookstore and one book in particular caught my eye: Martin Fowler’s Refactoring: Improving the Design of Existing Code

This is the book that changed my whole career. Up until that point, I had lived in a constant state of fear of change. I viewed old code as a house of cards – if I wasn’t very careful, it was all going to come down around me. Whenever my boss asked me for advice about what to do in a given area of the code, my answers were almost always similar to:

The risk of doing anything but the smallest possible change is huge – so either we do something that is an ugly hack that we will regret later, or we need to take the whole thing apart and re-implement the whole subsystem from the ground up.

And predictably, my boss’s answer was always something like:

Okay, we will live with the hack for now, but in the next release we will make time to do it right.

Of course every release we were forced to make many similar decisions. When the next release would come, the newly conceived product features would get priority over fixing code that was already working passably. In practice we might get lucky and be able to spend lots of time rewriting a single small subsystem, but introduce ugly hacks that would put 4 other systems on the map for future re-implementation.

The end result is affectionately referred to as a Big Ball of Mud. Yup, it is every bit as pleasant as it sounds. Life is just so miserable when you come to work every day knowing you are going to have to pack another layer of mud on the ball. You gripe about it. Your teammates gripe about it. Your boss gripes about it. Somehow you never seem to make a whole lot of forward progress.

As I read the book, I was at first skeptical. I thought that bad old code needed to be thrown away and not revitalized! But I wanted to see if it would work, and so I set out to try it. I was very careful to follow the techniques exactly as they are laid out in the book. I made sure not to use the word refactor when I really meant rewrite. I was careful to refactor the code every time I saw something I wanted to change and not just note it for later. I made sure that my refactorings were small. I took my time with it.

Obviously working this way required that I also be doing very good unit testing, but I had already bought into Test Driven Development. I was already writing unit tests for code before fixing bugs in an attempt to prevent regressions. Running these tests after each refactoring was not a big challenge for me.

Bit by bit I discovered the truth. By applying the refactoring techniques, I could take pieces that I thought needed to completely rewriten and make them better while I was fixing bugs in that area. I could kill two birds with one stone.

Then I discovered Eclipse. The built-in refactoring browser captivated me. Suddenly there was a good, fool proof way to do many of the common refactorings, and automation to keep them introducing new errors. My commitment to refactoring was completed and the defect rates in the code that I was responsible for maintaining declined dramatically. I was a convert. Since that time refactoring has been a cornerstone technique in my arsenal. I no longer lived in fear and loathing of old code!

One refactoring that I have still found to be painful, despite Eclipse’s facilities, is renaming files/classes. In most software configuration management (SCM) tools, renaming files can have unfortunate unintended side effects because the identity of a file is its path. This leads to a great many developers to name a class once, and then never change its name – even if that name does not make sense and the design of the code and the classes primary purpose and responsibilities change.

Luckily for me, I am a long time Accurev user. In Accurev, files are not identified by their pathnames, but rather by a unique id. This makes it possible to quickly and easily rename files with no negative side effect. However this process was inconvenient – I would have to drop out of Eclipse, rename the file with Accurev’s tools, and then refresh my workspace. Not ideal, but it worked. That is why I was so pleased when the Accurev-Eclipse Plugin was released – it integrated the Eclipse Refactoring browser’s rename actions with Accurev’s capabilities to make the whole experience seemless. Accurev has helped me to maintain well thought out, easy to understand designs despite constant evolution to those designs.

Person Martin Fowler’s

Right click for SmartMenu shortcuts

AccuRev naming conventions

By Tomas Lundström, ReadSoft

A consistent naming scheme makes your life easier and is also a good way of avoiding name clashes in AccuRev. Here follows my stab at it. (With one important disclaimer; for multi-depot installations, you should use a depot prefix for all streams, to avoid name clashes between depots)

 

AccuRev Codelines and Baselines

The following naming rules apply:

• Character set. For scripting compatibility, allowed characters are English alphanumericals, underscore ‘_’, hyphen ‘-’ and period ‘.’.
  In particular, blanks, Swedish characters and slashes are disallowed.
• Case. Product names and keywords exclusively use ALL UPPER CASE, other text and component names use mixed case.
  Examples:APPROVE_REL, Libraries_DEV
• Main codeline streams: <CODELINE>_<LEVEL>
  Examples: APPROVE_REL, DOCUMENTS_DEV
  In the basic case, there are two (optionally three) levels of streams for a codeline:
  • REL. Release stream, where final main releases of products are done.
  • QA. QA stream (optional). If not present, the REL Stream serves QA as well
  • DEV. Development stream where developers share code, and perform initial integration.
    
• Maintenance codeline streams (‘branches’): <CODELINE>_<VERSION>_<LEVEL>
  Examples: APPROVE_5-1_REL, DOCUMENTS_6-3_DEV
  Maintenance codelines may be single level, in which case it shall have the level REL, or it can be two or three levels, just like a main codeline.
• Other codeline streams: <CODELINE>[_<VERSION>]_<PURPOSE>[_<LEVEL>]
  Examples: APPROVE_portToVS2005, APPROVE_5-1_hotfix47
  These streams are used for e.g. hotfixes, service packs, substantial tasks, subprojects, teams, experiments and acceptance tests. Most streams will be single level, so the level can be omitted. In most cases, the version can be omitted as well, since it will be evident from the context (i.e. its parent stream).
• Snapshots: <PARENT STREAM>_<TIME>[_B<BUILD#>][_<PURPOSE>]
  Example: APPROVE_5-1_REL_D051127T1347_B6365_iRC01
  
• Workspace Streams: <PARENT STREAM>[_<host>|<number>]_<USER>
  Normally the default scheme should be used, where the AccuRev wizard attaches the user name to the stream name, i.e. the user name should never be explicitly written out when creating a Workspace!
  If a user has several workspaces on the same stream, they have to be distinguished by some kind of identification. For workspaces on different computers, the host name shall be used. For workspaces on the same computer, an integer number shall be used.
  Examples: APPROVE_DEV_3_tomas, APPROVE_DEV_buildserver12_tomas
  
• Reference Trees: <PARENT STREAM>_RT[_<PURPOSE>][_<host>|<number>]
  A reference tree cannot have the same name as an existing reference tree or workspace. In case of conflict, use the same distinguishing naming rules as for Workspaces.
  Example: APPROVE_REL_RT_NIGHTLYBUILD_buildserver12
  
• Pass-through streams: <CODELINE>_PT_<PURPOSE>
  No changes ‘stick’ to pass-through streams. However, include/exclude rules apply, so they can e.g. be used for grouping other streams/workspaces that share visibility rules.
  Example: Documentation_PT_APPROVE

<CODELINE> is typically a product or component name, such as APPROVE or Utilities

<VERSION> is the commercial product version, e.g. 5-1

<TIME> is on the form: Dyymmdd[Thhmm] Time is optional.

<PURPOSE> is used for additional comments:

• Hotfix number (HOTFIXyy)
• ServicePack number (SPyy)
• Release Candidates (iRCxx, eRCyy)
• Other useful freetext information about the purpose of the stream, such as:
  • For customer specific development (e.g. pilot projects): the company name
    Example: APPROVE_Volvo

For tasks: The task name and/or unique identifier
Example: APPROVE_PurchaseOrders

 

best regards,

/Tomas

Build Management with AccuRev and Maven

Build management is a long-overlooked area of software development. As is often the case with underserved areas, the open source community has several good solutions. Maven is among the most interesting and functional solutions for Java developers. I had the chance to take the AccuRev-Maven m2eclipse integration out for a test drive recently. This is a recently announced integration (read the press release here if you are interested, and see my video demo here).

The integration follows the pattern of other software configuration management (SCM) integrations with m2eclipse. A backend provider interface was written to support AccuRev, and the provider was integrated into the m2eclipse environment via the SCMHandler mechanism. I used m2eclipse in conjunction with AccuBridge for Eclipse (the AccuRev-provided Team plugin) to materialize Maven projects into a new AccuRev workspace from within Eclipse, and then did some basic Maven build and AccuRev SCM operations.

To get started, I needed to install m2eclipse from Sonatype. I used the Eclipse Update Manager to do this, by creating a new remote site in Update Manager for Sonatype (http://m2eclipse.sonatype.org/update/). I already had the AccuBridge for Eclipse plugin installed, also obtained via Update Manager (http://www.accurev.com/download/eclipseupdate/32/). After restarting Eclipse, I was ready to test.

In my test environment, I had an AccuRev stream called maven_int that I had pre-loaded with (of all things) the source and test code for the Maven integration itself. My goal was to create a new AccuRev workspace based on this stream from within Eclipse that was Maven- and AccuRev-aware. To do this, I used the Eclipse Import functionality and selected the “Checkout Maven Projects from SCM” option. Since I was using AccuRev, I chose the AccuRev provider from the drop down list box. Like other integrations with Maven, AccuRev supports a URL format for specifying where to obtain code. The URL lets you specify the AccuRev user and login credentials, as well as the exact depot and stream from which to import the code. I also chose the make workspace checkout option, which tells the plugin to create an actual AccuRev workspace in a specified location.

After pressing the Finish button on the Import wizard, m2eclipse called out to AccuRev, created a new AccuRev workspace, and created new Eclipse projects (based on whatever Maven POM files were found in the maven_int stream) containing the source code. I then associated the Eclipse projects with AccuRev using the Team Share option so that I would have full access to AccuRev functionality.

Since the projects were all Maven-based, building was done by right clicking on the POM file and selecting one of the build options. To convince myself that the AccuRev functionality worked, I did some edits to a few files, saved the changes, and then used the AccuRev promote option to version that file in the AccuRev repository.

Overall, the integration worked as I expected. The installation of the plugins was fast, it was easy to materialize Maven-based projects from AccuRev, and all of the important Maven and AccuRev functionality was available in the respective plugins. If you are an AccuRev user and want to use Maven, then the combination of m2eclipse and AccuRev integrated inside of the Eclipse environment is a practical desktop tool for managing your local builds.

 

Take Back Control: Using LDAP for SCM Authentication

Yesterday, just for fun, I counted the number of times that I logged into a computer or website. Once to login to my PC. Once more to connect to the company network. Three times for the 3 different UNIX boxes I needed to work with. And (if you promise not to tell my boss) once to login to a popular online shopping site to cancel a book order that apparently was lost in shipping. That’s six times in a day – and a slow day at that.

All this logging in got me thinking about security, authentication and of course, software configuration management (SCM) systems. Most SCM users, unless they are in the computer security business or are otherwise paranoid, don’t think about what goes on when they type in their user name and password and press Enter. In this post, we’ll peel back the covers a bit and show how you can use LDAP as the authentication mechanism for the AccuRev SCM system.

Starting with version 4.6, AccuRev introduced the notion of a ‘custom’ authentication mechanism. If you boil it all down, there are only three things that you need to do in order to use LDAP authentication with AccuRev:

1. Tell the AccuRev server that you want to use custom authentication

2. Create users in AccuRev and in LDAP

3. Write a special AccuRev trigger that authenticates the users against an LDAP server

Let’s look at each of these in turn. First, a word of caution. As with any change to a shared production system, it is best to practice this in a safe environment. If you don’t have a spare AccuRev server laying around, you can always download the free 30 day, 5-user evaluation kit and use it to fine tune your new authentication process.

Now to the details. To tell the AccuRev server that you want to bypass the built-in authentication mechanism and use a custom method, execute the following command:

accurev authmethod custom

Next, you’ll need to create some AccuRev users. In this example, we’ll assume that you’re already using LDAP for other applications, and therefore user entries already exist in the LDAP server. A typical user in an LDAP server might look like this in LDIF format:

dn: cn=James T. Kirk,o=engineering,dc=enterprise,dc=com
objectclass: top
objectclass: person
objectclass: inetOrgPerson
objectclass: organizationalPerson
cn: James T. Kirk
sn: jtkirk
mail: jtkirk@enterprise.com
userPassword: jtkirk

Well, typical if they happen to be the captain of the most famous starship ever! But I digress.

In AccuRev, we need to decide how this user will be represented. In this example, we’ll use the LDAP ‘commonName’ attribute, which is shown above as ‘cn’, as the AccuRev username. Here’s the command we’ll use to create that user in AccuRev:

accurev mkuser “James T. Kirk”

At this point, we have a user represented in LDAP, and that same user represented in AccuRev. All we need to do is to tell the AccuRev server how to authenticate this user via LDAP. We do this via an AccuRev trigger known as the ‘server_auth_trig’. Here is some sample code for a server_auth_trig that does just that:

use Net::LDAP;
use Net::LDAP::Util qw(ldap_error_text);
use Net::LDAP::Constant qw(LDAP_SUCCESS
            LDAP_CONNECT_ERROR
         );

use XML::Simple;
use strict 'vars';

# Server info for contacting LDAP
my $LDAP_HOST = "localhost" ;
my $LDAP_PORT = "389" ;

# We explicitly list the subtree DN to use when rewriting the incoming username as an LDAP Bind DN.
my $ldap_baseDN = "o=engineering,dc=enterprise,dc=com" ;

# Default attribute name for binding.  This attribute is concatenated
# with the incoming username and the ldap_baseDN above to form
# a Bind DN.
my $ldap_bind_attribute = "cn" ;

sub main
{
    my ($xmlinput);
    my ($command, $ip );
    my ($username, $password );
    my ($result);

    # populate array using XML::Simple routine, reading from stdin
    $xmlinput = XMLin('-', forcearray => 1, suppressempty => '');

    # set variables
    $command = $$xmlinput{'command'}[0];
    $ip = $$xmlinput{'ip'}[0];
    $username = $$xmlinput{'username'}[0];
    $password = $$xmlinput{'password'}[0];

    # First, establish a connection to the LDAP server
    my $LDAP = Net::LDAP->new($LDAP_HOST, port => $LDAP_PORT) ;
    unless ($LDAP) {
                print "Unable to connect to LDAP server on host $LDAP_HOST at port $LDAP_PORT.\n" ;
                return LDAP_CONNECT_ERROR;
    }

    # Now that we are connected, rewrite the username as a DN and attempt to bind to the server
    my $ldap_bindDN = $ldap_bind_attribute . "=" .$username . "," . $ldap_baseDN;
    print "Attempting to bind as: $ldap_bindDN\n" ;

    my $mesg = $LDAP->bind($ldap_bindDN, password => $password) ;

    # 'code' method contains any error code from the bind call
    # including success, so we return it to the caller
    my $return_code = $mesg->code;
    print "LDAP_BIND returned: $return_code\n";

    # Now unbind to free the connection
    $LDAP->unbind;

    # return the auth code to the AccuRev server
    exit ($return_code);

}

# run main routine
&main();

The main trick is to ‘rewrite’ the incoming user name in the form of an LDAP Distinguished Name, or DN, and then to use that DN and the incoming password to bind to the LDAP server. Binding is a fancy word for logging into the server. Typically this is done by providing a DN (to uniquely identify the user) and credentials (in this case, a password).

As we said earlier, we’re using a convention in this example that the incoming user name represents the ‘commonName’, or cn, attribute of the user’s LDAP entry. We then construct a string by concatenating the cn with a hard-coded base DN, the latter representing the subtree within the LDAP server where the users exist. The resulting DN in this example is:

cn=James T. Kirk,o=engineering,dc=enterprise,dc=com

which is represented in the example as the perl variable $ldap_bindDN. If the bind is successful, the trigger returns a 0, and the user is logged into AccuRev. If the bind fails, the trigger returns a non-zero code, and the user login is rejected.

There you have it. A few simple steps and you can use the industry standard LDAP mechanism to provide authentication for your AccuRev users. LDAP is used in all sorts of enterprises, from education to technology companies to government, and so is AccuRev, so we’re glad to provide a way for our customers to use this powerful and ubiquitous authentication mechanism.