How to become a CIVL developer

• If you are interested in contributing to the development of CIVL, send an email to civl-users@… expressing your interest, and we'll get back to you. We can use help in many areas, including testing and creating new examples, and we are very open to new ideas on all aspects of the project.
• The lead developer will perform the following tasks:
  • Add you to the civl-dev@… email list. You will be able to read and post messages to this group. Use it to discuss any development issues.
  • Create a Subversion account for you in the appropriate projects (CIVL, ABC, SARL, GMC). You will then be able to commit to the branches directories in those repositories. (All of the repositories are already world-readable.)
  • Create a Trac account for you. You will then be able to create and modify bug/issue tickets, and write to the Wiki. (The tickets and Wiki are already world-readable.)

How to make changes or additions to CIVL

1. To make any changes or additions to CIVL, you must first become a CIVL developer. See above.
2. Before embarking on any major changes or additions, talk to the other developers. This is best done using the email list civl-dev@…. Explain what you want to do, and listen to the feedback.
3. Create a new branch for the new features you want to add into CIVL. Name your branch anything you like and create it in the branches directory of the repository.
4. Proceed with development of your branch, committing as often as you like. Periodically, merge changes from the trunk into your branch, and resolve any conflicts that result. This will make it much easier to integrate your branch into the trunk later on. Be sure to follow the CIVL Coding Standards and the Coding Standards for CIVL models.
5. Create unit tests and system tests for your new code, making sure they provide 100% statement coverage of your code, at a minimum. You may also need to make changes to existing tests.
6. Have at least one other CIVL developer review your code. Your reviewer will make suggestions for improvements. Iterate until both of you are satisfied.
7. When you feel your branch is complete, send an email to civl-dev@…. In the email, give the name of your branch and summarize the changes/additions you have made. We will then schedule a CIVL meeting where your contribution will be discussed. All developers will be given some time to review your branch before the meeting.
8. At the meeting, your branch will either be accepted or it will be rejected with suggestions for further changes. If accepted, it will be merged into the trunk. Only the lead developers have permission to do this merge. If further changes are suggested, a future meeting will be scheduled to discuss again.

We recommend using the Eclipse IDE to write CIVL code. Remember to set your Java code formatter as "built-in 2.1" in your Eclipse.

Set up CIVL in Eclipse

1. Install theorem provers ​cvc3, ​cvc4 and ​z3. Install Eclipse IDE for Java/EE developers if you have not already done so.
2. Install an SVN plugin in Eclipse (such as Subversive) if you have not already.
3. Install prerequisite projects ABC, SARL and GMC. Make sure that the three projects are put in the workspace directory where CIVL will be created. Specifically:
   
   
   • Install the symbolic algebra and reasoning library SARL. In Eclipse, select New Project...from SVN, use the archive ​svn://vsl.cis.udel.edu/sarl. After entering that, open it up and select the "trunk". After checking out trunk, name the project "SARL". Then follow the instructions in the INSTALL file for Eclipse installation. Build the sarl.jar from within Eclipse by right-clicking (or ctrl-clicking) on the build.xml file and selecting Run As->Ant Build.
     
   
   
   • Install the C front-end ABC. In Eclipse, select New Project...from SVN, use the archive ​svn://vsl.cis.udel.edu/abc. After entering that, open it up and select the "trunk". After checking out trunk, name the project "ABC". Then follow the instructions in the INSTALL file for Eclipse installation. Build the abc.jar from within Eclipse by right-clicking (or ctrl-clicking on OS X) on the build.xml file and selecting Run As->Ant Build.
     
     
   • Install the generic model checking utilities package GMC. In Eclipse, select New Project...from SVN, use the archive ​svn://vsl.cis.udel.edu/gmc. After entering that, open it up and select the "trunk". After checking out !trunk, name the project "GMC". Build the gmc.jar from within Eclipse by right-clicking (or ctrl-clicking) on the build.xml file and selecting Run As->Ant Build.
     
     
4. From within Eclipse, select New Project...from SVN. The archive is ​svn://vsl.cis.udel.edu/civl. After entering that, open it up and select the "trunk". (It is simplest to just check out the trunk for the Eclipse project.)
5. Check out the trunk, and create the project using the New Java Project Wizard as usual, naming it "CIVL". The .project, .classpath, and other Eclipse meta-data are already in the SVN archive, saving you a bunch of work.
6. If default_build.properties matches the configuration of your system, then you can skip this step. Otherwise, you may need to create a file build.properties in the directory containing build.xml. Copy and paste the content from any file under properties, edit each entry with the path configured in your system. The newly created file build.properties will automatically be used by ant to to build the .jar file.
7. Navigate to Preferences -> Java -> Build Path -> ClassPath Variables, and then select New to create a classpath variable VSL, and specify its value to be /opt/vsl.
8. Do a clean build. Everything should compile. Generate the civl.jar by right-clicking (or ctrl-click on OS X) the build.xml file and Run As->Ant Build.
9. Somewhere on your system, create a plain text file containing exactly the following two lines:

   #!/bin/sh
   java -jar /Path/To/Your/workspace/CIVL/civl.jar $@
   

where "/Path/To/Your/workspace" is replaced with the path to your Eclipse workspace directory. Name this file "civl", put it in your PATH, and make it executable (chmod ugo+x civl). Alternatively, you can define an alias in your .profile, .bash_profile, .bashrc, or equivalent:

alias civl='java -jar /Path/To/Your/workspace/CIVL/civl.jar'

1. From a terminal window, execute "civl config". This should find the theorem provers in your PATH and create a file .sarl in your home directory.

Using Subversion in command-line

• CIVL uses Subversion to manage source code. The CIVL Subversion repository is structured in the typical way. In particular, the repository contains directories named trunk, branches and tags.
• To create a new branch named branch_name from the current trunk, type

  svn copy svn://vsl.cis.udel.edu/civl/trunk svn://vsl.cis.udel.edu/civl/branches/branch_name
  

• Once a new branch has been created, you can check out your new branch with the command

  svn co svn://vsl.cis.udel.edu/civl/branches/branch_name
  

You can also create a new Eclipse project from that branch, in the usual way.

• Within your own branch, you can change anything you want to implement your changes or additions, and you can commit your changes to the svn server so that you won't lose your work.
• To merge changes made to the trunk into your branch, change into your local branch directory and type

  svn merge svn://vsl.cis.udel.edu/civl/trunk  .
  

Do this regularly (or whenever changes are committed to the trunk) in order to reduce the work of resolving conflicts when you decide to merge your branch back to the trunk.

• Lead developers only: to merge a branch back to the trunk, change into the local branch directory and type

  svn merge . svn://vsl.cis.udel.edu/civl/trunk
  

Resolve conflicts as needed and make sure all tests pass.

• Checkout the merge history from trunk to your branch, go to your branch:

  svn mergeinfo ^/trunk