Coming in 4.13: Improvements in the project plugin

Since version 4.10 Kate comes with a simple project plugin, as introduced here .
The project plugin works by automatically reading a simple json file and providing the information found there to various parts and plugins in Kate.

“Opening” a project

Projects are opened automatically by Kate. Whenever a file is opened, Kate goes the directories from that file upwards until it finds a file named .kateproject , which defines the project. This is a simple json file, which is intended to be written manually by the user.

The .kateproject file defines the name of the project, the set of files which belong to the project, and optionally commands for the build plugin .

In 4.13, “out-of-source” project files are now also supported (actually already in 4.12).  What does that mean ? You can create a .kateproject file in some directory, but it will refer to a different directory as root of the project. This is useful if you have multiple build trees for one source tree, and then need different build commands for each build tree.

Creating such a .kateproject file is easy, simply add a top-level “directory” entry:

{
    "name": "MyProject",
    "directory": "/home/alex/src/myproject",
    "files": [ { "filters": [ "*.cpp", "*.h"] } ]
}

So if you create this file e.g. in /home/alex/src/myproject-build/.kateproject, once the project is opened, the files below /home/alex/src/myproject/ will belong to the project “MyProject”. Again, to “open” this project, open any file in the same directory as the .kateproject file or any of its subdirectories in Kate. Kate will again automatically find the .kateproject file and load it.

Support for the improved build plugin

In 4.13 the build plugin has seen several improvements, the main one being that it is now possible to define an arbitrary number of targets, instead of being limited to 3. This is fully supported by the project plugin. Also the “old” format is still fully supported, and the .kateproject files can even contain both the old and the new format, so it works with the build plugin in version before 4.13 and also after.

Below there is a simple example for a hello-world project, which defines 4 targets for the build plugin: build all, clean, install and building just “hello”:

{
    "name": "Hello",
    "files": [ { "filters": [ "*.cpp", "*.h"] } ],

    "build": {
        "directory": "/home/alex/src/tests/hello/build",
        "targets":[
             {"name":"all", "build_cmd":"make -j4 all"}
            ,{"name":"clean", "build_cmd":"make -j4 clean"}
            ,{"name":"hello", "build_cmd":"make -j4 hello"}
            ,{"name":"install", "build_cmd":"make install"}
        ], 
        "default_target": "all",
        "clean_target": "clean"
    }
}

So,  for each target, a “name” and a “build_cmd” is defined, and that’s it. One of the targets can be chosen to be the default target (which can be assigned a dedicated shortcut in the build plugin), and one can be chosen to be the “clean” target (again, which can be assigned a dedicated shortcut in the build plugin).

The screenshot below shows what you get when opening this project in Kate:

kate-project-plugin-manual1

Build plugin showing 4 targets from a .kateproject file

I mentioned above that both the “old” and the new build plugin can be supported within one .kateproject file. To do that, simply put both target definitions in the file, they don’t interfer:

{
    "name": "Hello",
    "files": [ { "filters": [ "*.cpp", "*.h"] } ],

    "build": {
        "directory": "/home/alex/src/tests/hello/build",
        "targets":[
             {"name":"all", "build_cmd":"make -j4 all"}
            ,{"name":"clean", "build_cmd":"make -j4 clean"}
            ,{"name":"hello", "build_cmd":"make -j4 hello"}
            ,{"name":"install", "build_cmd":"make install"}
        ], 
        "default_target": "all",
        "clean_target": "clean",

        "build": "make -j4 all",
        "clean": "make -j4 clean",
        "quick": "make -j4 install",
    }
}

Here, additionally to the 4 custom build targets, the three hardcoded targets “build”, “clean” and “quick” for the “old” build plugin are defined. When this project is opened in Kate 4.13 or newer, these three old entries are ignored, and only the four new entries are used. When this project is opened in Kat 4.12 or earlier, the four new targets are ignored and only the old ones are used.

In the case that an “old” .kateproject file is opened, which contains only the old entries, these are used, and the three entries are used to create three targets, as shown in the screenshot below:

Build plugin showing 3 targets from an "old" .kateproject file

Build plugin showing 3 targets from an “old” .kateproject file

 

Using the project plugin with CMake-based projects

Until now, the only way to create .kateproject files was to write them manually. If you are using Kate with C/C++ projects which are built using CMake, there are more news for you. CMake 3.0.0 will be released soon, and among others, it will contain a generator for, guess what: project files for the Kate project plugin!  With that, run CMake, select “Kate – Unix Makefiles” as generator, and there you go, everything set up ready to use for you, including all targets of the project available in the build plugin.

Below is a screenshot showing running cmake-gui on CMake itself:

Running cmake-gui on the CMake sources, showing the available generators

Running cmake-gui on the CMake sources, showing the available generators

As you can see, ninja is also supported.

