| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| <meta name="author" content="Nikolay.Krasilnikov@oracle.com"> |
| <meta name="description" content="A short guide to macro features in C/C++ projects in |
| NetBeans IDE or Oracle Solaris Studio IDE."> |
| <meta name="keywords" content="NetBeans, IDE, macros, |
| tutorial, guide, user, documentation, open source, C, C++, make, dbx, gdb"> |
| <link rel="stylesheet" type="text/css" href="../../../netbeans.css"> |
| <title>Exploring Macros in C/C++ Projects - NetBeans IDE Tutorial</title> |
| </head> |
| |
| <body style="padding: 2px;"> |
| <h1>Exploring Macros in C/C++ Projects - NetBeans IDE Tutorial</h1> |
| <div class="articledate" style="margin-left: 0px;font-style:italic;"> |
| <p><em>Contributed by <a |
| href="mailto:Nikolay.Krasilnikov@oracle.com"><i>Nikolay Krasilnikov</i></a> <br> |
| October 2013</em> [Revision number: V7.4-1]</div> |
| <p>This tutorial shows you how to use new NetBeans IDE features |
| for investigating and debugging code that includes macros.</p> |
| |
| <p><b>Contents</b></p> |
| <img src="../../../images_www/articles/73/netbeans-stamp-74-73.png" class="stamp" |
| alt="Content on this page applies to NetBeans IDE 7.3 and 7.4" title="Content on this page applies to the NetBeans IDE 7.3 and 7.4"> |
| |
| <ul class="toc"> |
| <li><a href="#requirements">Requirements</a></li> |
| <li><a href="#investigate">Investigating Code That Uses Macros</a></li> |
| <li><a href="#debug">Debugging Code That Uses Macros</a></li> |
| |
| </ul> |
| |
| |
| <h2><a name="requirements"></a>Requirements</h2> |
| <p><b>To follow this tutorial, you need the following software and resources.</b> </p> |
| |
| <table> |
| <tbody> |
| <tr> |
| <th class="tblheader" scope="col">Software or Resource</th> |
| <th class="tblheader" scope="col">Version Required</th> |
| </tr> |
| <tr> |
| <td class="tbltd1">NetBeans IDE</td> |
| <td class="tbltd1"><a href="https://netbeans.org/downloads/index.html">version 7.3 or 7.4 with NetBeans C/C++ plugin</a></td> |
| </tr> |
| <tr> |
| <td class="tbltd1">Java Developer Kit (JDK)</td> |
| <td class="tbltd1"><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">version 6 or 7</a></td> |
| </tr> |
| </table> |
| <p>See the <a href="../../../community/releases/74/install.html">NetBeans IDE |
| Installation |
| Instructions</a> and <a |
| HREF="../../../community/releases/74/cpp-setup-instructions.html"> |
| Configuring the NetBeans IDE for C/C++/Fortran</a><br> for |
| information about downloading and installing the required software. |
| </p> |
| <h2><a name="investigate"></a>Investigating Code That Uses Macros</h2> |
| <p>Macros are hyperlinked so that when you Ctrl-click them, the IDE opens the header |
| file where the macro is defined. However, sometimes for |
| simple macros such as numerical constants or string literals you might only want |
| a quick look at the macro definition.</p> |
| <p> |
| NetBeans IDE provides two features for quickly exploring source code that contains macros:</p> |
| <ul> |
| <li>Macro tooltips, useful for short and simple macros</li> |
| <li>Macro Expansion window, useful for more complex macros</li> |
| </ul> |
| <h3><a name="tooltips"></a>Working with Simple Macros Using Macro Tooltips</h3> |
| <p>The tooltips for macros allow you to view a small popup without opening another file. |
| </p> |
| |
| |
| <p><b>To activate a macro tooltip so you can see its expansion:</b></p> |
| <ol><li>Press and hold Ctrl+Alt.</li> |
| <li>Place the mouse cursor on the macro you want to expand, and a tooltip opens to display |
| the expanded information, as shown in the figure below.</li> |
| </ol> |
| <P><IMG SRC="../../../images_www/articles/73/cnd/macros/macro-tooltip.png" alt="Macro tooltip expansion" class="b-all margin-around"></P> |
| |
| |
| <h3>Working with Complex Macros Using Macro Expansion Window</h3> |
| <p> |
| The Macro Expansion view enables you to investigate source code with complex multiple-line macros. |
| Macros are often used to define constants, but can also be used to define code fragments that |
| can be used like functions. When you work with code that uses macros in this way, it might be |
| difficult to understand what is happening in the code. You may need to examine the macros |
| in context with the source code that is calling the macro. |
| </p> |
| <p><b>To view the source code with expanded macro code:</b></p> |
| <ul> |
| <li>Right-click on the macro and select Navigate->View Macro Expansion from the pop-up menu.<br> |
| The Macro Expansion window opens to display the expanded macro in context with the code that calls it.</li> |
| <li>You can also mouse over the code of interest while pressing Ctrl+Alt, and click the hyperlink to open the Macro Expansion window.</li> |
| </ul> |
| <p>The following figure shows the Macro Expansion window.</p> |
| <p> |
| <IMG SRC="../../../images_www/articles/73/cnd/macros/macro-expansion.png" alt="Macro expansion view" class="b-all margin-around"> |
| </p> |
| <p> |
| In the Macro Expansions window, the macro contents are located inside guarded blocks. |
| Semantic highlighting is provided for expanded code. |
| You can use hyperlinks in the Macro Expansion window to go to other source files. |
| Also there is highlighting for macro parameter usages. |
| </p> |
| <p> |
| The left column of the Macro Expansion window includes several toolbar buttons:</p> |
| <ul> |
| <li>Synchronize caret, content and context<br> |
| This option synchronizes caret position and content in the |
| source file in the Editor window and in the Macro Expansion window.<br> |
| It also changes context to make it relevant to caret position (if expand local context only selected). |
| </li><li>Expand local context only |
| Only the macros in the code block where the caret is located are expanded in the Macro Expansion window. |
| </li> |
| <li>Expand whole file<br> |
| All macros in the source file are expanded in the Macro Expansion window. |
| </li> |
| <li>Up and down arrows<br> |
| These buttons are for quick navigation to go to the next macro or go to the previous macro.</li> |
| </ul> |
| |
| <h2><a name="debug"></a> Debugging Code That Uses Macros</h2> |
| <p> |
| Sometimes it is not enough to understand the meaning of a macro.<br> |
| For example, suppose you are debugging the following code: |
| </p> |
| <pre>#include <stdlib.h> |
| #include <iostream> |
| |
| #define ID_FIRST (0) |
| #define ID_ALICE (ID_FIRST) |
| #define ID_BOB (ID_ALICE + 1) |
| #define ID_TOM (ID_BOB + 1) |
| #define ID_FRINDS_NUMBER (ID_TOM + 1) |
| |
| #define NEXT_PERSON(id) (id + 1) |
| #define PREV_PERSON(id) (id - 1) |
| |
| using namespace std; |
| |
| /* |
| * Main function |
| */ |
| int main(int argc, char** argv) { |
| int person = ID_TOM; |
| if (NEXT_PERSON(person) == ID_FRINDS_NUMBER) { |
| cout << "last person"; |
| } |
| return (EXIT_SUCCESS); |
| } |
| </pre> |
| <p> |
| Imagine that you stopped the debugger on the <tt>if</tt> statement and you want to know if the program will print "last person" or not. |
| </p> |
| <p> |
| Macro expansion tooltip says that <tt>ID_FRINDS_NUMBER</tt> is "<tt>(((((0))+ 1)+ 1)+ 1)</tt>".<br> |
| How much is <tt>ID_FRINDS_NUMBER</tt>? |
| In this simple situation it might be easy to say that the value of <tt>ID_FRINDS_NUMBER</tt> is 3, but it might not be as easy if you have two thousand persons. |
| </p> |
| <p>You might find it useful to evaluate the expression in the macro when debugging, as explained below.</p> |
| <h3>Evaluating Macros Using Tooltips</h3> |
| <p> |
| You can use expression evaluation on expressions with macros in the debugger.<br> |
| Hover the mouse pointer over <tt>ID_FRINDS_NUMBER</tt> and you see what is shown in the following figure:<br> |
| </p> |
| <p> |
| <IMG SRC="../../../images_www/articles/73/cnd/macros/macro-debugging-expression-evaluation.png" alt="Macro expression evaluation" class="b-all margin-around"> |
| </p> |
| <p> |
| You can also select the whole expression and mouse over it to evaluate the expression in a tooltip, as shown in the following figure:<br> |
| </p> |
| <p> |
| <IMG SRC="../../../images_www/articles/73/cnd/macros/macro-debugging-expression-evaluation-2.png" alt="Macro expression evaluation" class="b-all margin-around"> |
| </p> |
| <p class="tips"> |
| Be careful evaluating macros in tooltips, because such evaluation can change the state of a program. |
| For example evaluating of macro that expands to <tt>i++</tt> will increment <tt>i</tt>. |
| </p> |
| |
| <h3>Using Watches for Evaluating Macros</h3> |
| <p> |
| It is possible to use macros in debugger watches, as shown in the following figure:<br> |
| </p> |
| <p> |
| <IMG SRC="../../../images_www/articles/73/cnd/macros/macro-debugging-watches.png" alt="Macro debugging watches" class="b-all margin-around"> |
| </p> |
| <p class="tips"> |
| Be careful evaluating macros in watches, because such evaluation can change the state of a program. |
| For example evaluating of macro that expands to <tt>i++</tt> will increment <tt>i</tt>. |
| </p> |
| <h2>See Also</h2> |
| <p>Please see the |
| <a href="https://netbeans.org/kb/trails/cnd.html">C/C++ Learning Trail</a> for |
| more articles about developing with C/C++/Fortran in NetBeans IDE.</p> |
| |
| <div class="feedback-box"><a href="mailto:users@cnd.netbeans.org?subject=Feedback:%20Exploring%20Macros%20in%20C/C++%20Projects%20-%20NetBeans%20IDE%207.4%20Tutorial">Send Feedback on This Tutorial</a></div> |
| |
| </body> |
| </html> |
