Sun Studio 12 Update 1 IDE Quick Start Tutorial

The following short tutorial takes you through some of the basic steps of developing a C, C++, or Fortran application using Sun Studio 12 Update 1 IDE.

Contents

• Creating Projects
• Creating an Application Project
• Switching Between the Logical View and the Physical View of the Project
• Adding Files and Folders to Your Project
• Adding New Files to Your Project
• Adding More New Files to Your Project
• Adding Existing Files to Your Project
• Setting Project Properties
• Managing Configurations
• Setting Source File Properties
• Setting the Main Project
• Building Your Project
• Compiling a Single File
• Running a Project
• Creating a Project From Existing Code
• Creating a Project From Existing Code
• Building and Rebuilding Your Project
• Doing Remote Development
• Packaging an Application
• Editing Source Files
• Setting the Formatting Style
• Folding Blocks of Code in Source Files
• Using Semantic Highlighting
• Using Code Completion
• Navigating Source Files
  • Using the Classes Window
  • Using the Navigator Window
  • Finding Class, Method, and Field Usages
  • Using the Call Graph
  • Using Hyperlinks
  • Using the Include Hierarchy
  • Using the Type Hierarchy
• Collecting a Runtime Checking Experiment
• Creating Breakpoints
• Creating and Removing a Line Breakpoint
• Creating a Function Breakpoint
• Debugging a Project
• Starting a Debugging Session
• Inspecting the State of the Application
• Debugging at the Machine-Instruction Level
• Debugging an Executable
• Debugging a Running Program by Attaching to It
• Debugging a Core File
  

Sun Studio lets you create C, C++, and Fortran Application and Library projects with generated makefiles, as well as projects that have existing makefiles.

With a C/C++/Fortran Application, Dynamic Library, or Static Library project, the IDE controls all aspects of how your application is built, run, and debugged. You specify project settings when creating the project and in the Project Properties dialog box. The IDE generates a makefile in which all of your settings are stored.

Creating an Application Project

1. Open the New Project wizard by choosing File > New Project.


2. In the wizard, select the C/C++/Fortran Development category.


3. The wizard gives you a choice of four types of new projects: C/C++/Fortran Project From Existing Code, C/C++/Fortran Application, C/C++/Fortran Dynamic Library, and C/C++/Fortran Static Library. Select C/C++/Fortran Application and click Next.




4. Create a new C/C++/Fortran Application project from the wizard using the defaults. You can choose the name of the project and the location of the project.


5. Click Finish to exit the wizard.

A project is created with four logical folders. A logical folder is not a directory. It is a way for you to organize your files and does not reflect where the files are physically stored on disk. Files added to logical folders are automatically part of the project and are compiled when you build the project.

Files added to the Important Files folder are not part of the project and are not compiled when you build the project. These files are just for reference and are convenient when you have a project with an existing makefile.

Switching Between the Logical View and the Physical View of the Project

A project has both a logical and a physical view. You can switch between the logical view and the physical view of your project.

1. Select the Files tab. This tab shows the physical view of your project. It displays files and folders as they are stored on disk.




2. Select the Projects tab. This tab shows the logical view of your project.

Adding Files and Folders to Your Project

You can add logical folders to your project.

1. Right-click the project node of your Application_1 project and choose New Logical Folder. A new logical folder is added to the project.


2. Right-click the new logical folder and select Rename. Type the name you would like to give the new folder.

You can add both files and folders to an existing folder. Logical folders can be nested.

Adding New Files to Your Project

You can add new files to your project.

1. Right-click the Source Files folder and choose New > Main C File.


2. On the Name and Location page, type main in the File Name field.




3. Click Finish.

The main.c file is created on disk in the directory specified in the wizard and added to the Source Files folder. You can add any kind of file to this folder, not only source files.

Adding More New Files to Your Project

1. Right-click the Header Files folder and choose New > C Header File.


2. On the Name and Location page, type file in the File Name field.


3. Click Finish.

