How to Use IDE Projects Under Version Control

by Igor Nikiforov and Alexander Simon

How application developers can use the Oracle Solaris Studio IDE with version-controlled code.

Published July 2012

Storing Oracle Solaris Studio IDE projects under a version control system (VCS) can be tricky when developers are working on the project from several different platforms and with different tool collections.

This article provides tips for working on IDE projects that are stored under version control. It covers situations where all developers are using the same environment and situations where developers are using different combinations of platforms and tools. It is designed for you to follow along and perform the steps.

This article shows you how to place under version control a simple managed project, a term used to indicate a project that was originally created and managed by the IDE. You start using this project in the simple case where all developers are using the same platform and tools, and then evolve the project to support development on multiple platforms with multiple tool collections.

The article also discusses working with an unmanaged project under version control with the IDE. The differences between the types of projects and why the differences matter are discussed in the following section, "About Managed and Unmanaged IDE Projects."

Mercurial is used as the example VCS in this article. If you are using another VCS, such as Subversion or CVS, see the documentation for that system to find the corresponding commands to do similar tasks.

About Managed and Unmanaged IDE Projects

A managed project is an IDE project that is created and managed in the IDE. You specify project settings when creating the project and later you can change them in the Project Properties dialog box. The IDE generates a Makefile in which the project settings are stored and stores the Makefile separate from the source files in a special project directory. The IDE controls all aspects of how a managed project is built, run, and debugged. The Makefile is dynamic and changed by the IDE in response to changes in the project properties and source files. You never directly edit the Makefile for a managed project.

An unmanaged project is an IDE project whose source files exist independent of the IDE and are imported into the IDE through New Project templates called Project with Existing Sources or Project from Binary File. The IDE relies on an existing Makefile for instructions on how to compile and run the application. The settings you specify in the New Project wizard as well as in the Project Properties dialog box tell the IDE how the Makefile manages the builds of the source code.

It is important to know whether a project is managed or unmanaged when working with a VCS because some IDE-managed files should not be version controlled and should remain only in your copy of the project. Such files must be excluded from the VCS monitoring of changes because they contain some information that is specific to the user or system. The exact set of the files that must be excluded can vary depending on the development environment, and this is discussed later in this article.

Setting Up an IDE Project in a Repository

This article uses Mercurial as the VCS because is it a free source control management tool that can run on multiple platforms and is widely used. If you use another VCS, you should be able to apply the concepts described here to your VCS.

If you already have Mercurial and its hg command on your system, you can continue to the "Create a Test Repository" section.

If you do not already have Mercurial on your system, you can download it from http://mercurial.selenic.com and use the installation instructions from that site.

On Oracle Solaris 11, you can also install the developer/versioning/mercurial package from the pkg.oracle.com/solaris repository.

Create a Test Repository

In this task, you initialize a repository and seed it with source files from a sample project.

1. Use the following command to create a test repository:
   
   

   % hg init /tmp/test-repo
   

   
   

   The repository is created silently without any output from the hg init command. If you list the files in /tmp/test-repo, you should see that it contains a .hg directory.

2. In the IDE, create the Welcome sample project and place it in the repository:
   
   
   1. Choose File -> New Project to start the New Project wizard.
   2. Expand the Samples folder and select C/C++/Fortran -> Welcome.
      
      
      

      Figure 1. Selecting the Welcome Sample Project

   3. Click Next.
   4. Delete the _1 from the project name and type /tmp/test_repo in the Project Location field.
      
      
      

      Figure 2. Sample Project Name and Location Fields

   5. Click Finish.

Wait a moment while the IDE parses and builds the project.

Continue on to see how to work with this project under version control, under several scenarios of operating systems and tools that might be used by a development team.

How to Work with Managed IDE Projects Under Version Control

This section shows tips for working with IDE projects for sources under version control.

• Project Developed on One Platform with One Tool Collection
• Project Developed on One Platform with Multiple Versions of a Tool Collection
• Project Developed on Multiple Platforms with the Same Tool Collection
• Project Developed on Multiple Platforms with Multiple Tool Collections

Project Developed on One Platform with One Tool Collection

Suppose that the project's developers are all working on the same platform and using the same tool set. For example, they might be running the IDE on Oracle Solaris x86 and using the Oracle Solaris Studio 12.3 tools collection for their compilers and debugger.

The following must be done to ensure that developers can work with the version-controlled IDE project without conflicts:

