How to use CLion with our software

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.

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 can choose one way and then switch to the other 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 clone the three C++ projects hyrax-dependencies, libdap4, bes in that hyrax directory.
3. Or, you've manually cloned the hyrax-dependencies, libdap4, bes repos somewhere useful to you (which can be that hyrax directory). The 'magic' provided by the hyrax project is minimal. It does, however, contain a script called spath.sh that sets up some SHELL environment variables you may find useful and that will keep you from endless hours of headscrathing while you try to sort out why changes made to libdap don't seem to have any effect (the answer is that you have a hidden version of libdap installed in /usr/local/{bin,lib,include} and it's that library that is being used, not the copy you have just changed). Always using spath.sh saves you from that part particular nightmare.

Open a directory that contains code

I think it's best to have the three C++ projects/repos (hyrax-dependencies, libdap4, and bes) each opened independently, so let's do that, and open libdap4 for now. However, if you have already opened the hyrax repo, take a quick peak in the libdap4 directory it contains and see if there's an .idea directory in there. If there isn't, you should be able to open the libdap4 directory and follow all of the instructions that follow. CLion only reads project information from the .idea directory in the at the top level of the project it opens. If there is an .idea directory in there already, remove it (there's nothing sacred in there...).

The real power of something like CLion is that it can read and analyze the source code, providing a way to navigate from file to file finding the stuff you want without you doing too much searching. We have 1,000s of files and 100,000s of lines of code. In the (dark) past, we had to use CMake to do this. Now, in the renaissance, we can configure our projects using the Makefiles that we actually use to build the code. This has several advantages, including 1. Not having to maintain two lists of sources and, 2. builds where the errors and warnings are clickable links into the actual code (no more matching errors to line numbers in the editor).

This HowTo will cover both of those 'scenarios'

Getting CLion to index our code

Assuming your source code (I'm using libdap4) does not contain a .idea directory, you will need to make a 'New Project':

Click that, click the kind of project and then navigate to the sources. The kind of project doesn't matter much, but C++ library fits for libdap4 so I used that. Click Open and Create and you will see... a mess. Don't worry.

You should see something like this:

Error creating thumbnail: File with dimensions greater than 12.5 MP

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.

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.

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 dialog in the 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:

The dialog:

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...

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.

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.

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:

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.