The file.h file is created on disk in the directory specified in the wizard and added to the Header Files folder.

Adding Existing Files to Your Project

You can add existing files to your project.

• Right-click the Source Files folder and choose Add Existing Item. You can point to an existing file on disk using the Select Item dialog box and add the file to the project.

Do not use New to add existing items. The Name and Location panel will tell you the file already exists.

Setting Project Properties

When the project is created, it has two configurations, Debug and Release. A configuration is the project's way of storing the current settings. The Debug configuration builds a version of your application that includes debug information. The Release configuration builds an optimized version.

The Project Properties dialog box contains build and configuration information for your project. To open the Project Properties dialog box:

• Right-click the project node of the Application project and choose Properties.

You can modify the compiler settings and other configuration settings in the Project Properties dialog box by selecting a node in the left panel and modifying the properties in the right panel. Select some of the nodes and property values and notice the properties you can set. You are setting properties in the currently selected configuration.

Managing Configurations

Properties changed in the Project Properties dialog box are stored in the makefile for the current configuration. You can edit the default configurations or create new ones. To create a new configuration:

1. Click the Manage Configurations button in the Project Properties dialog box.


2. In the Configurations dialog box, select the configuration which most closely matches your desired configuration. In this case, select the Release configuration and click the Copy button. Then click Rename.


3. In the Rename dialog box, rename the configuration to PerformanceRelease. Click OK.


4. Click OK in the Configurations dialog box.


5. In the Project Properties dialog box, expand the Build node and select the C Compiler node.


6. In the property sheet in the right panel, change the Development Mode from Release to PerformanceRelease. Click OK.

You have created a new configuration that will compile the application with a different set of options.

Setting Source File Properties

When you set the project properties for your project, the relevant properties apply to all files in the project. You can set some properties for a specific file.

1. Right-click the main.c source file and choose Properties. You can override the project compiler settings and other properties on a per file basis. You can also exclude files from a build in a specific configuration.


2. Cancel the Project Properties dialog box.

Setting the Main Project

When you right-click a project node in the Projects tab, you get a pop-up menu of actions you can perform on the selected project. If you have multiple projects open at the same time, the pop-up menu for a project node implies you are operating on that project.

Most of the project-related actions on the menu bar and toolbar operate on the main project. The main project node is displayed in bold text in the Projects tab.

To change the main project in the IDE:

• Right-click the desired project node and choose Set as Main Project. This project is now the main project in the IDE and actions in the menu bar and toolbar refer to this project.

Building Your Project

To build your project:

1. Right-click the project and choose Build. The project builds. The build output is shown in the Output window.


2. Switch the configuration from Debug to PerformanceRelease in the configuration drop-down list in the main toolbar. Now the project will be built using the PerformanceRelease configuration.


3. Right-click the project and choose Build. The project builds. The build output is shown in the Output window.

To build multiple configurations of the project at the same time, choose Run > Batch Build Main Project and select the configurations you want to build in the Batch Build dialog box.

You can build, clean, or both clean and build the project by right-clicking the project and choosing actions from the menu. The project also keeps object files and executables from different configurations separate, so you do not have to worry about mixing files from multiple configurations.

Compiling a Single File

To compile a single source file:

• Right-click on the main.c file and choose Compile File. Only this file is compiled.

Note: Single file compilation is not supported for the project type C/C++/Fortran Project From Existing Code.

The args program prints command-line arguments. Before running the program, we will set some arguments in the current configuration. Then we will run the program.

To create the Args_1 project, set some arguments, and run the project:

1. Choose File > New Project.


2. In the project wizard, expand the Samples category.


3. Select the C/C++/Fortran subcategory, then select the Arguments project. Click Next, then click Finish.


4. Right-click the Arguments_1 project node and choose Build. The project builds.


5. Right-click the Arguments_1 project node and choose Properties.


6. In the Project Properties dialog box, select the Run node.


7. In the Arguments text field, type 1111 2222 3333. Click OK.




