Com An I Guide
User Manual:
Open the PDF directly: View PDF .
Page Count: 17
Download | |
Open PDF In Browser | View PDF |
Commit Analysis Infrastructure (ComAnI) Guide November 17, 2018 Christian Kröher kroeher@sse.uni-hildesheim.de Implemented in: Java, Version 1.8.0_181 Used on: Windows, Ubuntu Licensed under: Apache License, Version 2.0 Usage of external libraries (infrastructure): none Usage of external libraries (non-third-party plug-ins): Software Systems Engineering University of Hildesheim • • none Institute of Computer Science Universitätsplatz 1 • 31134 Hildesheim • Germany Acknowledgment 2 This work is partially supported by the ITEA3 project REVaMP , funded by the BMBF (German Ministry of Research and Education, https://www.bmbf.de/) under grant 01IS16042H. Any opinions expressed herein are solely by the author(s) and not by the BMBF. A special thanks goes to the developers of KernelHaven [9, 3, 4]: Adam Krafczyk, Sascha El-Sharkawy, Moritz Flöter, Alice Schwarz, Kevin Stahr, Johannes Ude, Manuel Nedde, Malek Boukhari, and Marvin Forstreuter. Their architecture and core concepts signicantly inspired the development of ComAnI. In particular, the mechanisms for lebased conguration of the infrastructure and the plug-ins as well as loading and executing individual plug-ins are adopted in this work. 2 Contents 1 Introduction 5 2 Overview 6 3 User Guide 8 3.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.2 Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4 Developer Guide 11 4.1 Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2 Commit Extractor Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.3 Commit Analyzer Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 References 17 3 List of Figures 1 ComAnI overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 ComAnI data model 3 ComAnI 4 ComAnI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AbstractCommitExtractor class AbstractCommitAnalyzer class . 6 11 . . . . . . . . . . . . . . . . . . . 11 . . . . . . . . . . . . . . . . . . . 15 Listings 1 ComAnI core conguration parameters . . . . . . . . . . . . . . . . . . . . . 8 2 ComAnI extraction conguration parameters 9 3 ComAnI analysis conguration parameters . . . . . . . . . . . . . . . . . . . 10 4 Blueprint of a ComAnI commit extractor main class . . . . . . . . . . . . . 14 5 Blueprint of a ComAnI commit analyzer main class . . . . . . . . . . . . . . 16 List of Tables 4 . . . . . . . . . . . . . . . . . 1 Introduction The Commit Analysis Infrastructure (ComAnI) is an open and congurable infrastructure for the extraction and analysis of commits from software repositories. For both tasks, individual plug-ins realize dierent extraction and analysis capabilities, which rely on the same data model provided by the infrastructure. and analysis plug-ins is possible. Hence, any combination of extraction For example, we could rst conduct an analysis for a software hosted in a Git repository [2] and later conduct the same analysis for a dierent 1 software hosted by SVN [1] . Another example is to use the same commit extractor, e.g., supporting the commit extraction from Git repositories, for dierent analyses. The denition of a particular ComAnI instance consists of a set of conguration parameters saved in a conguration le, which the infrastructure reads at start-up. Hence, there is no implementation eort needed. The infrastructure automatically performs its internal setup, loads and starts the desired plug-ins. ComAnI represents a large increment of the ComAn toolset [10]. This toolset uses a single commit extraction script and a Java-based implementation of a particular commit analysis [6, 7, 5]. Further, the toolset is designed to be applied to the Linux kernel [8] and its Git repository [11]. This design of ComAn restricts its applicability to other software and repository types. While it is not completely impossible to adapt it to other inputs, this adaptation requires mayor implementation eort. Hence, we decided to create a complete infrastructure, which realizes a exible and highly congurable ecosystem for conducting a variety of analyses by means of plug-ins for commit extraction and their analysis. This guide consists of three parts. The rst part in Section 2 introduces ComAnI in more detail and describes the concepts realizing the core features of the infrastructure. Section 3 represents the second part, which focuses on the end user of ComAnI. We describe how to download, install and execute the core infrastructure as well as the available plug-ins. As part of the execution, we also discuss the conguration parameters and the denition of particular ComAnI instances. The third part of this guide focuses on the developers. In Section 4, we discuss the development of new extraction and analysis plug-ins by examples. 1 Assuming that the analysis is able to cope with the artifacts and their technologies of the new software under analysis. 5 2 Overview ComAnI is designed to support the extraction of commits from dierent version control systems and various analyses of those extracted commits in any combination. For this purpose, it oers an open plug-in infrastructure implemented in Java. The core components of this infrastructure are the commit extractor, the internal data model, the commit analyzer, and the conguration le as illustrated in Figure 1. In this section, we will describe these components in detail. Software Repository Commit Extractor Commit Analyzer Data Model Analysis Results Configuration File Figure 1: ComAnI overview A commit extractor is a ComAnI plug-in, which is responsible for the extraction of commits and their provision for the commit analysis as elements of the internal data. 2 depending on the given A commit extractor typically supports three extraction variants sources from which the commits shall be extracted: • Full repository extraction : this variant forces the extraction of all commits of a software repository. This requires the denition of the location of the target repository as part of the conguration le. • Partial repository extraction : instead of extracting all commits of a software repository, this variant allows the extraction of a predened set of commits. Besides the location of the target repository, this requires the specication of an additional le, which contains a list of unique commit numbers (or hashes). Each line of this commit list le must contain exactly one commit number. Further, the author of the commit list le must ensure that the commit numbers specify commits of the target repository. • Single commit extraction : the third variant oers an interactive mode, in which the content of a single commit can be passed on the command line as an input. The available extractors are introduced in Section 3.1. Section 3.2 describes their de- nition for a particular ComAnI instance and the usage of the dierent extraction variants above. Further, Section 4.2 explains the development of new extractor plug-ins for custom commit extraction capabilities. The internal data model represents the conceptual interface between commit extrac- tors and commit analyzers. It oers two main elements for representing commits: Commit itself, which provides information, like its id (the commit number) or the ChangedArtifact for storing the information about the artifacts changed the date, and by a spe- cic commit. Hence, each commit typically contains a list of changed artifacts, which in 2 While the respective methods need to be implemented by each commit extractor, developers are free to realize the required algorithms. Hence, we cannot guaranteed that all extractors support all extraction variants. We recommend reading the description of the desired commit extractor for more information. 6 turn contain information about their name and location as well as their content including the changed lines. A commit extractor creates instances of these elements based on the extracted commits from a target repository or the content of a commit passed as command line input. Section 4.1 provides further details about the internal data model and its elements. The elements of the internal data model are input to a a ComAnI plug-in similar to a commit extractor. commit analyzer, which is Depending on the core algorithm of the respective analysis, a commit analyzer may either wait until all commits are available or directly start processing at the time a commit is available. The infrastructure neither imposes any restriction on the way of processing nor on the analysis results. Hence, each commit analyzer has full control over its result creation. The only input it receives is an output directory in which the results can be stored. While the available analyzers are introduced in Section 3.1, their denition for and usage in a ComAnI instance are described in Section 3.2. Section 4.3 explains the development of this type of plug-ins in detail. The conguration le in the lower part of Figure 1 denes a particular setup of the commit extraction and analysis and, hence, a specic instance of ComAnI. It consists of a set of conguration parameters for preparing the infrastructure (input and output locations, etc.) as well as dening the desired commit extractor and analyzer plug-ins. The infrastructure reads these parameters to congure ComAnI prior to its actual execution. Section 3.2 introduces the available conguration parameters and their denition for a particular ComAnI instance. 7 3 User Guide Some introduction... 3.1 Installation 3.2 Execution 1 # The 2 # 3 # 4 # Type : 5 # Default value : 6 # Related parameters : 7 path like to the the directory , available which extractors contains and the ComAnI plug −i n s , analyzers . mandatory none core . plugins_dir none =8 9 # The identifyer of the 10 # 11 # Commit 12 # 13 # 14 # Type : 15 # Default value : 16 # Related parameters : 17 repository the as the extractors respective version input and for control commit analyzers documentations need of system (VCS) , extraction the to support desired which relies the plug the on . VCS . −i n s See . mandatory none none core . version_control_system = 18 19 # The 20 # amount 21 # provide 22 # Valid 23 # 0 24 # 25 # 26 # 27 # 28 # 29 # 30 # 31 # Type : 32 # Default value : 33 # Related parameters : 34 number of at defining particular the log −l e v e l infrastructure as and , hence , well as the the plug −i n s runtime . values − a information are : SILENT : No information be no message is at provided all except and , for hence , there initial setup errors 1 − STANDARD: Basic information , warnings , and errors provided 2 − DEBUG: Similar to information STANDARD, is but additional debug provided optional core . log_level 1 none = < 0 | 1 | 2> Listing 1: ComAnI core conguration parameters 8 are will 1 # The 2 # 3 # mandatory , 4 # 5 # 6 # Type : 7 # Default value : 8 # Related parameters : 9 to fully use reuse qualified in is the main class particular the name ComAnI infrastructure of the instance . will commit extractor Although ignore this being parameter , if enabled . mandatory none extraction . extractor none = < E x t r a c t o r> 10 11 # The 12 # 13 # commits . 14 # 15 # 16 # Type : 17 # Default value : 18 # Related parameters : 19 path to repository this the from directory denoting which commit Although parameter the being in the mandatory , interactive root extractor of a will extractors software extract the will ignore list of mode . mandatory none extraction . input none = 20 21 # The 22 # numbers . 23 # commits 24 # 25 # Type : 26 # Default value : 27 # Related parameters : 28 path to and name Extractors from the of the will file try specified to containing extract repository a the commit corresponding exclusively . optional none none e x t r a c t i o n . commit_list = 29 30 # The 31 # Defining 32 # extraction , 33 # files 34 # analysis 35 # repeating 36 # 37 # IMPORTANT : the 38 # if 39 # 40 # Type : 41 # Default value : 42 # Related parameters : 43 path to the this and directory parameter which reuse allows them processes the directory , in the for saving enables saving future of is analyses , the infrastructure not extracted caching extracted extracted extraction it the commits same deletes commits . feature commits while as the the for the individual current usual . commits for as This avoids future content of analyses . this emtpy . optional none e x t r a c t i o n . cache extraction . reuse = 44 45 # The 46 # this 47 # which 48 # executing 49 # extraction 50 # 51 52 53 # 54 # Type : 55 # Default value : 56 # Related parameters : 57 path to the parameter leads to the directory enables a reuse defined of the # IMPORTANT : if caching # performed caching is containing the of caching previously extractor . same commits and and reusing the This for cached feature extracted avoids future is analysis commits . for Defining extraction , commits repeating at the extracted same none none = Listing 2: ComAnI extraction conguration parameters 9 time , commits . optional extraction . reuse instead the analyses . defined uses the of 1 # The 2 # 3 # 4 # Type : 5 # Default value : 6 # Related parameters : 7 to fully use in qualified the main particular class name ComAnI of the commit analyzer instance . mandatory none analysis . analyzer none = 8 9 # The path to the directory 10 # Each 11 # directory 12 # to 13 # 14 # Type : 15 # Default value : 16 # Related parameters : 17 analysis avoid will named by unintended create the for saving its own name of overriding the of sub the analyis −d i r e c t o r y analyzer previous and results . in a this timestamp results . mandatory a n a l y s i s . output none none = Listing 3: ComAnI analysis conguration parameters 10 4 Developer Guide Some introduction... 4.1 Data Model < > < > ChangedArtifact Commit -changedArtifacts net.ssehub.comani.data -id: String -date: String -commitHeader: String[] 0..* net.ssehub.comani.data -artifactPath: String -artifactName: String -diffHeader: List -content: List Figure 2: ComAnI data model 4.2 Commit Extractor Plug-ins A commit extractor plug-in is responsible for extracting commit information from a software repository and providing this information for an analysis. Therefore it has to create instances of the Commit and ChangedArtifact classes described in Section 4.1 and add CommitQueue. This queue represents the actual connection these instances to the internal between commit extractors and analyzers. AbstractCommitExtractor It is accessible through an attribute of the class, which each commit extractor has to extend. Figure 3 presents this abstract class as well as the extractor-specic commit queue interface. < > AbstractCommitExtractor net.ssehub.comani.extraction #logger: Logger #extractionProperties: Properties < > +AbstractCommitExtractor(Properties,IExtractionQueue) +extract(File):boolean +extract(File,List ):boolean +extract(String):boolean +operatingSystemSupported(String):boolean +versionControlSystemSupported(String):boolean Figure 3: ComAnI IExtractionQueue #commitQueue net.ssehub.comani.data 0..1 +addCommit(Commit):boolean AbstractCommitExtractor class Each commit extractor inherits three attributes: the infrastructure-wide logger, the extraction properties, and the commit queue as shown in Figure 3. The logger provides multiple methods for logging general information about the extraction process, warning, error, and debug messages. The amount of information actually shown, e.g., on the command line, depends on the dened log-level in the conguration le (cf. extractionProperties include all conguration prex extraction., a property providing the name The Section 3.2). parameters, which start with the of the operating system on which the extractor currently runs, and a property for the version control system as specied by the respective conguration parameter in the conguration le (cf. Section 3.2). The commitQueue enables the transfer of extracted commits to an analysis. It only provides a 11 single method, which accepts a single Commit instance as a parameter. Hence, the extrac- tion algorithms have to call this method for each extracted commit individually. Figure 3 also shows that a commit extractor has to implement a constructor, which accepts a properties and a particular extraction queue instance as parameters, as well as a set of methods for extracting commits and checking whether it is executable in the current environment. Listing 4 introduces a blueprint of a commit extractor, which implements all these required elements. This blueprint represents a starting point for each new extractor by implementing the necessary algorithms as follows: 1. Constructor : creates a new instance of the commit extractor and, hence, has to call its parent class' constructor by passing the constructor parameters of the new extractor. Further actions for setting up the particular commit extractor can be performed here as well, which may also throw ExtractionSetupExceptions, if the setup fails. Listing 4 shows the constructor in Lines 16 to 22 including the usage of the logger, which informs the user about its creation (Line 20). 2. Extraction methods : realize the three extraction variants as introduced in Section 2. Each method in the Lines 25 to 41 returns a Boolean value indicating whether the particular extraction variant was successful (true) or not (false). In the latter case, the user is automatically informed about an extraction error indicating that either there are no analysis results or the results may potentially be incorrect. The individual methods have the following purpose: (a) extract (File repository): extracts all commits of the given software repository. The repository parameter identies the directory specied as input (extraction.input) in the conguration le (cf. Section 3.2), which is typically the root directory of a software repository. The particular way of interacting with the supported type of repository depends on the commands and capabilities provides by the version control system. (b) extract (File repository, List commitList): extracts only those commits of the given software repository, which are part of the given commit list. While the above, the repository parameter provides the same information as for the method commitList parameter contains a set of commit numbers (or hashes), which enable to extraction of the respective commits. However, this method is only called if a commit list is dened via the corresponding conguration parameter in the conguration le. (c) extract (String commit): transforms the given information representing the con- tent of a particular commit into a commit of the internal data model. This method is only called in the interactive mode of ComAnI, in which the given string is passed directly as a command line argument. 3. Support check methods : realize the opportunity to restrict the application of a commit extractor to a particular operating system and version control system. In particular, this is important, if, for example, an extractor relies on a third-party library, which is only available for Windows, or if the extractor cannot process other commits than those of a Git repository. A missing support yields a ExtractionSetupException during the creation of an instance of the extractor by the infrastructure, which terminates the entire tool. Each method in Lines 44 to 54 returns a Boolean value indicating whether the extractor supports the respective system (true) or not (false): 12 (a) (b) operatingSystemSupported(String os): checks whether the extractor supports the given operating system. The os parameter provides the operating system in the 3 format of System.getProperty(os.name) . versionControlSystemSupported(String vcs): checks whether the extractor supports the given version control system. The vcs parameter provides the version control system as dened by the core.version_control_system conguration parameter in the conguration le. 4.3 3 Commit Analyzer Plug-ins https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html 13 1 2 3 4 5 6 7 8 9 10 11 12 package import import import import import import import core ; java . io . F i l e ; java . u t i l . List ; java . u t i l . Properties ; n e t . s s e h u b . comani . c o r e . L o g g e r ; n e t . s s e h u b . comani . d a t a . I E x t r a c t i o n Q u e u e ; n e t . s s e h u b . comani . e x t r a c t i o n . A b s t r a c t C o m m i t E x t r a c t o r ; n e t . s s e h u b . comani . e x t r a c t i o n . E x t r a c t i o n S e t u p E x c e p t i o n ; public c l a s s 13 CommitExtractor private s t a t i c f i n a l 14 15 public 16 17 extends String ID = { " MyCommitExtractor " ; CommitExtractor ( P r o p e r t i e s IExtractionQueue AbstractCommitExtractor extractionProperties , commitQueue ) throws E x t r a c t i o n S e t u p E x c e p t i o n { super ( e x t r a c t i o n P r o p e r t i e s , commitQueue ) ; this . l o g g e r . l o g ( ID , " C r e a t e d " , null , L o g g e r . M e s s a g e T y p e . INFO ) ; 18 19 20 21 / / TODO 22 Further setup actions go here } 23 24 @Override public boolean 25 26 / / TODO extract ( File Extraction return f a l s e ; 27 28 of all repository ) commits { from given repository } 29 30 @Override public boolean 31 32 / 33 ∗ ∗ TODO extract ( File Extraction given repository return f a l s e ; 34 35 of all r e p o s i t o r y , L i s t commitList ) commits list of given commit from ∗/ } 36 37 @Override public boolean 38 39 / / TODO extract ( String Extraction return f a l s e ; 40 41 of given commit ) commit { ( convert to data model ) } 42 43 @Override public boolean 44 45 / / TODO Check return f a l s e ; 46 47 operatingSystemSupported ( String if extractor supports given os ) { operating system } 48 49 @Override public boolean 50 51 / 52 ∗ ∗ TODO Check system versionControlSystemSupported ( String if extractor supports given version vcs ) ∗/ return f a l s e ; 53 54 } 55 56 } Listing 4: Blueprint of a ComAnI commit extractor main class 14 { control { <> AbstractCommitAnalyzer < > net.ssehub.comani.analysis #logger: Logger #analysisProperties: Properties #commitQueue +AbstractCommitAnalyzer(Properties,IAnalysisQueue) +analyze():boolean +operatingSystemSupported(String):boolean +versionControlSystemSupported(String):boolean Figure 4: ComAnI AbstractCommitAnalyzer 15 0..1 class IAnalysisQueue net.ssehub.comani.data +isOpen():boolean +getCommit():Commit 1 2 3 4 5 6 7 8 9 10 11 package import core ; java . u t i l . Properties ; import import import import import n e t . s s e h u b . comani . a n a l y s i s . AbstractCommitAnalyzer ; n e t . s s e h u b . comani . a n a l y s i s . A n a l y s i s S e t u p E x c e p t i o n ; n e t . s s e h u b . comani . c o r e . L o g g e r ; n e t . s s e h u b . c o m a n i . d a t a . Commit ; n e t . s s e h u b . comani . d a t a . I A n a l y s i s Q u e u e ; public c l a s s 12 CommitAnalyzer private s t a t i c f i n a l 13 14 public 15 16 extends String ID = CommitAnalyzer ( P r o p e r t i e s IAnalysisQueue AbstractCommitAnalyzer { " MyCommitAnalyzer " ; analysisProperties , commitQueue ) throws A n a l y s i s S e t u p E x c e p t i o n { super ( a n a l y s i s P r o p e r t i e s , commitQueue ) ; this . l o g g e r . l o g ( ID , " C r e a t e d " , null , L o g g e r . M e s s a g e T y p e . INFO ) ; 17 18 19 20 / / TODO 21 Further setup actions go here } 22 23 @Override public boolean a n a l y z e ( ) { while ( this . commitQueue . i s O p e n ( ) ) { Commit commit = this . commitQueue . getCommit ( ) ; i f ( commit != null ) { 24 25 26 27 28 / / TODO 29 Analyze commit } 30 } return f a l s e ; 31 32 } 33 34 @Override public boolean 35 36 / / TODO Check return f a l s e ; 37 38 operatingSystemSupported ( String if analyzer supports given os ) { operating system } 39 40 @Override public boolean 41 42 / 43 ∗ ∗ TODO Check system versionControlSystemSupported ( String if analyzer supports given version vcs ) ∗/ return f a l s e ; 44 45 } 46 47 } Listing 5: Blueprint of a ComAnI commit analyzer main class 16 { control References [1] Apache Software Foundation. org/, Apache subversion. https://subversion.apache. 2018. Accessed 2018/10/11. [2] Git. Git version control system. https://git-scm.com/, 2018. Accessed 2018/10/11. [3] C. Kröher, S. El-Sharkawy, and K. Schmid. KernelHaven - an experimentation workbench for analyzing software product lines. In 40th International Conference on Soft- ware Engineering: Companion Proceedings, pages 7376, New York, NY, USA, 2018. ACM. [4] C. Kröher, S. El-Sharkawy, and K. Schmid. KernelHaven - an open infrastructure for product line analysis. In 22nd International Systems and Software Product Line Conference, volume 2, pages 510, New York, NY, USA, 2018. ACM. [5] C. Kröher, L. Gerling, and K. Schmid. Identifying the intensity of variability changes in software product line evolution. In 22nd International Systems and Software Product Line Conference, volume 1, pages 5464, New York, NY, USA, 2018. ACM. [6] C. Kröher and K. Schmid. A commit-based analysis of software product line evolution: Two case studies. Technical Report SSE 2/17/E, University of Hildesheim, 2017. [7] C. Kröher and K. Schmid. Towards a better understanding of software product line evolution. In Softwaretechnik-Trends, volume 37:2, pages 4041, Berlin, Germany, 2017. Gesellschaft für Informatik e.V., Fachgruppe PARS. [8] Linux Kernel Organization, Inc. The Linux kernel archives. org/, https://www.kernel. 2018. Accessed 2018/10/15. [9] Stiftung Unviversity of Hildesheim - Software Systems Engineering. https://github.com/KernelHaven, KernelHaven. 2018. Accessed 2018/10/12. [10] Stiftung Unviversity of Hildesheim - Software Systems Engineering. Variability-centric commit extraction and analysis. https://github.com/SSE-LinuxAnalysis/ComAn, 2018. Accessed 2018/10/15. [11] L. Torvalds. Linux kernel source tree. https://github.com/torvalds/linux, Accessed 2018/10/15. 17 2018.
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Page Count : 17 Page Mode : UseOutlines Author : Title : Subject : Creator : LaTeX with hyperref package Producer : pdfTeX-1.40.17 Create Date : 2018:11:17 11:29:44+01:00 Modify Date : 2018:11:17 11:29:44+01:00 Trapped : False PTEX Fullbanner : This is MiKTeX-pdfTeX 2.9.6100 (1.40.17)EXIF Metadata provided by EXIF.tools