How to use CLion with our software

From OPeNDAP Documentation

Setting up CLion to work with our software is really the same as using CLion with a 'Makefile' project. By default, CLion uses CMake to to figure out which files are part of a program or library. The problem for our software, and any software that does not use CMake, is that most of the benefit(s) of CLion (or any IDE) depend on knowing all the files that are used to build a program or library.

This page shows how to set up CLion with software that uses make and/or autotools.

1 The whole server or just parts

First, you need to decide if you want to work with all of the C++ code as one 'project' or use a separate project for each of 'hyrax-dependencies,' 'libdap4,' and 'bes.' In practice, you choose one way and then switch without paying too great a penalty.

For the rest of this HowTo, I'll assume you have done the following:

  1. Checkout the hyrax git repo from GitHub (https://github.com/opendap/hyrax) and ...
  2. Have used the script(s) to checkout the three C++ projects 'hyrax-dependencies,' 'libdap4,' 'bes.'
  3. Or, you've done something else to get our server code...

2 Open a directory that contains code

When you start CLion, you will see a dialog box New Project dialog

Click on the New CMake Project from Sources and you will see the following Choose the directories to scan

Use this dialog to choose which directories to scan. CLion will scan the selected directories. looking for code to be compiled and also, in the lower panel, for headers to be included. In the later case, code all the dirs with headers you want to be found. For Hyrax, that means the $prefix/build/deps/include and $prefix/build/include directories. The end result will take a few seconds to load and will show messages at the bottom of the screen regarding various scanning and indexing operations. Once this process completes, you should get a CMakeLists.txt file that is pretty comprehensive (AFAIK, this cannot be used to build code without some additions, but it serves as a database for CLion. It may be that we need to add some extra directories to it for things like the libxml2 and curl headers). Regardless of my parenthetical comments, you should see something like this: CMakeLists file

Drive around in the source panel and open some code. It should look 'good' in the sense that there are not many false positive error flags.

2.1 A second way to make the database

The CMakeLists file is one of two 'databases' you can make for CLion to describe the contents of a C++ project - the other is a compiledb json file. This is built from a python tool called compiledb. But there's a trick. In the simplest use, this tool is used like this compiledb -n make. But this alone probably won't work. Unless the directory is clean (i.e., make clean) make won't build anything and compiledb won't put anything in the database. Second, command line arguments to make seem to confuse compiledb. However, it will work to pipe the output of make into compiledb, like this make -nwk all | compiledb.

I'm not sure if this is useful or if editing the CMakeLists.txt file will be sufficient for our needs.

3 Building the code

There are several ways to run builds from within CLion. Here's an overview:

  1. Use the terminal window. It is just like a regular terminal window, so you need to source spath.sh at the root of the hyrax project. This is the simplest way to run builds, but it does not lay the groundwork for debugging.
  2. Using the Makefile plugin is another way, but the result does not provide an easy way to find compilation warnings or errors (that is, click on the error and goto the source file/line without having to search).
  3. Using a Custom Build Application is similar to the Makefile plugin but does set the IDE up debugging and does provide a decent way to link to warnings/errors.

3.1 The terminal window

You know how to run make in a terminal... Here's what the terminal looks like. This shows that, for hyrax, you need to source the spath.sh file.

Terminal window

3.2 Setting up Custom Build Applications

For our Hyrax project you can make your work easier if you do one little, but somewhat odd, step first. Goto the hyrax-dependencies/src/bison-x.y directory and re-run configure using the defaults (i.e., just run ./configure). Then build and install bison. This will install the bison executable in /usr/local/bin which technically 'pollutes' your build environment, but means that most of the complicated things you need to do with the PATH environment variable in the following section become moot.

This is tricky because you have to do two steps here, one is to set up a Custom Build Target and the second is to set up a Custom Build Application. The Target is needed for the Application to be valid, and for things like the BES, the Target also works to build the code. But, for libdap, the Target will only build the code if bison 3.x is installed in a directory on your default PATH. If not, then the Target described here won't work (but is still required as a placeholder). The general rule is that the Target only works with all of the tools needed for the build are on the PATH that is used when the OS starts CLion.

Condensed version: Open the Edit Configurations doalog int he Run menu and then use that to make a Custom Build Application with a Custom Build Target. Once you have the Target set, deselect the Build item in the lower part of the Application dialog and then set up the make binary to build the code. Set PATH as needed (i.e., for libdap, make sure the include the .../build/deps/bin dir on PATH).

Confused? Follow the expanded directions below:

Open the Edit Configurations... dialog using the Run menu (there is also an option to open this from the Run menu's Run... item).

The menu: Run Menu

The dialog: Edit Configurations...

Open the Custom Build Targets Dialog by clicking the blue pseudo-link near the upper right corner of the dialog. Notice that you're now looking at the Preferences dialog. Look at the right edge of the dialog for buttons with ellipses in them. You might need to study this dialog for a bit...

Open the CBT dialog

For each of Build and Clean, click the ellipses button and you will see another dialog. At the bottom of this tall, skinny window, click the plus sign to define a new Target.

Custom Build Targets

To build a C++ library or program using a Makefile, set the Program to be /usr/bin/make. Note that for this, there's no option to alter the PATH, so if the build depends on a tool (e.g., bison) that is not in the PATH, it will fail. The BES is fine but libdap needs bison 3.x. You can put that in /usr/local/bin. You might have to fiddle with things on OSX to get than on you 'default PATH (the PATH used by things the Finder starts). Regardless of whether it works in general or not, you need to define these ... Targets. NB: You might be able to pass PATH in as a command line argument - I have not tried that.

Make/edit a build Target

Now, once you have filled in the dialog, close it and use the menu to the left of the ellipses button to choose the thing you just defined. Make one Target for make all and one for make clean.

Close the dialog(s).

Fill in the ... Applications dialog. Here you can put pretty much whatever you want. For standard build commands (all, clean, check, ...) set up things as you'd like them. For OSX, the make executable is found down in /Applications/Xcode/Contents/Developer/usr/bin/ Note that for tests, adding TESTSUITEFLAGS=-j8 to the program arguments will run the autotest tests in parallel.

Here's that Custom Build Applications dialog again: Custom Build Applications

Note how PATH is hacked. For hyrax, you will want to put both .../build/bin and .../build/deps/bin on PATH (even though the example doesn't). Also note that the large dialog at the bottom does not have a Before Launch: Activate tool window item. By default, that will be Build but for libdap, that will fail. So, select that and remove it with the minus sign.

4 Running the debugger