8. Choose Run > Run Main Project. The application runs. Your arguments are displayed in an external window.

With a C/C++/Fortran Project From Existing Code, the IDE relies on your existing makefile for instructions on how to compile and run your application.

Creating a Project From Existing Code

1. Download the loki-0.1.7 library from http://sourceforge.net/projects/loki-lib.


2. Uncompress loki-0.1.7 in a directory of your choice
   
   


3. Choose File > New Project.


4. Select the C/C++/Fortran Development category.


5. Select C/C++/Fortran Project From Existing Code and click Next.


6. On the Build Tool page, click the Browse button for the Makefile field. In the Select Makefile dialog box, navigate to the directory where you saved loki-0.1.7. Select the Makefile. Click Select.




7. On the Build Actions page, the Working Directory text field, the Build command text field, and the Clean command text field are filled in automatically. In the Build Result field, type the full path to where the makefile will put the library, libloki.a, built from the source code. Click Next.




8. On the Source File Folders page, the path to the source file folder for the project is automatically listed. You could specify additional folders by clicking Add and using the Source File Folders dialog box.




9. On the Code Assistance Configuration page, click Next.




10. On the Project Name and Location page, type Loki in the Project Name field. Use the defaults for all of the other fields. Click Finish.

The project is created and opened in the Projects tab. You have created a project that is a thin wrapper around existing code.

Building and Rebuilding Your Project

To build the project:

• Right-click the project node of the project and choose Build.

To rebuild the project:

• Right-click the project node of the project and choose Clean and Build.

You can build, run, and debug projects on the local host (the system from which you started the IDE) or on a remote host running a UNIX® operating system.

You can define remote development hosts in the Build Tools tab of the Options window.

1. To add a remote host, click Edit.
2. In the Development Host Manager dialog box, click Add.
3. In the Add New Server dialog box, type the system name of the host, a login name, and a password, and click OK.




4. After the host is added to the Development Hosts list in the Development Hosts Manage dialog box, click OK.

To develop a project on a remote host, the project must be on a shared filesystem that is visible on both the local host and the remote host. Typically such a filesystem is shared using NFS or Samba. You can define the mapping between local and remote paths to project source files when you define the remote host.

When you create a project, the current development host is selected as the development host for the project. You can change the development host for the project on the Build panel of the Project Properties dialog box. You can also specify the development host when you are debugging an executable or a core file.

You can package a completed application as a tar file, zip file, Solaris SVR4 package, RPM, or Debian package.

1. Right-click the Quote_1 project and choose Properties.


2. In the Project Properties dialog box, select the Packaging node.


3. Select the Solaris SVR4 package type from the drop-down list.




4. Change the output path if you want to use a different destination directory or filename for the package.


5. Click the Packaging Files browse button. In the Packaging Files dialog box (for an SVR4 package), modify the package parameters on the Info tab as needed.




6. For all package types, add files to the package using the buttons on the Files tab. For each file, type the path you want it to have in the package in the File or Directory Path in Package column of the Files list, and the location of the file in your project in the Original File or Link column. Click OK when your Files list is complete.




7. Turn off verbose mode if you wish by clicking the checkbox.


8. Click OK.


9. To build your package, right-click the project and choose Build Package.

The Sun Studio IDE provides advanced editing and code assistance features to help you in viewing and modifying your source code. To explore these features, we'll use the Quote project:

1. Choose File > New Project.


2. In the project wizard, expand the Samples category and the C/C++ subcategory, then select the Quote project. Click Next, then click Finish.

Setting the Formatting Style

You can use the Options window to configure default formatting style for your projects.

1. Choose Tools > Options.


2. Click Editor in the top pane of the window.


3. Click the Formatting tab.


4. Select the language for which you want to set formatting style from the language drop-down list.


5. Select the style you want to set from the Style drop-down list.




6. Modify the style properties as desired.

Folding Blocks of Code in C and C++ Files

