Directories under your control: ‘Mark Directory As’

Hi,

Recently we’ve opened the Early Access Program for CLion 1.5, with many hot features on board that we’d like to introduce you to. Let’s take a closer look at a new feature called “Mark directory as”.

When you open the context menu for a directory and select “Mark Directory As”, you can see three options:
mark_directory

Each one serves a particular use case. Let’s explain them going from the bottom up:

  • Mark directory as Excluded: CLion indexes all the directories listed in your CMake files, like sources or include_directories paths, in order to provide you with accurate code completion, navigation, refactorings, code analysis and other smart features. However, some folders may contain binaries, logs, generated data, or build artifacts that do not really affect the Intellisense that CLion provides. There’s no sense in indexing them.

    Although CLion automatically excludes build directories from indexing, some users expect wider options. The same situation can happen when some folders are too big or located on network storage, making their indexing too expensive. To let CLion know that this is the case, you may want to manually exclude folders from indexing.

    Note that you can exclude only directories located under your project root. Also, to ensure consistent behavior, build directories have to be excluded manually via the new option, i.e. they are no longer excluded automatically.

  • Mark directory as Library files: When working with libraries, you may want to disable refactoring for library folders and take control over navigation and search actions. This means it’s up to you to decide whether to include symbols from these directories or not, when navigating to symbol/class/file, and whether to search through them.

    From the compiler perspective, <>-includes are library headers, while “”-includes are user project headers. But the choice of <> vs “” imports is a matter of project configurations, and sometimes taste. Moreover, in the same project a given header file may be included both as <> and as “”-include. From the IDE perspective, that means we cannot rely on the automatic libraries vs project headers detection, and the user needs manual control.

    We started working in this direction this summer, trying to highlight project/libraries files in a more visible way in the IDE. We’ve now come to a more generalized solution where you can mark directories as libraries and thus let CLion know what’s what. Thanks to all your valuable feedback that has influenced this decision – keep it coming!

  • Mark directory as Project sources and headers: Reverse situations are also possible. Suppose you have a lot of headers that are really part of project sources. How do you let the IDE know about them? One simple situation is when you can include these headers in your sources (in this case the IDE builds an index and thus knows about them). But can you get navigation and completion for symbols from these headers before they are actually included? Yes, if you manually give the IDE a hint, by using this ‘Mark Directory As’ option.

Now let’s explore how selecting these options affects CLion’s code assistance features in a practical way.

In case of files included into the project, i.e. Project files, you’ll get the whole set of smart features after indexing is done:

  • Code completion and auto-import
  • Code generation
  • Find in Path
  • Navigation actions, like Go to Class/File/Symbol, and
  • A range of refactorings

How do these features behave for Excluded and Library files?

Code completion and auto-import

Symbols from Excluded files are not completed since the IDE is not aware of them. However, if you first include the files from the excluded directories explicitly, then completion will work.
The same is true for Library files. Both cases will become similar to Project files if the directory is marked with include_directories in your CMake files.

Code generation

Code generation is not available in either Excluded or Library files. If you try using the Generate action (Alt+Insert on Linux/Windows, ⌘N on OS X), you will get the New... dialog which can help you create a new file or C++ class.

Find in Path

Find in Path feature allows you to search for a key through the selected scope (Shift+Ctrl+F on Linux/Windows, ⇧⌘F on OS X):

  • Whole project
  • Any directory in particular
  • Custom scope, that could include
    • Project files
    • Project and Libraries
    • Open files
    • Current file
    • Selected files (if any selected)
    • VCS scope

As you can see, the only way to search through the Excluded directories is to select them manually in search or to search through current/opened files.

As for library files, there is a separate custom scope called ‘Project and Libraries’. Select it to include libraries into search results:
find_path

Navigation actions, like Go to Class/File/Symbol

CLion offers lots of possibilities to navigate across your project. Among them, you can find:

  • Go to Class (Ctrl+N on Linux/Windows, ⌘N on OS X) takes you to a particular class.
  • Go to File (Ctrl+Shift+N on Linux/Windows, ⇧⌘O on OS X) takes you to a particular file.
  • Go to Symbol (Ctrl+Alt+Shift+N on Linux/Windows, ⌥⌘O on OS X) locates a particular symbol for you.

Symbols from Excluded folders are not included into these searches (since these directories were not indexed at all).

However, for library files they can be included. Simply tick the Include non-project classes option in the corresponding dialog.

Compare the result for project files only:
find_project

and for libraries symbols added:
find_library
By the way, if you don’t include non-project symbols, but no matching symbols are found in the project, CLion will search through the libraries automatically.

Refactorings

Refactorings are not allowed inside files that are excluded or marked as libraries:
element is not inside the project
However, you can still perform some refactorings for whole files, like moving, copying or renaming files.

This wraps it up for Mark Directory As. Please give it a try and share your feedback in the comments section below.

Sincerely yours,
The CLion Team

This entry was posted in Tips'n'Tricks and tagged , , , . Bookmark the permalink.

8 Responses to Directories under your control: ‘Mark Directory As’

  1. Johan says:

    This is an amazing feature! Is it possible for me to annotate our CMakeFiles to specify if things should be excluded and/or library files?

    • Anastasia Kazakova says:

      This thing is independent from the CMakeFiles. And that was done on purpose, since CMake model is not that flexible (for example, -iquote is still not supported by CMake, as fas as we know). So this is more a way to explain some additional things to the IDE in case you want to.

  2. Dorin says:

    Hi, do you think about adding support for resources, stuff that need to be copied to be able to debug? Like images, audio tracks, etc?

  3. Suresh Subramani says:

    When can we expect a feature parity with Eclipse C-IDE
    In terms of Project Definition, Build Definition, Support for different compilers
    CMake is very unfriendly.

    • Anastasia Kazakova says:

      Which compilers are you interested in? Now it’s GCC, clang and Intel that can be used.
      Could you please share more details about the rest? What exactly you are expecting from CLion?

  4. Henry says:

    This is an awesome feature.

    One thing I would really like to see is the ability to create your own labels to mark a directory as. Maybe make it so you can add custom action options with said custom labels.

    • Anastasia Kazakova says:

      That’s not about custom label actually, this is more about how CLion understands some directories in your project. And you are talking about slightly different thing, as far as I understand. How are you gonna use these labels? Could you share some use cases to understand how CLion should behave?

Leave a Reply

Your email address will not be published. Required fields are marked *