Personally I still prefer Makefiles, especially for use with Kate projects. When using the Makefile generator, you get build targets for compiling every individual source file into an object file. This can save a lot of time when working on some source file and trying to get it to compile. Instead of starting to build everything, which involves dependency checking, and linking afterwards, you can simply just compile that one file (via the quick target select dialog of the updated build plugin), and if it failed, simply build the previous target again (there’s a shortcut for that) until it compiles, and then switch back to building everything (by building the default target).

In the screenshot below you can see Kate having loaded the project for CMake itself, listing the whole bunch of source files on the left, a long list of available build targets in the lower part, and the select-target-dialog on top, filtered already and the target for compiling cmMakefile.cxx is selected.

Kate showing a full project for CMake itself

Kate showing a full project for CMake itself

 

After trying to compile the file, Kate shows you which errors occurred, and using a dedicated shortcut (I set it to F9) it jumps to the line in the code:

Build plugin: jump to error works

Build plugin: jump to error works

As can be seen, there is the parsed error, the status tells you that there were errors when building the target “cmMakefile.cxx.o”, and if you want to try again, there’s a “Build again” button right there.

Now, how do you actually open CMake-generated projects in Kate? The .kateproject file is generated in the build tree, and usually you never have to open any files from the build tree in Kate.  But to open the project in Kate, you have to open any, at least one, file from the build tree (this will trigger searching the .kateproject file, which will point the project plugin to the source tree). To help with this, CMake additionally generates a file “ProjectName@buildDirectory.kateproject” in the top level build dir, right next to the generated .kateproject file. Open this file, and Kate loads the project.

 

Loading a project via opening the "dummy" ProjectName@BuildDir.kateproject file

Loading a project via opening the “dummy” ProjectName@BuildDir.kateproject file

This has been done in the screenshot above,  and already you’re ready to go !

Documentation

Last but not least, starting with 4.13, you can find documentation for the project json file in <PREFIX>/share/apps/apps/kate/plugins/project/kateproject.example.

 

So that’s it for now, I hope you find the new stuff useful. :-)

Coming in 4.13: Improvements in the build plugin

Kate comes with a build plugin, which supports running make, or ninja,  or actually any arbitrary command directly from within Kate. This is obvisouly  useful when using Kate as development editor, and this plugin has seen several improvements for the 4.13 release.

A small change, but for affected developers a major improvement, is that Kate  can now parse warning and error messages from the Intel compilers, icpc and icc.
So for those of you using icpc, Kate can now automatically jump to the line of code which caused the error. Actually you don’t have to wait for 4.13 for this, it is already available since 4.12.3.

Beside that, there are improvements which benefit all users of the build plugin. Let’s start with a screenshot, which already shows one of the major changes.

kate-targets

Build plugin showing the list of targets and the Build-menu

 

Up to 4.12, it was possible to create multiple “targets”, and each of these targets could contain a “Build” command, a “Clean” command and a “Quick” command.  As of 4.13, the build plugin is not limited anymore to these three commands. As can be seen in the screenshot, every “target set” can now  contain an arbitrary number of actual targets.
They are listed in a table widget. To add a target, click the green “plus”-button in the lower right. This will  append a target to the end of the list. It can be edited by simply double clicking it (or pressing F2 while keyboard focus is in the table).
To delete a target, click the “minus”-button right next to the “plus”
One of the targets can be marked as the “default” target. This will typically be  the target which runs “make all”. Additionally one target can be marked  as the “clean” target, this will typically be “make clean”. For these two special  targets separate keyboard shortcuts can be assigned, so they are always  quickly available.

A whole set of actions which can be bound to shortcuts can be seen here:

build-shortcuts

Configuring keyboard shortcuts for the build plugin

 

Now to the actually interesting part: building something.
There are multiple ways how to start building a target.

The default and the clean targets can be built directly using keyboard shortcuts, in the screenshot above I assigned F8 to the default target.
To build another than the default target, you can select the target you want in the table and then build it by clicking the blue “check”-button next to the “plus” and “minus” buttons.
For keyboard users, there is a quick-select dialog. It shows a list with the names of all targets, which can be filtered by typing part of the target name. That’s a really quick way to build any of the available targets. Here’s a screenshot:

kate-targets-quick-select

The Quick-select dialog for building a target

 

Once building has started, the output is displayed in the log view.
As can be seen, there is only one output tab left, where the “level of detail” can be adjusted using a slider. While building, the plugin automatically switches to the log display.

kate-build-log

Build plugin showing the output while building.

 

Also new, there is now a simple status display, which tells you which target is currently being built or was built previously.
Next to it, there is yet another way to start a build, the “Build again” button. Once some target has been built, using this button the same target can be built again. Oh, and there is now also a button to cancel a build, in case you forgot the assigned keyboard shortcut.