For some types of files, you can use the code folding feature to collapse blocks of code so that only the first line of the block appears in the Source Editor.

1. In the Quote_1 application project, open the Source Files folder, then double-click the cpu.cc file to open it in the Source Editor.


2. Click the collapse icon (small box with minus sign) in the left margin to fold the code of one of the methods.


3. Mouse over the {...} symbol to the right of the folded block to display the code in the block.

Using Semantic Highlighting

You can set an option so that when you click on a class, function, variable, or macro, all occurrences of that class, function, variable, or macro in the current file are highlighted.

1. Choose Tools > Options.


2. Click C/C++ in the top pane of the window.


3. Click the Highlighting tab.


4. Make sure that all of the check boxes contain checkmarks.


5. Click OK.


6. In the customer.cc file of the Quote_1 project, notice that the function names are highlighted in bold.


7. Click on an occurrence of the Customer class.


8. All of the occurrences of the Customer class in the file are highlighted with a yellow background.




9. In the customer.h file, notice that class fields are highlighted in bold.

Using Code Completion

The IDE has a dynamic C and C++ code completion feature that enables you to type one or more characters and then see a list of possible classes, methods, variables, and so on that can be used to complete the expression.

1. Open the quote.cc file in the Quote_1 project, and right-click in the left margin of the Source Editor and choose Show Line Numbers.


2. On line 41 of the quote.cc file, type a capital C and press Ctrl-Space. The code completion box displays a short list that includes the Customer class. You can expand the list by pressing Ctrl-Space again.




3. Select the Customer class and press Enter.


4. Complete the new instance of the Customer class by typing " andrew;". On the next line, type the letter a and press Ctrl-Space. The code completion box displays a list of choices starting with the letter a, such as method arguments, class fields, and global names, that are accessible from the current context.




5. Double-click the andrew option to accept it and type a period after it. You are automatically provided with a list of the public methods and fields of the Customer class.




6. Delete the code you have added.

The IDE provides advanced navigation features for viewing your source code. To explore these features, we'll continue using the Quote_1 project.

Using the Classes Window

The Classes window lets you see all of the classes in your project, and the members and fields for each class.

1. Click the Classes tab to display the Classes window.


2. Expand the Quote_1 node. All classes in the project are listed.


3. Expand the Customer class.




4. Double-click on the name variable to open the customer.h header file.

Using the Navigator Window

The Navigator window provides a compact view of the file that is currently selected, and simplifies navigation between different parts of the file.

1. Click anywhere in the quote.cc file in the Editor window.


2. A compact view of the file is displayed in the Navigator window.




3. To navigate to an element of the file, double-click the element in the Navigator window and the cursor in the Editor window moves to that element.

Finding Class, Method, and Field Usages

You can use the Usages window to show you everywhere a class (structure), function, variable, macro, or file is used in your project's source code.

1. In the customer.cc file, right-click the Customer class on line 44, and choose Find Usages.


2. In the Find Usages dialog box, click Find.


3. The Usages window opens and displays all of the usages of the Customer class in the source files of the project.
   
   

Using the Call Graph

The Call Graph window displays a tree view of either the functions called from a selected function, or the functions that call that function.

1. In the quote.cc file, right-click on the main function and choose Show Call Graph.


2. The Call Graph window opens and displays a tree view of all of the functions called from the main function.




3. Select the end1 function.


4. Click the second button on the left side of the window to focus on the endl function, then click the bottom button to change the graph to a tree view of all of the functions that call the function.


5. Expand some of the nodes in the tree to see more functions.

Using Hyperlinks

Hyperlink navigation lets you jump from the invocation of a class, method, variable, or constant to its declaration, and from its declaration to its definition.

1. In the cpu.cc file of the Quote_1 project, mouse over line 48 while pressing Ctrl. The ComputeSupportMetric function is highlighted.




2. Click the hyperlink and the editor jumps to the definition of the function.




