( transcript for https://www.imagix.com/apps/Delta_Analysis.mp4 ) Comparing Revisions of Source Code [0:00] Before getting into the demo, let's talk about why -- why Delta Analysis. The central concept of Imagix 4D's Delta Analysis is that it performs comparisons between different versions of software. Typically, these would be different revisions of the same source code. But they could also be different branches of software that share the same origins, or they might simply be different builds of the same exact source files. Essentially, Delta Analysis compares two sets of software that have enough in common that you'd like to understand their differences. As you know, there are already tools out there for comparing versions of software. The most common and fundamental of these is diff. Diff exists as a standalone file difference tool that's available in many varieties. Diff is also integrated into many source control systems, so that they're able to report out the lines that have changed between two versions of the same file. The limitation of diff is that it provides no perspective on the meaning, scope and impact of changes at the source file level. Without examining and comparing each modified line of source code, there's no way to know which are the significant differences and what their impacts are. Whether the changes conform with any planned design improvements. Whether problems have been introduced into the uses and dependencies of symbols. What testing needs to be done to validate the changes. Etc. It is to address all of these questions that Delta Analysis has been created. The objective of Imagix 4D's Delta Analysis is to let you see, understand and methodically review software differences from higher level perspectives. You can see the impact of the changes on the overall control flow hierarchy of your code. You can also examine the changes within the context of the file structure, etc. At any time you can drop down and examine the changes at the level of lines of source code, but you're able to keep big picture perspective as you do so. You thereby avoid getting lost in every little detail. [2:06] So now let's look at some examples of Delta Analysis results and how they are displayed. For this demo, we'll explore ngspice, an item of open source software. As we can see here in the Project Summary tab, ngspice is written in C, there are nearly 2000 files, most of which are source files. And there are about half a million lines of source code. We'll be comparing version 28 of ngspice with the earlier version 26 of the same software. For the sake of familiarity, we'll start with the Delta Analysis's Diff Tool, which works like a standard diff tool. Let's look at this function, 'fileInit_pass2'... Focusing the Diff Tool on the function opens it to where the function is defined in the current version, in the file 'outitf.c'. The Diff Tool also opens the revision version of the file, automatically. You can see the current version of the source code on the left, and the earlier revision on the right. The lines that have changed between the two versions are highlighted. Here in the Diff Tool, and throughout the rest of Delta Analysis, green is used to flag content that is unique to the current version, and red to represent the parts of the software that only exist in the earlier revision. So in this green area here, we're seeing lines that have been added into the current source code. The gray on the revision side indicates that there are no equivilent lines in the older version of the file. And higher up the file, these tan areas highlight lines that have changed. To help you spot the actual differences, the diff tool highlights the changed characters with a darker tan background. We can see that there are several differences between versions of the file, but it's not immediately clear what's going on. To find out, we'd need to use the Diff Tool to read and study many of the changed lines of source code. Or, we can start with the delta graphs to get a perspective. [4:08] Our original starting point was a call graph of 'fileInit_pass2' displayed in one of Imagix 4D's standard graph windows. Let's look at the same function in a delta graph window. The resulting delta graph uses the same coloring convention as the diff tool. Again, green represents symbols and dependencies that exist in just the current version of the software, and red indicates symbols and relationships that are unique to the earlier revision. We can see that a new function, 'guess_type', has been added, and that 'guess_type' rather than 'fileInit_pass2' makes the calls to 'substring' and 'cleq'. We might hypothesize that a portion of 'fileInit_pass2' has been partitioned into a new function, 'guess_type'. Let's check if there's anywhere else that 'guess_type' is used... What we see is that 'plotInit' also uses the new function. And again, the calls to 'substring' and 'cleq' from 'plotInit' have been replaced by the calls made through 'guess_type'. So now it looks like maybe parts of a couple of functions have been combined and merged into the new shared function, 'guess_type'. We have some structural perspective about the changes that have taken place. So now when we look at the two versions of the source code in the Diff Tool, we're not starting from scratch, but we're able to examine the detailed changes within a general framework. [5:30] Let's look at 'guess_type' using the Diff Tool... Here we can see that 'guess_type' does indeed implement the internals of the for loop in the earlier 'fileInit_pass2'. We can also see that a couple of else-if conditions have been added, related to 'inoise' and 'onoise', and that these are the branches that add the use of 'ciprefix'. Now, if we examine 'plotInit', we can see that a large portion of the inside of its for loop has also been partitioned into the new 'guess_type' function. At this point, we might want to stay in the Diff Tool to dive down into the source level details, and insure that the merge was proprerly done. [6:15] Alternatively, we might want to move up for an even higher level perspective on the change. Let's switch to an architectural view of the symbols involved... Here in the Subsystem Architecture diagram, we see that the changes and dependencies we've been examining are all closely related, within the 'frontend' subsystem of the 'src' subsystem. By expanding out the architecture, we can gain further persepctive. By clicking on the outer subsystem, we can see the rest of the overall architecture... And by expanding the 'src' subsystem, we can see where the 'frontend' fits within the 'src' layering. Notice that while we do this, additional green and red lines appear, indicating dependencies that only exist in the current or revision versions of the software. Subsystems that only exist in the one or the other are also shown in green or red, as you can see when I expand the visualc subsystem. To get more detail about what a specific dependency represents, you can focus a new graph on that line. Here we're able to see the dependencies introduced from the new subsystem within 'visualc'. The green area on the right indicates code introduced in the current version of the software. We can see the hierarchy of directories and files, culminating in the green rectangles representing new functions. The dashed lines coming out of those functions show variables being read. The lines are green because, again, these variable reads did not exist in the revision source code. And on the left side of the the diagram, we can see the particular member variables being accessed. So far in this demo, we've started by examining specific portions of the software changes, and explored their meanings and related changes by following the chain of dependencies around the code. This approach is most appropriate when you're trying to understand the differences between two versions, to deduce why code was changed, or how a bug might have been introduced, or whether two versions of similar code can be merged. [8:15] But there might be times when a more methodical, top down exploration of the changes is desirable. This might particularly apply in a QA environment where you're trying to compare to a list of expected changes, to make sure that all of the expected changes were implemented, or that no unexpected changes slipped in. Or perhaps if you're trying to develop tests to make sure that all of the actual changes are exercised by your test cases. For such applications requiring methodical, structured reviews of the changes, you'll want to use Delta Analysis's reports... These use a table format to indicate all the changes between the current and revision software. In the Delta Analysis Summary report, there is an entry for every source file in the software that is associated with a structural change. The first column lists any functions or variables that have been deleted from the file, and the second columns shows any that have been added. The third column shows any new or deleted function calls or variable accesses made from the functions defined in the file. The changes referenced in the fourth column may not have actually occurred within the file itself. The column flags any symbols defined in the file whose use has changed between two versions of the software. These changes often result from a function being modified in a separate source file. So even though the source file itself hasn't changed, you're made aware that it contains symbols being used differently, and you can decide whether you want to review or test those uses. [9:43] To see more detail about the changes, you can open the Delta Analysis report specific to that file or class. Let's take a look at the Delta Analysis report for 'outitf.c', which is where many of the changes we examined earlier occurred. This Delta Analysis report contains the same four columns as the summary report. But you can see that there is much more detail provided about each change. Rather than simply listing the symbols involved, the report itemizes every structural change. As previously, the third column shows any new or deleted function calls or variable accesses made from the functions defined in the file. Let's look at the entry for 'fileInit_pass2'. Note that 'fileInit_pass2' is blue. Throughout Imagix 4D, functions are listed in blue, and green is used for variables. If you look closely, you can see that the green used to indicate variables is somewhat different than the green used in this report to list a relationship that exists only in the current version of the code. Here under 'fileInit_pass2', there's a red calls entry, meaning 'fileInit_pass2' only calls 'cieq' and 'substring' in the revision software. And the green calls entry indicates that the call to 'guess_type' is only made in the current code. Notice also the C that preceeds 'guess_type'. That indicates that 'guess_type' only exists in the current version of the software. One other item to notice here. The 'cieq' and 'substring' as well as all of these 'SV_' variables being read are all preceeded by an e. This is alerting us that these symbols are all defined externally, somewhere outside of the current file. [11;27] In this way, every single structural change involving a specific file or class is identified. The resulting list can be used to methodically review each change to insure that it meets spec or that it is properly tested. This report can be exported for communication and documentation. Or for an even more rigorous approach to recording and auditing every change, you can invoke Imagix 4D's Review tool... From the Delta Analysis results, the Review tool will create a guided checklist that itemizes every change. In creating the checklist, you're able to control which types of changes to include. We won't go into the Review Tool here. Let me just mention that by applying the resulting checklist, the Review tool will automate a series of steps, leading a reviewer through visualizing, exploring, and confirming each change. And the process generates an audit trail covering each and every item being reviewed. [12:26] Imagix 4D's Delta Analysis presents information about structural differences in a variety of displays and levels of detail. The graphic visualization can be especially helpful if you're doing development work trying to understand and examine what is different between two versions of software. The reports, which provide a complete, structured map of the changes from one version of software to another, can be easily applied to direct QA and testing activities. And to guide, automate and document a rigorous review of changes, the Review Tool is available. All of these support analysis of software differences at the structural level.