Skip to content

Latest commit

 

History

History
192 lines (154 loc) · 9.79 KB

readme.org

File metadata and controls

192 lines (154 loc) · 9.79 KB
Raw

Information

Malinka is a project management Emacs package for C/C++

It acts as a glue between different C/C++ packages to provide them with the right data for a project. All the data are organized and can be configured on a per project basis. The packages that malinka can work with are:

Rtags

Rtags help the user jump around the code easily and provide integration with many clang utilities like Clang fixits. The main functionality that malinka provides is to properly populate and communicate the compiler commands to the rtags daemons depending on the project you are working on.

If you have not installed rtags yet, visit their github page and read more information about how you can acquire and use rtags. Alternatively if you used el-get to get malinka rtags should have been downloaded and built as a dependency

Flycheck

Optionally and if you also have flycheck with the clang syntax-checker activated, malinka will communicate to flycheck’s clang syntax checker the appropriate cpp-defines and include-paths so that flycheck can do its syntax checking.

Projectile

If you are using projectile then malinka can provide projectile with the compile and test commands to build and test your project respectively. Projectile also helps with the detection of root directory for projects.

Irony

If you are using irony mode malinka can then provide the json compilation database for your project that will be indexed by the irony server

Example Setup

Working with malinka requires that you define your project somewhere in your emacs file using (malinka-define-project). 
(require 'malinka)

(add-hook 'c-mode-common-hook 'malinka-mode)

(malinka-define-project
 :name "ethereum"
 :root-directory "/home/lefteris/ew/cpp-ethereum"
 :build-directory "/home/lefteris/ew/cpp-ethereum/build"
 :configure-cmd "cmake .. -DCMAKE_BUILD_TYPE=Debug -DHEADLESS=1"
 :compile-cmd "make -j4"
 :test-cmd "./test/testeth")

In the above example we can see malinka’s initialization and a sample definition of a project. You need to hook malinka-mode to c/c++ mode so that all malinka functionality can operate only on the loading of those type of buffers.

Let’s look now at the arguments of a project’s definition one by one.

name

This is the name of the project. This is how malinka will refer to your project everywhere. Must be unique.

root-directory

This is the root directory of the project.

build-directory

This is the directory where the build-cmd and compile-cmd will be executed in.

configure-cmd

This is the command to configure the project for malinka. This is what malinka will use to create the json compilation database. There are 2 different ways to achieve this and depends on the type of build system you use to build your project.

cmake > 2.85

If malinka detects you are using cmake with version greater than 2.85 then it will use cmake to create the compilation database in the build directory.

all others

For all other cases, simple makefiles, scons, waf e.t.c. you have to provide the build command here making sure that it will provide visible compile output. You can simply add the --dry-run option in most build systems as this command should be used just to create the compilation database. The output will be parsed by malinka and the compilation database will be created.

compile-db-cmd

This command instructs malinka in what way to generate the compilation database. compile-db-cmd takes precedence over configure-cmd. When configure-cmd is not enough to generate a correct compilation database, you should use compile-db-cmd. One example is when using ninja or bear to generate a compilation database. You should provide a command that could always generate a compilation database correctly. For example, you may add bear make -B to make sure it always generate a compilation database whenever current project has been already built.

compile-cmd

This is the command to compile the whole project. This is what will be given to projectile’s projectile-compile-project to compile your project with your chosen keybinding. Default is: C-c p c

test-cmd

This is the command to test the project. This is what will be given to projectile’s projectile-test-project to test your project with your chosen keybinding. Default is: C-c p P. It is an optional project attribute.

run-cmd

This is the command to run the executable or anything else generated by the project. It is bound to projectile-run-command and the default keybinding is C-c p u. This is an optional project attribute.

Usage

As shown in the example setup section the basic configuration that needs to exist in order to use malinka is to define your projects using (malinka-define-project) Following that the way to interact with the defined projects is via the following interactive API:

  • (malinka-project-configure name given-root-dir)

    You will be prompted with a list of the known projects and you will have to select the one you need to configure. Basically this command will create the compilation database for your project and feed the data to the packages you use. Depending on project size this may take quite a bit of time.

    The given-root-dir is optional and will only be asked if you failed to provide one in the project definition.

  • (malinka-project-select name given-root-dir)

    You will be prompted with a list of the known projects and you will have to select the one you need to select. Basically this command will search for the compilation database in the selected project, read it and feed the data to the packages you are using.

    The given-root-dir is optional and will only be asked if you failed to provide one in the project definition.

Operation

Malinka will attempt to feed data to all the C/C++ relevant packages that it can detect while a buffer of a malinka project is currently visited.

Idle Check

If `malinka-enable-idle-project-check’ is non-nil then at the specified interval of `malinka-idle-project-check-seconds’ the visited buffer’s file will be checked against all the known malinka projects.

If it is found to be under a project’s root then that project is considered the current project and is selected by malinka. Selection basically means feeding the appropriate data to each of the other C/C++ packages.

Customization

As a user you have ample customization choices when using malinka. These are:

  • malinka-completion-system: As a user you have a choice of the completion system to choose when selecting a defined project. As inspired by flycheck’s customization there are currently two choices offered:
    • IDO: the built-in completion system with fuzzy searching. Powerful though it is, one can really improve it by using flx-ido.
    • Completing Read: The very simple and not fancy emacs built-in completion system. Is the default.
  • malinka-ignored-directories: A list of directories to ignore for file searching
  • malinka-supported-compilers: A list of compiler executable names that are recognized and supported by malinka.
  • malinka-supported-file-types: File extensions that malinka will treat as related source and header files.
  • malinka-supported-header-types: File extensions that malinka will treat as related header files.
  • malinka-idle-project-check-seconds: The idle time in seconds to wait until we perform a project idle check. Can be nil or 0 to disable idle project checks.
  • malinka-mode-line: The string to show on the modeline when malinka minor mode is active
  • malinka-print-info?: If true malinka will be printing some info messages of the actions it takes.
  • malinka-print-warning?: If true malinka will be printing warning messages in case things go wrong but can be taken care of
  • malinka-print-debug?: If true malinka will be printing a lot of DEBUG messages. Only useful for debugging
  • malinka-print-xdebug?: If true malinka will be printing extreme DEBUG messages. Only useful for debugging. Warning: This WILL spam the Messages buffer

Issues

If you have problems, bugs or feature requests feel free to open an issue in github and I will take a look at it when I find the time.

Common Issues

  • Can’t index file

    To get a view of the connection between Emacs and the rtags daemon you can always check the *rdm* buffer. There you can see after a M-x malinka-project-configure if the files are indexed properly.

    If for some reason a file can’t be indexed and in the *rdm* buffer you get something like below:

    Failed to make location from [filename:line:column]

    Then I would suggest removing the rtags cache kept under ~/.rtags by default and then redoing a M-x malinka-project-configure. Also killing the rdm daemon is a good idea.

Contributions

All contributions are welcome. If you would like to help you can open a pull request with your suggested contribution.

Running tests

cask
make compile
make lint
make test

Styling

The malinka code is written in elisp and for styling we use the [elisp-formatter](https://www.emacswiki.org/emacs/ElispFormat) tool. If you make any contributions please make sure they adhere to the elisp style rules by also running it on your Pull Request.