Contributing

This page shows some hints about the coding conventions.

Coding advices

CutterCore class

This is the main class where every link with r2 is made. It is _unique_accross the whole process. To access it, simply call Core().

Example:

  1. Core()->getOffset();

Calling a radare2 command

There are two ways to call a radare2 command:

  • CutterCore::cmd() (Discouraged) Only use it for commands which yells no output
  • CutterCore::cmdj() To be used with json commands like cmdj("agj") or cmdj("aflj").

Generally, if one needs to retrieve information from a radare2 command, itis preferred to use the json API.

Example:

  1. QJsonArray array = Core()->cmdj("pdj 1 @ main").array();

Seek the current file

To modify radare2 seek use CutterCore::seek(const RVA offset). Thisis important because it will emit aCutterCore::seekChanged(RVA offset) signal. Never ever callcmd("s offset");

Example:

  1. Core()->seek(0x00C0FFEE);

Creating a widget

Make sure to connect the CutterCore::seekChanged(RVA offset) signalso your widget refreshes its output when radare2 seek is modified(switching to another function, etc.).

General coding guidelines

Coding style

In general, we follow the official Qt guidelines toformat the code. If in doubt, you can use AStyle2.06to format the code. The command line for formatting the code accordingto the style is:

  1. astyle --project=src/Cutter.astylerc src/filename.cpp

In contrast to the official guidelines of Qt, in Cutter we always use curly braces in conditional statements, even if the body of a conditional statement contains only one line.

  1. // Wrong
  2. if (address.isEmpty())
  3.    return false;
  4.  
  5. // Correct
  6. if (address.isEmpty()) {
  7.    return false;
  8. }
  9.  
  10. // Wrong
  11. for (int i = 0; i < 10; ++i)
  12.    qDebug("%i", i);
  13.  
  14. // Correct
  15. for (int i = 0; i < 10; ++i) {
  16.    qDebug("%i", i);
  17. }

Includes

Strive to include only required definitions inside header files.This will avoid triggering additional unnecessary compilations.

If you only need to know that a class exists but don’t need the prototype,you can declare the class like this:

  1. class MyClassThatExists;
  2.  
  3. /** ... **/
  4.  
  5. private:
  6.     MyClassThatExists *classInstance;

And then include the class header inside your .cpp so you can use that class.

If you need something in the source file (.cpp) that is not a class member,then add the include in the source file.

The includes must be ordered from local to global. That is, first includeany local header file (with doublequotes like #include “common/Helpers.h”.Then, after an empty newline, include Qt definitions like#include <QShortcut>.Finally, include the standard C++ headers you need.

Includes must be sorted by alphabetical order.

Docstrings

Our API reference is generated using Doxygen, so when it comes tofunction documentation, please use the following format:

  1. /**
  2.  * @brief Add a new param to the accumulator
  3.  */
  4. virtual void accumulate(RefreshDeferrerParams params) =0;

Loops

We use the C++11 foreach loop style, which means any “foreach” loop shouldlook like:

  1. for (QJsonValue value : importsArray) {
  2.     doSomething(value);
  3. }

nullptr

Please do not use 0 nor Q_NULLPTR, only use nullptr.

Example:

  1. QObject *object = nullptr;

Connecting signals

To connect a signal to a slot, this is the preferred syntax:

  1. connect(sender, &QObject::destroyed, this, &MyObject::objectDestroyed);

The main reason is that this syntax allows the use of lambda functions.

Functions documentation

You can find the classes documentation in the API Reference menu item.