• The name for the tool collection must be exactly the same in each IDE that is used for project development. This can be done simply by using the default tool collection.
• All required libraries must be installed on all systems used for development.
• The following project files and directories must be ignored in the repository so that changes to them are not tracked by the VCS:
  
  

  Welcome/nbproject/private
  Welcome/.dep.inc
  Welcome/build
  Welcome/dist
  

  
  

  All other files should be version controlled.

For Mercurial, you should perform the following steps to add the files to the ignore list:

1. In a terminal window, go to the top-level directory of the repository.
   
   

   % cd /tmp/test-repo
   

2. Create a file named .hgignore with the following content:
   
   

   /build$ 
   /dist$ 
   /nbproject/private$
   /.dep.inc$
   

3. Add the .hgignore file to the repository:
   
   

   % hg add .hgignore
   

4. Commit your change to the repository:
   
   

   % hg commit -m"Ignore list created"
   

5. Build the project in the IDE by clicking the Build button.
   
   

   Tip: If you open the Source Files folder in the project, you will see the welcome.cc file is shown in green to indicate it is a new file that has not yet been added to the repository.

6. In a terminal window, add all the project files to the repository:
   
   

   % hg add
   adding Welcome/.make.state.Debug
   adding Welcome/Makefile
   adding Welcome/nbproject/Makefile-Debug.mk
   adding Welcome/nbproject/Makefile-Release.mk
   adding Welcome/nbproject/Makefile-impl.mk
   adding Welcome/nbproject/Makefile-variables.mk
   adding Welcome/nbproject/Package-Debug.bash
   adding Welcome/nbproject/Package-Release.bash
   adding Welcome/nbproject/configurations.xml
   adding Welcome/nbproject/project.xml
   adding Welcome/welcome.cc
   adding Welcome/welcome.h
   

   
   

   Notice that the ignored files are not added to the repository.

7. Commit the files to the repository:
   
   

   % hg commit -m"Initial commit"
   

8. Close the project in the IDE.
9. Clone the repository on developer systems.
   
   

   In this article, for simplicity, you can create the clone on the same system with a command such as the following:

   % hg clone /tmp/test-repo /export1/sside/my-repo
   

10. In the IDE, open the project located in the cloned repository.
    
    

    For example, open /export1/sside/my-repo/Welcome.

11. Open the file welcome.cc in the Source Files folder and change the text on line 35 from "Welcome..." to "Welcome to Studio IDE."

12. Save your changes and notice that the welcome.cc file is now shown in blue in the Projects window because it is a modified file under version control.
    
    
    

    Figure 3. Modified File Under Version Control in IDE

13. Build and run the project and you should see the new output.
    
    
    

    Figure 4. New Build Output After the Program Was Edited

14. Now use the usual hg commands to pull changes from the master repository and update your repository with the changes, and then commit your changes.
    
    

    For example, you might do the following:

    % hg pull -u
    pulling from /tmp/test-repo
    searching for changes
    no changes found
    % hg commit -m"Changed greeting"
    % hg out
    comparing with /tmp/test-repo
    searching for changes
    changeset:   2:17166e49c21d
    tag:         tip
    user:        yourname
    date:        Mon Apr 02 18:05:18 2012 -0400
    summary:     Changed greeting
    % hg push
    pushing to /tmp/test-repo
    searching for changes
    adding changesets
    adding manifests
    adding file changes
    added 1 changesets with 2 changes to 2 files
    

Tip: You can work with several version control systems, including Mercurial, Subversion, and CVS inside the IDE. You can access commands for them in the Team menu and by right-clicking projects and files in the Projects window. See the Help menu in the IDE for more information.

Project Developed on One Platform with Multiple Versions of a Tool Collection

Suppose that multiple versions of a tool collection are used by developers on the same platform. For example, suppose the developers' systems are all running Oracle Solaris x86, but some developers are using Oracle Solaris Studio 12.3 and others are using Oracle Solaris Studio 12.2. Or they might be using different versions of GNU compilers.

You can add the project to the VCS the same way you did previously in the "Project Developed on One Platform with One Tool Collection" section.

However, all developers should use the same name of the tool collection in the IDE and set it as the default tool collection. The IDE provides several aliases for the tool collection that comes with the particular version of Oracle Solaris Studio. Generic names OracleSolarisStudio and SunStudio are used in each release of Oracle Solaris Studio to refer to the current version of the tools. For example, Oracle Solaris Studio 12.3 has tool collections named OracleSolarisStudio_12.3, OracleSolarisStudio, and SunStudio, which all represent the tools in /opt/solarisstudio12.3/bin. In the 12.2 release, the OracleSolarisStudio and SunStudio tool collection names exist, but they represent the tools in /opt/solstudio12.2/bin.

