How to use CLion with our software: Difference between revisions

From OPeNDAP Documentation
⧼opendap2-jumptonavigation⧽
mNo edit summary
Line 98: Line 98:
Goto the Edit Configurations item under the build item in the 'toolbar' or ''Run'' menu:
Goto the Edit Configurations item under the build item in the 'toolbar' or ''Run'' menu:


[[File:clion_edit_config.png|320px|border|Terminal window]] [[File:clion_run_menu.png|400px|border|Terminal window]]
[[File:clion_edit_config.png|320px|border|Edit Configurations...]] [[File:clion_run_menu.png|400px|border|Run menu]]


And this will bring up a dialog for those items. Initially the dialog will look like:
And this will bring up a dialog for those items. Initially the dialog will look like:


[[File:clion_initial_edit_conf_dialog.png|960px|border|Terminal window]]
[[File:clion_initial_edit_conf_dialog.png|960px|border|Edit configurations dialog]]


Edit that so it looks like:
Edit that so it looks like:


[[File:clion_targets.png|960px|border|Terminal window]]
[[File:clion_targets.png|960px|border|Targets]]


Where the different targets can be edited. There's no real reason to do them all, just get ''all'', ''clean'' and ''check'' working.
Where the different targets can be edited. There's no real reason to do them all, just get ''all'', ''clean'' and ''check'' working.
Note that the ''Target:'' drop down list can either be a ''custom build configuration'' (something you can set up by clicking the gear to the right) or it can be one of the Makefile targets. It's easier to use one of the Makefile targets. I'm not 100% sure what this does... However, if leave it blank, the build won't start.


Most of the settings are straightforward, but the Environment variables are not. You need to set the environment variables so that ''PATH'' matches the value that the ''spath.sh'' script will set. Generally, this is the default value of ''PATH'' prefixed with ''$prefix/deps/bin:$prefix/bin'' where you should expand ''$prefix''. There may be a way to set values of environment variables that are used by default for a project, but I have not found it. Note that the first path is used to find things like ''ncdump'' while the second is used for things like ''besstandalone''. Both paths are needed to run the tests. The assumption is that the Makefiles are built using ''configure'' in a shell with the ''PATH'' set.
Most of the settings are straightforward, but the Environment variables are not. You need to set the environment variables so that ''PATH'' matches the value that the ''spath.sh'' script will set. Generally, this is the default value of ''PATH'' prefixed with ''$prefix/deps/bin:$prefix/bin'' where you should expand ''$prefix''. There may be a way to set values of environment variables that are used by default for a project, but I have not found it. Note that the first path is used to find things like ''ncdump'' while the second is used for things like ''besstandalone''. Both paths are needed to run the tests. The assumption is that the Makefiles are built using ''configure'' in a shell with the ''PATH'' set.

Revision as of 03:39, 1 September 2022

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

Other sources of this kind of information

From Jet Brains
Makefile support

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.

You can check that this really has been slurped up as a Makefile project by looking under the Tools menu.

Tools menu

To configure the automatic indexing, go to the CLion menu and choose Preferences..., In the dialog, open up the Build, Execution, Deployment section and select Makefile:

Preferences --> Build, ... --> Makefile

Now, here's where we are going to fix things so indexing works.

Make the dialog entries look like this:

Build, ... Done Right

To wit:

  1. Build Directory: "." (i.e., the current working directory)
  2. Build options: "-j20" (unless you don't have 20 cores, in which case use a lower number ;-)
  3. Pre-configuration commands: "make all -j20" (This seems redundant because we're going to run make as part of 'pre-configuration' and then we're going to do it all over again in the next section. However, we need to run make once as part of pre-configuration because make generates some of our source code)
  4. Arguments: "-j20" (unless...)
  5. Build target: "check" (For libdap4 I use check because that works to build all the source and the tests and we want everything to build so it's all indexed. For the BES use all check instead)
  6. Clean target: "clean"

Now, re-run the indexing. In the "Build" section of the bottom pane, click on the 'recycle' symbol inthe upper left corner:

Build, ... Done Right

If you open code like Byte.cc, it should look like this after a few seconds:

Build, ... Done Right

Building code in CLion

The big win here is that when code is built in the IDE, the errors and warnings are links that will take you directly to the source of the error.

Goto the Edit Configurations item under the build item in the 'toolbar' or Run menu:

Edit Configurations... Run menu

And this will bring up a dialog for those items. Initially the dialog will look like:

Edit configurations dialog

Edit that so it looks like:

Targets

Where the different targets can be edited. There's no real reason to do them all, just get all, clean and check working.

Note that the Target: drop down list can either be a custom build configuration (something you can set up by clicking the gear to the right) or it can be one of the Makefile targets. It's easier to use one of the Makefile targets. I'm not 100% sure what this does... However, if leave it blank, the build won't start.

Most of the settings are straightforward, but the Environment variables are not. You need to set the environment variables so that PATH matches the value that the spath.sh script will set. Generally, this is the default value of PATH prefixed with $prefix/deps/bin:$prefix/bin where you should expand $prefix. There may be a way to set values of environment variables that are used by default for a project, but I have not found it. Note that the first path is used to find things like ncdump while the second is used for things like besstandalone. Both paths are needed to run the tests. The assumption is that the Makefiles are built using configure in a shell with the PATH set.

You can cut and paste the value of PATH or use the dialog brought up using the little box icon on the right of the Environment variables edit field. That dialog looks like:

Terminal window

One trick, however, is to use -k when you run make. This will build all the code instead of stopping at the first error (drop the -k if want to stop at the first error). This way you can fix a bunch of small issues without the time to run lots of builds.

Lastly, look at the list box at the bottom. It will have a single entry Build. Remove that by clicking on it and then clicking the minus sign at the top of the list box (right next to the plus sign). This will keep a default build from running before the build you just configured.

Run a build

To run a build, choose the item and hit the play button to the right:

Run window

To goto the line where there is an error or warning, click the link:

error links

Running the debugger