Tips & Tricks

Directories under your control: ‘Mark Directory As’


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:

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:

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:

and for libraries symbols added:
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 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

image description