If all developers select the same name, such as OracleSolarisStudio, the project can work smoothly under version control because the tool collection names are the same even though the tools are different versions. If some developers are using an older release when the product was named Sun Studio, all developers should select the SunStudio tool collection name. The chosen tool collection name should be set as the default by all developers on the project.

Note: While it is possible to use Oracle Solaris Studio compilers and GNU compilers on the same project, you would have to restrict the use of compiler options. Only the compiler options with equivalent names and meaning could be used. See the article "Translating gcc/g++/gfortran Options to Oracle Solaris Studio Compiler Options" for more information about such options.

To set the default tool collection, do the following:

1. Choose Windows -> Services from the IDE menu to open the Services window.
2. In the Services window, expand the C/C++ Build Hosts node.
3. Expand the localhost and Tool Collections nodes.
4. Right-click the tool collection you want to use and select Set as Default from the context menu.

An alternate approach is to agree upon a tool collection name and have each developer create a new copy of the tool collection with the agreed-upon name. Then each developer can use the new tool collection name to build the version-controlled project.

To create a new name for the tool collection in the IDE, do the following:

1. Choose Windows -> Services from the IDE menu to open the Services window.
2. In the Services window, expand the C/C++ Build Hosts node.
3. Expand the localhost node.
4. Right-click the Tool Collection node and select Properties from the context menu.
   
   

   The Tool Collection Manager window opens.

5. Select the tool collection that you want to copy, and click the Duplicate button.
6. In the Duplicate Tool Collection dialog box, type the new name in the Tool Collection Name field at the bottom of the dialog box and click OK.
7. Click the Default button in the Tool Collection Manager dialog box to make this collection become the default, and click OK.

Each developer should use the default tool collection to build the version-controlled project.

Project Developed on Multiple Platforms with the Same Tool Collection

Suppose you need the Welcome project to work on both Oracle Solaris and Linux. Some developers are using Linux with the Oracle Solaris Studio tool collection and other developers are using Oracle Solaris with the same version of the tool collection.

You should add the project to the VCS the same way you did previously and create a .hgignore file as described in the "Project Developed on One Platform with One Tool Collection" section. In addition, you should add /nbproject/Makefile-*.mk and /nbproject/Package-*.mk to the .hgignore file so that the file now looks as follows:

/build$ 
/dist$ 
/nbproject/private$
/nbproject/Makefile-*.mk
/nbproject/Package-*.mk
/.dep.inc$

When the /nbproject/Makefile-*.mk and /nbproject/Package-*.mk files are ignored, you can work with this shared project on both Linux and Oracle Solaris without any additional changes.

However, this approach has one side effect: If you clone the repository and try to build the project from the command line, the build will fail because the /nbproject/Makefile-*.mk files are missing. To fix the build failure, you should build the project from the IDE first to generate the /nbproject/Makefile-*.mk files appropriate for your environment. Then you can build the project from the command line.

If you have a build system that takes sources from the repository and builds the project automatically, you must use the IDE to build the project once on the build system. This generates the Makefile-*.mk files that are suitable for the build system.

Project Developed on Multiple Platforms with Multiple Tool Collections

The most complex case occurs when some developers are using Oracle Solaris with the Oracle Solaris Studio tool collection and other developers are using Linux with the GNU tool collection.

The tips discussed in the "Project Developed on Multiple Platforms with the Same Tool Collection" section also apply for this scenario:

1. Add the project to the VCS.
2. Add /nbproject/Makefile-*.mk and /nbproject/Package-*.mk to the .hgignore file.
3. Build the project in the IDE once before trying to build from the command line, including when build scripts are used on a build system.

In addition, to deal with developing projects under VCS with multiple platforms and multiple tool collections, you should create a project configuration for each platform. Developers can select the configuration that is suitable for their environments, and they will not be restricted to using only compiler flags that are the same for GNU compilers and Oracle Solaris Studio compilers.

A configuration is a collection of settings used for the project. You can easily switch many settings at once when you select a configuration. When the IDE creates a managed project, it creates a Debug configuration and a Release configuration, by default. The Debug configuration builds a version of your application that includes debug information. The Release configuration builds an optimized version.

Project configurations can also be used to quickly set the options for a particular platform and tool collection. If you add a configuration to the Welcome project for each of the development environments in use by your development team, each developer can select the appropriate configuration for their environment.