3. Mouse over the definition while pressing Ctrl, and click the hyperlink. The editor jumps to the declaration of the function in the cpu.h header file.




4. Click the left arrow in the editor tool bar and the editor jumps back to the definition.

Using the Include Hierarchy

The Include Hierarchy window lets you inspect all header and source files that are directly or indirectly included in a source file, or all source and header files that directly or indirectly include a header file.

1. In the Quote_1 project, open the module.cc file in the Source Editor.


2. Right-click on the #include "module.h" line in the file and choose Navigate > View Includes Hierarchy.


3. By default, the Hierarchy window displays a plain list of files that directly include the header file. Click the right-most button at the bottom of the window to change the display to a tree view. Click the second button from the right to change the display to all files that include or ar included. Expand the nodes in the tree view to see all of the source files that include the header file.

Using the Type Hierarchy

The Type Hierarchy window lets you inspect all subtypes or supertypes of a class.

1. In the Quote_1 project, open the module.h file.


2. Right-click on the declaration of the Module class and choose Navigate > View Type Hierarchy.


3. The Hierarchy window displays all of the subtypes of the Module class.

Runtime checking (RTC) allows you to automatically detect runtime errors (memory access, memory usage, memory leaks) in an application during the development phase. You can use runtime checking while running your application to collect an RTC experiment.

1. Choose File > New Project.


2. In the New Project wizard, expand the Samples node and select the Applications category.


3. Select the Freeway Simulator project. Click Next and then click Finish.


4. Select the Freeway_1 project in the Projects tab and choose Advanced > Runtime Memory Checking > Configure.


5. In the Project Properties dialog box, make sure the checkboxes for Access Checking and Check Memory Usage and Leaks are checked. Click OK.




6. Choose Advanced > Runtime Memory Checking > Start. The Freeway application window opens and a Runtime Memory Checking tab is displayed above the Editor window in the IDE.


7. Choose Actions > Start in the Freeway window and let the application run for about 30 seconds. Then choose Actions > Stop and click Quit.


8. The collected runtime checking data the collected data is displayed in the Memory Usage tab and the Memory Leaks tab in the Runtime Checking tab in the IDE.







9. The experiment is saved in the nbproject directory for the project.

You can also use runtime memory checking while debugging a project. To do so, select Enable RTC While Debugging when you set the runtime memory checking properties of the project. Then when you debug the project, runtime memory checking data is displayed whenever the program stops execution.

You can create and manipulate breakpoints in your code at any time.

Creating and Removing a Line Breakpoint

1. In the Quote_1 project, open the quote.cc file.


2. Set a line breakpoint by clicking in the left margin of the Editor window next to line 173 (response = readChar("Enter disk module type: (S for single disks, R for RAID; Q - exit)", 'S');). The line is highlighted in red to indicate that the breakpoint is set.


3. You could remove the breakpoint by clicking on the icon in the left margin.


4. Choose Window > Debugging > Breakpoints to open the Breakpoints tab. Your line breakpoint is listed in the tab.

Creating a Function Breakpoint

1. Choose Debug > New Breakpoint (Ctrl+Shift+f8) to open the New Breakpoint dialog box.


2. In the Breakpoint Type drop-down list, set the type to Function.


3. Type the function name Customer::GetDiscount in the Function text field. Click OK.




4. Your function breakpoint is set and is added to the list in the Breakpoints tab.

When you start a debugging session, the IDE starts the dbx debugger, then runs the application inside the debugger. The IDE automatically opens the debugger window and prints debugger output to the Output window.

Starting a Debugging Session

1. Start a debugging session for the Quote_1 project by right-clicking the project node and choosing Debug. The debugger starts and the application runs, and the Local Variables, Watches, Call Stack, Threads, Process I/O, and Dbx Console tabs open in the Debugging window.


2. Open the Sessions tab by choosing Window > Debugging > Sessions. The debugging session is shown in this tab.

Inspecting the State of the Application

1. The Quote application prompts you for input in the Process I/O tab.