When building has finished, the output tab automatically switches to a parsed output mode, which lists the warning – and error messages. By double clicking on one of them or using the keyboard shortcut of your choice, I assigned F9,  you can jump directly to the line of code which caused the error.

kate-build-error

Build plugin showing the parsed errors after the build failed.

All that together, should make the build plugin even more useful than before.
Have fun compiling ! :-)

Alex

Kate Part (KF5): New Default Styles for better Color Schemes

Kate Part gained 17 new default styles in addition to the existing 14 default styles. These changes are available for Kate based on the KDE frameworks 5 initiative and currently live in ktexteditor.git module.

Default Styles are predefined font and color styles that are used by Kate Part’s syntax highlighting. For instance, Kate Part always had a default style for comments. Therewith, the comments in all syntax highlighting files look the same (by default, a gray color). Or keywords are by default always bold and black.

However, during the last years it became apparent that the list of 14 default styles were not always enough. Consequently, lots of syntax highlighting files defined their own hard-coded colors. For instance, doxygen comments were hard-coded in a dark blue color. The problem with hard-coded colors is that they do not adapt when changing the default styles. Hence, doxygen comments were barely readable on a dark color scheme.

Therefore, a discussion took place on kwrite-devel (thread 1, thread 2, thread 3) that ended in 17 new default styles and a categorization of these as follows (the new default styles are bold):

Category “Normal Text and Source Code

  • dsNormal: default for normal text and source code.
  • dsKeyword: Used for language keywords.
  • dsFunction: Used for function definitions and function calls.
  • dsVariable: Used for variables, if applicable. Example: $foo in PHP.
  • dsControlFlow: Used for control flow highlighting, e.g., if, then, else, return, continue.
  • dsOperator: Used for operators such as +, -, *, / and :: etc.
  • dsBuiltIn: Used for built-in language classes and functions, if applicable.
  • dsExtension: Used for extensions, such as Qt or boost.
  • dsPreprocessor: Used for preprocessor statements.
  • dsAttribute: Used for attributes of functions or objects, e.g. @override in Java, or __declspec(…) and __attribute__((…))in C/C++.

Category “Strings & Characters

  • dsChar: Used for a single character.
  • dsSpecialChar: Used for an escaped character in strings, e.g. “hello\n”.
  • dsString: Default for strings.
  • dsVerbatimString: Used for verbatim strings such as HERE docs.
  • dsSpecialString: Used for special strings such as regular expressions in ECMAScript or LaTeX math mode.
  • dsImport: Used for includes, imports, modules, or LaTeX packages

Category “Numbers, Types & Constants

  • dsDataType: Used for data types such as int, char, float etc.
  • dsDecVal: Used for decimal values.
  • dsBaseN: Used for numbers with base other than 10.
  • dsFloat: Used for floating point numbers.
  • dsConstant: Used for language constants, e.g. True, False, None in Python or nullptr in C/C++.

Category “Comments & Documentation

  • dsComment: Used for normal comments.
  • dsDocumentation: Used for comments that reflect API documentation, e.g., the default style for /** */ comments.
  • dsAnnotation: Used for annotations in comments, e.g. @param in Doxygen or JavaDoc.
  • dsCommentVar: Used to refer to variables in a comment, e.g. after @param <identifier> in Doxygen or JavaDoc.
  • dsRegionMarker: Used for region markers, typically defined by BEGIN/END.
  • dsInformation: Used for information, e.g. the keyword @note in Doxygen.
  • dsWarning: Used for warnings, e.g. the keyword @warning in Doxygen.
  • dsAlert: Used for comment specials such as TODO and WARNING in comments.

Category “Miscellaneous

  • dsOthers: Used for attributes that do not match any of the other default styles.
  • dsError: Used to indicate wrong syntax.

Existing Syntax Highlighting Files

If the new default styles are not used, syntax highlighting files are backwards compatible to Kate Part in KDE SC 4. However, the plan is to use the new default styles where applicable to avoid hard-coded colors. To this end, the kateversion attribute in the language element will be set to 5.0 (yes, Kate Part’s version changed from 3 to 5 to match KDE frameworks 5) to avoid loading incompatible syntax highlighting xml files in older Kate Part versions. Example:

<language name="C++" kateversion="5.0" [other attributes omitted]>

With the new default styles, the Default Styles tab looks as follows:
Default Styles in KF5

 

In comparison, the KDE 4.x version looks like this:
Default Styles in KDE 4

 

The new default style colors are not fixed yet, so improvements and additional color themes we can ship with Kate Part by default are a welcome addition!

A Note at 3rd Party Developers

There are other implementations (such as in Qt Creator or for Haskell). If you developers read this, we encourage you to add these default styles as well once Kate Part 5 is released (stable). Otherwise, the new syntax highlighting files may not be compatible.