EasyClangComplete

Sublime Text 3 plugin that offers clang-based auto-completion for C++

Linux / OSX	Windows

This plugin aims to provide easy-to-use, minimal-setup autocompletions for C++ for Sublime Text 3. Support it if you like it.

Jump right in!

Follow all the following steps to ensure the plugin works as expected!

Install this plugin

• Best is to use Package Control
  • CTRL+Shift+P and install EasyClangComplete
• If you don't have Package Control (you should)
  • download one of the releases from here.

Install clang

• Ubuntu: sudo apt-get install clang
• Windows: install the latest release from clang website
• OSX: ships clang by default. You are all set!
• on other systems refer to their package managers or install from clang website

Configure your includes

Are you using CMake?

Then you're good to go! All the flags should be guessed automatically. The plugin will create a folder for your project in the temporary folder, will run cmake -DCMAKE_EXPORT_COMPILE_COMMANDS <your_project_location> to generate the compilation database and will parse it to get correct flags for your project. The flags will be saved to .clang_complete file near a CMakeLists.txt that contains a project <name> line.

WARNING: this is in Beta state. Refer to issue #19 for discussions on the topic.

Not using CMake?

You will need a little bit of manual setup for now. Clang will automatically search for headers in the folder that contains the file you are working on and its parent. If you have a more sophisticated project you will need to help clang just a little bit. There are three ways to do it. Pick any of the following:

• Set include_dirs setting in User Settings:
  • see default settings to get started. These includes will be included in every project you run.
• Add .clang_complete file to the root of your project folder.
  • this file should contain all includes and macroses you want to use.
  • see example .clang_complete file.
  • absolute paths start with /. All the others are treated as relative.
• Add all the flags to pass to clang to *.sublime-project file.
  • add all settings as a string list under settings -> clang_flags.
  • See example sublime-project file.
  • absolute paths start with /. All the others are treated as relative.

That's it! You're ready to use the plugin!

More on the plugin

All the essential information to make the plugin run is written above. If you are still interested in more details - please read on.

General info

The plugin has two modes:

• one that uses libclang with its python bindings. This is the better method as it fully utilizes saving compilation database which makes your completions blazingly fast. It is a default method for Linux and OSX. It is also unit tested to complete STL functions on both platforms. Please help me to bring it to Windows. Check out this discussion.
• one that parses the output from clang -Xclang -code-completion-at run from the command line. This is the default method for Windows. Tested on all platforms (see Testing part). Slower than method with libclang. Will be deprecated when we solve issue #4.

This plugin is intended to be easy to use. It should autocomplete STL out of the box and you should just add the folders your project uses to include_dirs list in the settings to make it autocomplete code all your project. If you experience problems - create an issue. I will try to respond as soon as possible.

Commands

Here are some highlights for the commands. You can see all commands in command pallet. Open it by pressing:

• Windows/Linux: Ctrl + Shift + P
• OSX: Cmd + Shift + P

All the commands of this plugin start with EasyClangComplete: and should be self explanatory. Open an issue if they are not.

Settings highlights

I will only cover most important settings here.

PLEASE RESTART SUBLIME TEXT AFTER EACH SETTINGS CHANGE

• include_dirs:
  • stores the locations where clang should be looking for external headers, e.g. Boost, Ros, Eigen, OpenCV, etc.
  • you can use placeholders like $project_base_name or $project_base_path to make includes more convenient.
  • it is absolutely ok to include a folder that does not exist. clang knows how to deal with it and it will neither break anything nor make things slower.
• std_flag_cpp:
  • sets the standard flag that will be used for compilation of C++ code. Defaults to std=c++11.
• std_flag_c:
  • sets the standard flag that will be used for compilation of C code. Defaults to std=c11.
• use_libclang:
  • if true use libclang as backend.
  • if false or if first option failed, use output from clang -Xclang -completion-at command and parse it with regular expressions.
• search_clang_complete_file:
  • seach for .clang_complete file up the tree. Project folder is the last one to search for the file.
  • If the file is found, its contents of style -I<some_local_path> and -I/<some_absolute_path> (mind the / at the start of the line) are appended to include flags.
• errors_on_save:
  • highlight errors on save. A tooltip with an error message will be shown if the caret goes over a highlighted line.
• triggers:
  • defaults are ".", "::", "->". The autocompletion does not trigger on > or :. It also ignores float numbers like 3.14.
  • For them to work, the Sublime Text completion triggers have to be configured too. These are already set to match triggers by default. You can also set these settings manually by copying the default ones defined here to your User Preferences and modifying them there.
• use_project_specific_settings:

  • when true will enforce sublime text to read all flags from project settings(*.sublime-project -> settings -> clang_flags). This settings overrides all other settings like include_dirs or std_flag so should be used with caution. Defaults to false. If the project settings cannot be found, the plugin will fall back to default behavior. An example settings entry looks like this:

    {
      "settings":
      {
        "clang_flags":
        ["-std=c++11", "-Isrc", "-I/usr/include",]
      }
    }

Please see the default settings file in the repo for more settings descriptions. Every setting in settings file should have an understandable comment. Should they not be clear - create an issue.

Credits

The whole work seen here was originally a fork of another repository: ClangAutoComplete

However, with time this plugin has grown quite different from its origin and this is why you see it as a separate package now. Anyway, I encourage you to check out what ClangAutoComplete has to offer and come back if you still like this plugin more.

The trick with multiple clang.cindex files is inspired by this repo: clangHelper. Thanks for inspiration!

If you are an experienced python developer and find that something in my code sucks completely - DO tell me. Python is not my main language and I am always willing to learn.

Some functionality is there only because of the help of the following users (in no particualr order):

@Ventero, @riazanovskiy, @rchl, @Mischa-Alff, @jdumas.

Tests

I have tried to cover most crucial functionality with unit tests using UnitTesting Sublime Text plugin. Currently tests cover autocompletion of user struct and stl vector using clang binary. To check out the current status click on relevant badge below:

Linux / OSX	Windows

Support it!

Current sponsor of this project is my sleep. Please buy me a cup of tea if you appreciate the effort.