A configuration should be created in the IDE while it is running in the development environment for which you are creating the configuration. In other words, you should run the IDE on a Linux system where the GNU compilers are available to create the configuration for developing on Linux, and run the IDE on an Oracle Solaris system where the Oracle Solaris Studio compilers are available to create the configuration for developing on Oracle Solaris.

To create new configuration, do the following:

1. Open the project in the IDE running on the development environment.
2. Right-click the project in the Project window and select Project Properties.
3. Click the Manage Configurations button to open the Configurations dialog box.
4. Click New to create a completely new configuration or click Duplicate to copy an existing configuration.
   
   

   If you are creating a duplicate, the new configuration is created with a name such as Copy_of_Debug.

5. Rename the configuration by double-clicking it in the list or by selecting it and clicking Rename, and give it a name to indicate the platform and tools it will use.
   
   

   For example, you might use "Linux and GNU" for the configuration name if you are on a Linux system.

6. Click OK to dismiss the Configurations dialog box and return to the Project Properties dialog box.
7. Set the properties of the configuration by selecting the new configuration at the top of the Project Properties dialog box and then modifying properties.
   
   

   For example, select the Linux and GNU configuration, and then you can set the appropriate tool collection by selecting the Build category and selecting GNU from the Tool Collection list. You can make changes to any other properties appropriate for the platform, and then click OK.

8. Save the project and push the changes to the master repository.
9. Pull the changes to a local repository that you can access from a system running another development environment for which you want to create a configuration.
10. Follow Steps 1 through 8 to create a new configuration for the other development environments on your team.
    
    

    For example, if you want to create a configuration for developing on Oracle Solaris x86 with Oracle Solaris Studio tools, in Step 1 you would start the IDE on Oracle Solaris x86.

After you create all the configurations for the project and push the changes to the master repository, you can update your developer repositories. Then you can select a configuration from the Configurations list in the IDE toolbar, or right-click the project and select Set Configuration, or select a configuration in the Project Properties dialog box.

How to Work with Unmanaged IDE Projects Under Version Control

An unmanaged project is an IDE project that was created as a Project from Existing Sources or as a Project from Binary. See the "About Managed and Unmanaged IDE Projects" section for more information about the differences between managed and unmanaged projects.

Most likely, the source files for an existing project are already maintained in a VCS. If you want to create an IDE project to work on sources that are already version controlled, you should do the following:

1. Add the IDE project directory to the repository near the sources root directory.
2. Add the projectname/nbproject/private directory to the ignore list.
3. Add projectname/nbproject/Package-*.bash to the ignore list.

A potential problem with version-controlled unmanaged projects exists if the project's Makefile uses macros that have values that change frequently, such as a date or time string, and macros that depend on system or user information. Such macros cause the IDE project's configuration.xml file to be updated each time the project is built from the IDE on any system. This will result in merges on each push to the repository. You can disable the updating of configuration.xml by disabling the Smart Build Analyzer.

To disable the Smart Build Analyzer, do the following:

1. From the IDE menu bar, choose Tools -> Options and then click the C/C++ button.
2. Select the Project Options tab.
3. Deselect the checkbox for Use Smart Build Analyzer to Configure Code Assistance.

Note: If you are going to create a new project from existing sources, be sure to first re-enable this feature by selecting the checkbox for Use Smart Build Analyzer to Configure Code Assistance. You should disable it again once the project has been parsed when you are working with an unmanaged project in the VCS.

See Also

See the following resources for more information:

• The Help menu in the IDE, which provides access to extensive information about using the IDE
• The IDE Quick Start Tutorial, which provides basic information about using the IDE, in the Oracle Solaris Studio documentation library at http://docs.oracle.com/cd/E24457_01/
• "Performance Tips for the Oracle Solaris Studio IDE" and "how to" articles for the IDE in the Topics page of the Oracle Solaris Studio portal

About the Authors

Igor Nikiforov has been working for Oracle and Sun Microsystems for more than four years. His current responsibilities include development of the Oracle Solaris Studio IDE and NetBeans. Before Oracle, Igor developed enterprise applications including some municipal IT projects for the city of Saint Petersburg, Russia.

Alexander Simon has been working in IT for over 25 years. Before joining Sun in 2006, he worked for Togethersoft and Borland, participating in the development of enterprise-level systems and modern IDEs. Alexander is currently a Principal Software Engineer for Oracle in St. Petersburg, Russia developing the Oracle Solaris Studio IDE. His responsibilities include developing IDE modules for the tool collection, project creation, and the editor.

See sysadmin-related content for all Oracle technologies by following OTN Systems on Facebook and Twitter.