How to use CLion with our software

From OPeNDAP Documentation
⧼opendap2-jumptonavigation⧽

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.

NB: I used CLion version 2022.2.1. I think anything from 2022 works as I describe here.

New Project dialog

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

Before going to the next section, if you are using a fresh checkout of the sources, use autoreconf and configure to get a valid Makefile. Doing this will make things easier. Since we have a CMakeList.txt file in the repo, we need to have a Makefile in there, too. So, run

autoreconf --fiv
./configure --prefix=$prefix --enable-developer

Where you can fiddle with the arguments to configure (you don't need --enable-developer and you can use whatever path you want for the prefix value).

What is important is that the directory contain a Makefile.

Getting CLion to index our code

Assuming your source code (I'm using libdap4) does not contain a .idea directory, you can just 'Open' the directory or go into the repo directory and open the Makefile. Either way seems to work. The key thing is that you convince CLion that this is a Makefile project:

New Project dialog

In the dialog that pops up, navigate to the directory that contains your sources:

New Project dialog

Since the directory has both a CMakeLists.txt and a Makefile, CLion asks which kind of project you want to make.

New Project dialog

Note that you can also choose the Makefile explicitly and IIRC, CLion will skip the question but instead ask if you want to open just the file or import a new project based on the Makefile.

The two key things to getting this to work are to have the Makefile in the directory and to using Open. Using the options to make a New Project lead me round and round and the checkout from Get From VCS won't get something with a Makefile and then you'll be stuck with a CMake project. You might be able to coerce CLion to switching by re-opening the directory once it has a Makefile, but I have not tried that.

Aside: Once you have done this once, you can click on the name in the Choose Project dialog and it'll open as a Makefile project.

It's all pretty cool except, you'll see that there is a bit of a mess at the bottom of the CLion window that looks like indexing has failed. It has.

Index FAIL!

However, now we are ready to...

Configure this project for a Makefile build

This is the key to getting the code to index and that is the key to all the sophisticated navigation capabilities of this IDE.

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.

Terminal window

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

Running the debugger