2. Enter a customer name after the Enter customer name: prompt.


3. The application stops at the function breakpoint you set earlier. The Breakpoints tab lists the two breakpoints you set earlier. The green program counter arrow appears on top of the breakpoint icon of the function breakpoint.




4. In the customer.cc file, the green program counter arrow appears on top of the breakpoint icon on the first line of the GetDiscount function.





5. Click the Call Stack tab. The call stack shows three frames.




6. Click the Local Variables tab and note that one variable is displayed. Click the node to expand the structure.





7. Click the Continue button. The GetDiscount function is executed, printing the customer discount to the Process I/O tab. Then you are prompted for input.


8. Enter the input in response to the prompts. The program stops at the next breakpoint, the line breakpoint you set earlier. Click the Local Variables tab and note the long list of local variables.





9. Click the Call Stack tab and note that there is only one frame in the stack.


10. Click the Continue button and continue entering input in response to the prompts in the Process I/O tab until the program is completed. When you enter the last input to the program, your debug session ends. To end the debug session before the execution of the program was complete, you could right-click the session in the Sessions tab, and choose Finish.

Debugging at the Machine-Instruction Level

The debugger provides tabs that let you debug your project at the machine-instruction level.

1. Right-click the Quote_1 project and choose Debug.


2. In the Process I/O tab, type a customer name in response to the prompt.


3. When the program pauses at the breakpoint on the GetDiscount function, choose Window > Debugging > Disassembly to open the Disassembler tab as in the Editor window. The green program counter arrow appears on top of the breakpoint icon at the instruction on which the program is paused.




4. Choose Window > Debugging > Registers to open the Registers tab, which displays the contents of the registers, in the Debugger window.




5. Choose Window > Debugging > Memory to open the Memory tab, which displays the contents of memory currently used by your project, in the Debugger window. At the bottom of the tab, you can specify a memory address to browse, change the length of the memory browse, or change the format for memory information.

You can debug an executable that is not associated with a project.

1. Choose Debug > Debug Executable.


2. In the Debug dialog box, select the local host or a remote host from the Host drop-down list.


3. Type the full path to an executable in the Executable field, or click Browse and use the Select Executable dialog box to navigate to an executable.
   
   
4. When you have specified the executable, the Working Directory text field is automatically filled in with the directory where the executable is located.


5. By default, the Project text field displays either <no project> or the name of an existing project that exactly matches the name of the executable. If you want a new project created for the executable, select <create new project>.

   If you create a new project for your executable, only the executable is stored in the project properties. You need to set the other project properties by right-clicking the project in the Projects tab and choosing Properties.

6. Type any run arguments or environment variable settings for the executable in the Arguments and Environment Text Fields. These settings are not stored in the project properties if you created a new project for your executable.





7. Click Debug. The IDE runs the project in the debugger to the first line after the main routine, and pauses.

If you want to debug a program that is already running, you can attach the debugger to the appropriate process.

1. In the Projects tab, right-click the Freeway_1 project you created earlier and choose Run Project. The project builds and the Freeway application starts.


2. Choose Debug > Attach Debugger.
   


3. In the Attach dialog box, type Freeway in the Filter field to filter the list of processes.






4. Select the Freeway process from the filtered list.


5. Click OK.


6. A debugging session is started and execution of the Freeway process pauses at the point where the debugger attached to it.

If your program is crashing, you might want to debug the core file (the memory image of your program when it crashed). To load a core file into the debugger:

1. Choose Debug > Debug core file.


2. Type the full path to a core file in the Core File field.


3. If the debugger cannot associate the core file you specified with an executable, the Select Executable dialog box opens so that you can specify the executable. If this occurs, type the path name of the executable in the Executable text box, or click the Browse button and use the Executable dialog box to select the executable.


4. By default, the Project text field displays either <no project> or the name of an existing project that exactly matches the name of the executable. If you want a new project created for the executable, select <create new project>.
   
   
   
   
   
5. Click Debug.