by Igor Nikiforov and Alexander Simon, July 2012 (updated by Alexander Simon, June 2016)
Storing Oracle Developer 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 Git, see the documentation for that system to find the corresponding commands to do similar tasks.
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.
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
In this task, you initialize a repository and seed it with source files from a sample project.
% 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
Figure 1. Selecting the Welcome Sample Project
_1from the project name and type
/tmp/test_repoin the Project Location field.
Figure 2. Sample Project Name and Location Fields
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.
This section shows tips for working with IDE projects for sources under version control.
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 for x86 and using the Oracle Developer Studio 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:
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:
% cd /tmp/test-repo
.hgignorewith the following content:
/build$ /dist$ /nbproject/private$ /.dep.inc$
.hgignorefile to the repository:
% hg add .hgignore
% hg commit -m"Ignore list created"
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.
% 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.
% hg commit -m"Initial commit"
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
For example, open
Open the file
welcome.cc in the Source Files folder and change the text on line 35 from "
Welcome..." to "
Welcome to Studio IDE."
welcome.ccfile 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
Figure 4. New Build Output After the Program Was Edited
hgcommands 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 Git 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.
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 for x86, but some developers are using Oracle Solaris Studio 12.4 and others are using Oracle Developer Studio 12.5. 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 Developer Studio or 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.4 has tool collections named OracleSolarisStudio_12.4, OracleSolarisStudio, and SunStudio, which all represent the tools in
/opt/solarisstudio12.4/bin. Generic name OracleDeveloperStudio is used in each release of Oracle Developer Studio to refer to the current version of the tools.
If all developers select the same name, such as OracleDeveloperStudio, 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 Oracle Solaris Studio or Sun Studio, all developers should select the OracleSolarisStudio or 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 Developer 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 Oracle Developer Studio 12.5: GCC Compatibility Guide for more information.
To set the default tool collection, do the following:
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:
The Tool Collection Manager window opens.
Each developer should use the default tool collection to build the version-controlled project.
Suppose you need the Welcome project to work on both Oracle Solaris and Linux. Some developers are using Linux with the Oracle Developer 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/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$
/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.
The most complex case occurs when some developers are using Oracle Solaris with the Oracle Developer 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:
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 Developer 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 Developer Studio compilers are available to create the configuration for developing on Oracle Solaris.
To create new configuration, do the following:
If you are creating a duplicate, the new configuration is created with a name such as Copy_of_Debug.
For example, you might use "Linux and GNU" for the configuration name if you are on a Linux system.
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. Set property Platform Specific Configuration to separate the Linux and Oracle Solaris configurations. You can make changes to any other properties appropriate for the platform, and then click OK.
For example, if you want to create a configuration for developing on Oracle Solaris for x86 with Oracle Developer Studio tools, in Step 1 you would start the IDE on Oracle Solaris for 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.
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:
projectname/nbproject/privatedirectory to the ignore list.
projectname/nbproject/Package-*.bashto 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 Build Analyzer.
To disable the Build Analyzer, do the following:
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 Build Analyzer. You should disable it again once the project has been parsed when you are working with an unmanaged project in the VCS.
See the following resources for more information:
Igor Nikiforov has been working for Oracle and Sun Microsystems for more than eight years. His current responsibilities include development of the Oracle Developer 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 29 years. Before joining Sun (now Oracle) in 2006, he worked for Togethersoft and Borland, participating in the development of enterprise-level systems and modern IDEs. Simon is currently a principal software engineer for Oracle in St. Petersburg, Russia developing the Oracle Developer Studio IDE. His responsibilities include developing IDE modules for the tool collection, project creation, and the editor.
|Revision 1.2, June 2016|
|Revision 1.1, August 2012|