cutter Documentation

This is the main class where every link with Rizin is made. It is *unique*
across the whole process. To access it, simply call ``Core()``.

Example:

.. code:: cpp

   Core()->getOffset();


Seek the Current File

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

Coding Style
------------

clang-format
~~~~~~~~~~~~

In general, we follow a slightly customized version of `the official Qt guidelines <https://wiki.qt.io/Qt_Coding_Style>`__ 
to format the code. Before sending a pull request, you will need to use `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`__ (version 8 or newer)
to format the code. The command line for formatting the code according
to the style is:

.. code:: bash

   clang-format -style=file -i src/filename.cpp

If your changes were done on many files across the codebase, you can use this oneliner to run ``clang-format`` on the entire ``src`` directory:

.. code:: bash

   find ./src -regex '.*\.\(cpp\|h\)' -exec clang-format -style=file -i {} \;

clang-tidy
~~~~~~~~~~

Beyond formatting, we use `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`__ (version 13 or newer) to catch potential style violations.

To run ``clang-tidy``, first configure your build to generate ``compile_commands.json`` and run the autogen tools:

.. code:: bash

    cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCUTTER_QT=6 -DCUTTER_USE_BUNDLED_RIZIN=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
     
    cmake --build build --target Cutter_autogen

Run ``clang-tidy`` on modified files relative to the latest commit

.. code:: bash

    git diff -U0 --no-color HEAD~1 | clang-tidy-diff.py -p1 -path build/

Similar to ``clang-format``, If your changes were done on many files across the codebase, you can use this oneliner to run ``clang-tidy`` on the entire 'src' directory. The following command excludes third-party and auto generated files:

.. code:: bash

    run-clang-tidy -p build ".*src/(?!(themes|bindings|fonts|img|translations|Cutter_autogen)).*\.(cpp|h)$"

``clang-tidy`` can also attempt to fix style violations using the ``-fix`` flag. However these may not always be perfect. Make sure to verify the fixes before opening a pull request:

.. code:: bash

    git diff -U0 --no-color HEAD~1 | clang-tidy-diff.py -fix -p1 -path build/

Python scripts
~~~~~~~~~~~~~~

If you don't want to run manual commands, cutter also provides scripts for running ``clang-format`` and ``clang-tidy`` in the ``scripts`` directory

.. code:: bash

    python scripts/clang-format.py -h
    usage: clang-format.py [-h] [-C CLANG_FORMAT] [-c] [-v] [-f FILE] [-d DIFF]

    Clang format the cutter project

    options:
      -h, --help            show this help message and exit
      -C, --clang-format CLANG_FORMAT
                            path of clang-format
      -c, --check           enable the check mode
      -v, --verbose         use verbose output
      -f, --file FILE       formats (or checks) only the given file
      -d, --diff DIFF       format all modified file related to branch

.. code:: bash
    
    usage: clang-tidy.py [-h] [-T RUN_CLANG_TIDY] [-p BUILD_PATH] [-j JOBS] [-r REGEX] [-i] [-q]

    clang-tidy regex wrapper

    options:
      -h, --help            show this help message and exit
      -T, --run-clang-tidy RUN_CLANG_TIDY
                            Path of run-clang-tidy binary
      -p, --build-path BUILD_PATH
                            Path to the build directory
      -j, --jobs JOBS       Number of parallel execution jobs
      -r, --regex REGEX     Regex pattern for filtering files
      -i, --fix             Apply fixes automatically
      -q, --quiet           Suppress configuration logs

Below are some of the low level coding conventions that we follow

Variables
~~~~~~~~~

Variable names start with a lowercase letter with each consecutive word starting with an uppercase letter. (**camelBack** case)

.. code:: cpp

   int Height             // Wrong
   string name_of_widget  // Wrong
       
   int height;            // Correct
   string nameOfWidget    // Correct

Avoid meaningless variable names

.. code:: cpp

   int a, b;              // Wrong
   string c;              // Wrong

   int height, width;     // Correct
   string nameOfThis;     // Correct
   Object obj;            // Also Correct

Only first letter of an acronym is uppercase 

.. code:: cpp

   CutterJsonWigdet cutterJSONWidget;    // Wrong

   CutterJsonWigdet cutterJsonWigdet;    // Correct

Variable names don't use leading/trailing underscores, including prefixes like m\_

.. code:: cpp

   class Example {
     private:
       int index_;     // Wrong
       int m_index;    // Wrong

       int index;      // Correct
   };

Global variables follow the same naming conventions

Anonymous Namespace

bool doSomething() {
       ...
       return true;
   }

Function names follow the same naming convention as `variables`_. (**camelBack** casing)

.. code:: cpp

   void do_something() {}     // Wrong

   void DoSomething() {}      // Wrong

   void doSomething() {}      // Correct

Unused parameters inside a function are omitted in the definition either by commenting out the parameter name or not writing the name at all.

Avoid using ``Q_UNUSED``

.. code:: cpp
   
    // Bad
    void doSomething(int one, int two) {
        Q_UNUSED(one)
        ...
    }

    // Good
    void doSomething(int /*one*/, int two) {
        ...    
    }

    // Good
    void doSomething(int, int two) {
        ...    
    }

Avoid the use of automatic name based connections. See `Connecting Qt Signals`_.

Classes
~~~~~~~~

First letter of each word is uppercased. (**CamelCase**)

.. code:: cpp

   class memory_dock_widget;   // Wrong
   class memoryDockWidget;     // Wrong

   class MemoryDockWidget;     // Correct

Only first letter of an acronym is uppercase 

.. code:: cpp

   class CutterJSONWidget    // Wrong

   class CutterJsonWidget    // Correct


Member variables follow the same naming conventions defined in `variables`_ that means no leading/trailing underscores or m\_ prefixes

Casting
~~~~~~~

Avoid the use of C style casts, prefer C++ casts (``static_cast``, ``const_cast`` ...)

Use ``qobject_cast`` for ``QObjects``

Smart Pointers

RegisterProfileDialog *ui;                        // Bad

std::unique_ptr ui;    // Good

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.

.. code:: cpp

   // Wrong
   if (address.isEmpty())
      return false;
   
   // Correct
   if (address.isEmpty()) {
      return false;
   }
   
   // Wrong
   for (int i = 0; i < 10; ++i)
      qDebug("%i", i);
   
   // Correct
   for (int i = 0; i < 10; ++i) {
      qDebug("%i", i);
   }

Loops
~~~~~

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

.. code:: cpp
   
   // Good - If a copy of each element is required
   for (auto import : importsArray) {
       doSomething(import);
   }
   
   // Good - If copy is not required
   for (auto &import : importsArray) {
       doSomething(import);
   }

   // Good - If no modification is required
   for (const auto &import : importsArray) {
       doSomething(import);
   }

auto
~~~~

Prefer the use of ``auto`` keyword when working with the following:

.. code:: cpp

   // Iterators
   auto it = myMap.find(key);
   for (const auto &import : importsArray) { ... }

   // Lambdas
   auto multiply = [](int a, int b) -> int { return a * b; };

   // Casting
   auto myFloat = static_cast<float>(myInt);
    
   // Initializing using new
   auto *item = new QListWidgetItem(text);

nullptr

std::unique_ptr<QObject> obj = nullptr;
 
// Note that this is just an example, unique_ptr constructor initializes the internal pointer to nullptr by default

Use one of the following methods for connecting signals to slots:

.. code:: cpp

   // typically you will make connection in the constructor to a member of current class
   connect(this->ui->button1, &QPushButton::clicked,
           this, &MyObject::buttonClicked); // Good

   // you can also connect directly other object slots
   connect(checkbox, &QCheckBox::toggled, widget, &QWidget::setEnabled); // Good

   // use lambda for passing extra arguments
   connect(button1, &QPushButton::clicked, this, [this](){ foo(getBar()); }); // Good

This syntax performs compile-time type checks and allows the use of lambda
functions. Other approaches for connecting signals can silently break at runtime.

Don't use the older macro based syntax or automatic name based connections.

.. code:: cpp

   // SIGNAL and SLOT macros
   connect(sender, SIGNAL(clicked), this, SLOT(buttonClicked)); // BAD

   // automatic name based connection
   slot:
      void on_actionNew_triggered(); // BAD

   // 3 argument connect without receiver object
   connect(sender, &SomeObject::signal, [this](){ this->foo(getBar()); }); // BAD


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:

.. code:: cpp

   class MyClassThatExists;

   /** ... **/

   private:
     std::unqiue_ptr<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 include
any local header file (with double quotes 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.

This is automatically handled by running ``clang-format``

Docstrings
~~~~~~~~~~

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

.. code:: cpp

   /**
    * @brief Add new parameters to the accumulator
    * @param params The parameters to add
    * @return True if the parameters were added, false otherwise
    */
   bool accumulate(RefreshDeferrerParams params) { ... };

Documenting every function is generally not required. Only document those functions whose purpose is not immediately understandable just by looking at the function name.

.. code:: cpp

    // No need for docs
    int getCount() const;

    // Should provide docs
    bool syncRemote();

It is preferred for classes to have documentation just above the definition, explaining their purpose.

.. code:: cpp

    /**
     * @brief A short description about SomeDialog
     */
    class SomeDialog {
        ...
    };

General Coding Advices
----------------------

Functions Documentation

Git submodules play a major part in Cutter. This, because Cutter is powered
by Rizin, its parent project, and it tries to stay up-to-date with its
recent version, which allows us to implement new features, and enjoy bug
fixes and performance improvements on Rizin. Often, we need to update
the Rizin submodule or the others, to push their most recent
version to Cutter.

You can view the list of all the submodules from the cutter root folder with:

.. code:: sh

   git config --file .gitmodules --get-regexp path | awk '{ print $2 }'

To update all the submodules at once, run these commands from the
cutter root folder:

.. code:: sh

   git submodule foreach git pull origin master
   git add submodule_name_1 submodule_name_2
   git commit -m "Update submodules"

More likely, you'll only need to update the *rizin* submodule.
In order to update one submodule individually, use the following code:

.. code:: sh

   cd rizin
   git checkout dev && git pull
   cd ..
   git add rizin
   git commit -m "Update rizin submodule"


Useful Resources (Qt Development)

- builtin help for Qt API
- builtin .ui file editor (Qt Designer - visual form editor)
- builtin helper for displaying Qt types in the debugger
- Viewing source files that are not directly part of the project (Rizin source code) is somewhat inconvenient.
- The simplest way of installing on non-Linux operating systems require login with Qt account

Project setup

To configure ``clang-format`` for formatting a file you will need to use the built-in Beautifier plugin. `Follow the instructions <https://doc.qt.io/qtcreator/creator-beautifier.html>`_ on Qt Creator's website to enable the plugin and configure it to run ``clang-format`` when saving a file. In the clang-format options page choose "Use predefined style: File".

Changing CMake configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Click on the "Projects" button on the left side of the screen and then select "Build". All the project CMake options are listed and can be edited there in a graphical editor.

Editing Qt .ui files
~~~~~~~~~~~~~~~~~~~~
Double-clicking a ``.ui`` file in a file list opens it inside a visual editor. If you want to make changes that are easier to do by editing ``.ui`` file as text - right-click the file and select :menuselection:`Open With --> Plain Text Editor`. Switching from visual form editor back to code editor mode will open the ``.ui`` file in read-only mode with the following warning "This file can only be edited in Design mode". To edit use the same steps as described before.

VS Code
-------
`VS Code <https://github.com/Microsoft/vscode>`_ is an open-source code editor made by Microsoft.

Pros and Cons
~~~~~~~~~~~~~

- A large number of plugins
- A good fallback mechanism for files that are not directly part of a project.

Recommended plugins
~~~~~~~~~~~~~~~~~~~
- `C/C++ <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools>`_ - The official C++ support plugin made by Microsoft
- `CMake Tools <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools>`_ - Provides CMake project integration. Originally developed by vector-of-bool and currently maintained by Microsoft.
- `CMake <https://marketplace.visualstudio.com/items?itemName=twxs.cmake>`_ - CMake language support when editing CMake files. Does not replace the previous CMake plugin. They provide non-overlapping functionality and should be used together.

Project setup
~~~~~~~~~~~~~
- :menuselection:`File --> Open Folder...` and select the folder in which you cloned Cutter
- Install the recommended plugins.
- Once the `CMake Tools` plugin is installed, in the corner you will see a popup asking you "Would you like to configure project 'cutter'? Source: CMake Tools (Extension)". Click Yes.
- In the kit selection popup, choose :guilabel:`[Unspecified]` unless you have more specific needs.
- If you initially dismissed the configuration window or didn't have the plugins installed yet - open command-palette using :kbd:`Ctrl-Shift-P` and select :guilabel:`Cmake: Configure`

Changing CMake configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After the first configuration :kbd:`Ctrl-Shift-P`/:guilabel:`CMake: Edit CMake Cache` opens a text editor with all CMake options. Cutter specific ones mostly start with "CUTTER".

.. _vscode-debug-setup:

Formatting using clang-format

Build and running commands are available in the status bar at the bottom and in the Command Palette menu (:kbd:`Ctrl-Shift-P`) named ``CMake: Build F7``, ``CMake: Run Without Debugging Shift+F5``, and ``CMake Debug Ctrl + F5``.
Shortcuts can be viewed in the :kbd:`Ctrl-Shift-P` menu. They don't match default VS Code ones since those depend on :file:`tasks.json``.

Running and debugging launches the executable without any arguments. Command-line arguments can be passed to the debug
executable by creating a ``.vscode/launch.json`` configuration. Read the `documentation <https://code.visualstudio.com/docs/cpp/launch-json-reference>`_  for more information. Instead of creating :file:`launch.json` manually it can be created from template: :kbd:`Ctrl-Shift-P`/:menuselection:`Debug: Select and Start Debugging --> Add configuration.. --> C,C++: (gdb) Launch`.

To setup gdb pretty printers for Qt types on Linux, download the scripts from `Kdevelop <https://github.com/KDE/kdevelop/tree/master/plugins/gdb/printers>`_. In the :file:`~/.gdbinit` file add the following code:


.. code-block:: python

    python
    import sys

    sys.path.insert(0, '/path/to/folder/with/pretty_printer_scripts')
    from qt import register_qt_printers
    register_qt_printers (None)

    end
    set print pretty 1


CLion
-----
`CLion <https://www.jetbrains.com/clion/>`_ is a C and C++ IDE from the popular software development tool maker - JetBrains.


Pros and Cons
~~~~~~~~~~~~~

- Medium amount of plugins, many first-party plugins made by JetBrains for their IntelliJ based IDE family
- There is no free version
- Takes some time to analyze the files after opening a project. Switching between .cpp and corresponding .h file may for the first time may take a few seconds.

Project setup
~~~~~~~~~~~~~
- Go to :menuselection:`File --> Open` and select the folder in which you cloned Cutter
- Open :file:`cutter/CMakeLists.txt` using the project file list on the left side of the screen
- A yellow bar with a message :guilabel:`CMake project is not loaded` should appear, click :guilabel:`Load CMake project`

Changing CMake configuration

Clion provides you with an easy way to format files with ``clang-format``. Follow the `documentation <https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html>`_ on their website to learn how to enable formatting with ``clang-format``.

Building, Running, Debugging
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Follow the `Clion documentation <https://www.jetbrains.com/help/clion/qt-tutorial.html#debug-renderers>`_ for how to configure Qt type debugger renderers. If you are using the MSVC toolchain
it can use :file:`qt5.natvis`. In rest of the cases you can use ``.gdbinit`` or ``..ldbinit`` based approach similar to one described for :ref:`VSCode setup<vscode-debug-setup>`

Editing Qt .ui files
~~~~~~~~~~~~~~~~~~~~
Default CLion behavior for opening .ui files is `somewhat buggy <https://youtrack.jetbrains.com/issue/CPP-17197>`_. Double-clicking the file does nothing, but it can be opened by dragging it to the text editor side.
This can be somewhat improved by changing `file association <https://www.jetbrains.com/help/clion/creating-and-registering-file-types.html>`_. Open :menuselection:`File --> Settings --> Editor --> File Types` and change type association of \*.ui files from :guilabel:`Qt UI Designer Form` to either "XML" or :guilabel:`Files Opened in Associated Applications`.
The first one will open it within CLion as an XML file and the second will use the operating system configuration.

Visual Studio
-------------
Visual Studio Community edition is available for free and can be used for contributing to open source projects.

It is recommended to use the latest Visual Studio version 2019 because it has the best CMake integration.
Older VS versions can be used but CMake integration isn't as good. With those, it might be better to generate Visual Studio
project from CMake project using the command-line or :command:`cmake-gui` and opening the generated Visual Studio project instead of opening the
CMake project directly.

Visual Studio supports many different languages and use-cases. Full installation takes a lot of space. To keep the size minimal during installation
select only component called "Desktop development with C++". Don't worry too much about missing something.
Additional components can be later added or removed through the VS installer which also serves as an updater and package manager for Visual Studio components.

Pros and Cons
~~~~~~~~~~~~~
- good debugger
- medium amount of plugins
- completely closed source
- Windows only

Project setup
~~~~~~~~~~~~~
- Open folder in which you cloned Cutter source using Visual Studio
- Open CMake settings configurator using either :menuselection:`Project --> CMake Settings` or by clicking :guilabel:`Open the CMake Settings Editor` in the overview page.
- Check options that you want Cutter to be built with, or leave it as-is for the default options.
- If you are using vcpkg, Visual Studio should detect it automatically. The list of CMake options in the configurator should have some referring to vcpkg. If they are not there, specify the path to vcpkg toolchain file in the :guilabel:`CMake toolchain file` field.
- If you are not using vcpkg, configure the path to Qt as mentioned in :ref:`windows CMake instructions`. You can specify the CMake flag in :guilabel:`CMake command arguments:` field.
- To Ensure that VS debugger can display Qt types in a readable way, it is recommended to install `Qt Visual Studio Tools <https://marketplace.visualstudio.com/items?itemName=TheQtCompany.QtVisualStudioTools2019>`_ plugin. It will create a :file:`Documents/Visual Studio 2019/Visualizers/qt6.natvis` file. Once :file:`qt6.natvis` has been created you can uninstall the plugin.

Changing CMake configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Open :menuselection:`Project --> CMake Settings`. CMake options can be modified either in graphical table editor, as a command-line flag or by switching to the JSON view.

Formatting using clang-format

By default Visual Studio will open ``.ui`` files as XML text documents. You can configure to open it using Qt Designer by right-clicking and selecting :guilabel:`Open With...`.

There is a  Qt plugin for Visual Studio from Qt. It isn't very useful for Cutter development since it is aimed more at helping with Qt integration into Visual Studio projects.
It doesn't do much for CMake based projects. The biggest benefit is that it automatically installs :file:`qt6.natvis` file for more readable displaying of Qt types in the debugger.

---

## File: docs/source/contributing/code/release-procedure.rst

Release Procedure
=================

1. Update translations submodule `<https://github.com/rizinorg/cutter-translations>`_
    1. The latest archive from Crowdin should already be in the repository, if not make sure to merge any automated Pull Request from Crowdin (e.g. https://github.com/rizinorg/cutter-translations/pull/9)
    2. Update submodule in cutter
2. Merge the current state of dev into stable. This can happen even earlier in order to feature-freeze the release while keeping development on dev alive. The rizin submodule on stable should point to a commit of stable in rizin and dev to a commit in dev.
3. Lock rzghidra and rzdec versions downloaded by packaging scripts. Specify a tag or commit hash.
4. Update version
    #. appveyor.yml
    #. docs/sourc/conf.py
    #. docs/source/index.rst
    #. CMakeLists.txt
    #. Cutter.appdata.xml
    #. To be safe, search the code base for the previous version number.
5. Create a tag for the release candidate. For example, for the `v1.11.0` release you'd do something like this:
    #. ``git tag v1.11.0-rc1``
    #. ``git tag push origin v1.11.0-rc1``
6. Create a GitHub release, mark it as pre-release save draft, set the tag to v1.11.0-rc1
7. Wait for packages to build
8. On all operating systems do the `Basic testing procedure`_ to ensure nothing badly broken.
9. If any major problems are found, open an issue and fix them in dev and cherry pick into release branch. If the amount of changes is sufficiently large repeat from step 3. increasing rc number by one.
10. Update version to 1.11.0
11. Create tag
12. Create release
    * Fill the release notes in the Release description. Preparing release notes can begin earlier. Compare current dev branch against previous release to find all the changes. Choose the most important ones. Don't duplicate the commit log. Release notes should be a summary for people who don't want to read whole commit log. Group related changes together under titles such as "New features", "Bug Fixes", "Decompiler", "Rizin" and similar.
13. Prepare announcement tweets and messages to send in the Telegram group, reddit, and others.
14. Close milestone if there was one



Bugfix Release
--------------
The process for bugfix release is similar no normal release procedure described above with some differences.

* Cherry pick required bugfixes from dev into the stable.
* Increase the third version number x.y.n into x.y.(n+1) .


Basic testing procedure
-----------------------

This isn't intended as exhaustive testing process, just some simple steps to make sure nothing is badly broken.
If it makes sense repeat the step multiple times at different offsets and click around increase the chance of noticing common problems that doesn't happen 100% of time.

* Open a simple executable like ``/bin/ls`` or ``calc.exe``
* Make sure that the upgraded layout isn't completely broken
* The Disassembly widget shows proper disassembly.
* Bundled plugins work
   * Open decompiler and select ghidra, it shows some C code at least for some functions
   * Open rzdec in decompiler widget, make sure it shows code
* Test that sample python plugin works
* Try debugger
   * Insert breakpoint in main
   * Start debugging
   * Go to main using function widget, make sure relocation was done correctly and you see code instead of unmapped memory and breakpoint is where you placed
   * Click continue until you hit breakpoint in main
* Delete cutter settings file, and test that clean start works and layout isn't broken

---

## File: docs/source/contributing/docs/building-docs.rst

Building docs
=======================

This page explains the steps that are needed to build Cutter's documentation.

Requirements
------------

You will need:

* doxygen
* python3
* pip3

  * sphinx
  * breathe
  * recommonmark

On Debian-based Linux distributions, the packages above can be installed with the following command.

.. code:: sh

   sudo apt install make doxygen python3-pip doxygen
   sudo pip3 install sphinx breathe recommonmark

Then, you can build the documentation with the following commands:

.. code:: sh

   cd cutter/docs/
   make html

.. tip::

   If you do not need API documentation, type ``make quick`` instead of ``make html``.
   
You can find the generated html files at ``cutter/docs/build``. Open ``cutter/docs/build/html/index.html`` with your browser to visit the index file of your local copy of the documentation.

---

## File: docs/source/contributing/docs/getting-started.rst

Contributing documentation to Cutter
====================================

If you reached this place you were probably looking to help and improve Cutter's documentation - Fantastic, welcome aboard!

As many other young projects, Cutter has a problem - it lacks comprehensive documentation and written content. Thankfully, contributing to Cutter's documentation doesn’t require you to have a deep knowledge about the internals of the project. Writing, reviewing, and editing the documentation are great ways to learn about Cutter.

Don’t like the way something reads? Discover some information that wasn’t documented? Your pull request will be gleefully embraced.

.. note::
   The documentation of Cutter is written using `Sphinx and reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_. The syntax is quite straight forward and very similar to Markdown. In the future, we hope to move completely to Markdown as it is more popular.


How can you help?
-----------------

The following sections suggest ways you can contribute to Cutter's documentation. The list isn't complete as the possibilities are limitless.

The source for this documentation is available in the `docs directory <https://github.com/rizinorg/cutter/tree/dev/docs>`_ on Cutter's repository. This source can be generated according to the steps described in the :ref:`building docs page<contributing/docs/building-docs:Building docs>`. When the docs are updated, they are generated and pushed directly to the website at <https://cutter.re/docs>. The source for the website and blog are available on the `cutter.re's repository <https://github.com/rizinorg/cutter.re>`_ and are served from the ``gh-pages`` branch.

.. tip::
  Document what you wished to see. If you are a user of Cutter, try to think what things you would want to see documented when you started using the project. Sometimes, the best contributions are coming from your own needs.

User documentation
^^^^^^^^^^^^^^^^^^

The documentation for users describes how to use Cutter and what the different features in Cutter do. The possibilities for contributing are endless since there are so many features that weren't even described on our docs yet. To contribute to our user documentation, all you need to do is pick a subject, widget, or functionality and document it. Describe the different visual components, how to use them, and what this feature even does.

Common Errors and Troubleshooting
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As our community gets bigger, more and more people are using, installing or building Cutter on different setups. Naturally, different environments might cause different issues. The :ref:`common issues` section in our docs aims to go over the most popular issues that you might face while using Cutter and the :ref:`building errors troubleshooting` section goes over common errors that you might face while building Cutter from sources. These docs sections also explain what causes these issues and how to solve them.

If you know of such a common issue, whether you faced it yourself or noticed it on our community chats, it will be very helpful if you could document it and possible solutions for it.


Developers documentation
^^^^^^^^^^^^^^^^^^^^^^^^

The documentation for Cutter developers aims to instruct new contributors on how to get started with developing to Cutter's codebase. It also describes best practices and development guidelines for all developers in the project. Think you have something to add to the developers' docs? We would love you to contribute.

API documentation
^^^^^^^^^^^^^^^^^

The documentation for Cutter's API is an important reference for Cutter developers as well as Plugin developers. It thoroughly describes for developers how some functions and features work. While some of the functions are thoroughly documented, most of them aren't. Any help with improving these documentations will be blessed.


Blog posts
^^^^^^^^^^

We would love to see people writing and sharing their experiences with Cutter. Whether you are solving CTF challenges with Cutter, analyzing malware, finding vulnerabilities, or working on personal projects - we would love to see these published. If you have a personal blog, we would be proud to share and retweet your Cutter-related publications on our profiles, bringing you more engagement and followers. If you don't have a personal blog, we would love to host your publication on our community blog over at https://cutter.re/blog.

---

## File: docs/source/contributing/plugins/getting-started.rst

Getting Started with Python Plugins
===================================

This article provides a step-by-step guide on how to write a simple Python plugin for Cutter.

Create a python file, called ``myplugin.py`` for example, and add the following contents:

.. code-block:: python

   import cutter

   class MyCutterPlugin(cutter.CutterPlugin):
       name = "My Plugin"
       description = "This plugin does awesome things!"
       version = "1.0"
       author = "1337 h4x0r"

       def setupPlugin(self):
           pass

       def setupInterface(self, main):
           pass

       def terminate(self):
           pass

   def create_cutter_plugin():
       return MyCutterPlugin()

This is the most basic code that makes up a plugin.
Python plugins in Cutter are regular Python modules that are imported automatically on startup.
In order to load the plugin, Cutter will call the function ``create_cutter_plugin()`` located
in the root of the module and expects it to return an instance of ``cutter.CutterPlugin``.
Normally, you shouldn't have to do anything else in this function.

.. note::
   The Cutter API is exposed through the ``cutter`` module.
   This consists mostly of direct bindings of the original C++ classes, generated with Shiboken6.
   For more detail about this API, see the Cutter C++ code or :ref:`api`.

The ``CutterPlugin`` subclass contains some meta-info and two callback methods:

* ``setupPlugin()`` is called right after the plugin is loaded and can be used to initialize the plugin itself.
* ``setupInterface()`` is called with the instance of MainWindow as an argument and should create and register any UI components.
* ``terminate()`` is called on shutdown and should clean up any resources used by the plugin.

Copy this file into the ``python`` subdirectory located under the plugins directory of Cutter and start the application.
You should see an entry for your plugin in the list under Edit -> Preferences -> Plugins.
Here, the absolute path to the plugins directory is shown too if you are unsure where to put your plugin:

.. image:: preferences-plugins.png

.. note::
   As mentioned, plugins are Python modules. This means, instead of only a single .py file, you can also
   use a directory containing multiple python files and an ``__init__.py`` file that defines or imports the
   ``create_cutter_plugin()`` function.

.. note::
   If you are working on a Unix-like system, instead of copying, you can also symlink your plugin into the plugins
   directory, which lets you store the plugin somewhere else without having to copy the files over and over again.


Creating a Widget
-----------------

Next, we are going to add a simple dock widget. Extend the code as follows:

.. code-block:: python

   import cutter

   from PySide6.QtWidgets import QAction, QLabel

   class MyDockWidget(cutter.CutterDockWidget):
       def __init__(self, parent, action):
           super(MyDockWidget, self).__init__(parent, action)
           self.setObjectName("MyDockWidget")
           self.setWindowTitle("My cool DockWidget")

           label = QLabel(self)
           self.setWidget(label)
           label.setText("Hello World")

   class MyCutterPlugin(cutter.CutterPlugin):
       # ...

       def setupInterface(self, main):
           action = QAction("My Plugin", main)
           action.setCheckable(True)
           widget = MyDockWidget(main, action)
           main.addPluginDockWidget(widget, action)

   # ...

We are subclassing ``cutter.CutterDockWidget``, which is the base class for all dock widgets in Cutter,
and adding a label to it.

.. note::
   You can access the whole Qt6 API from Python, which is exposed by PySide6. For more information about this, refer to the
   Documentation of `Qt <https://doc.qt.io/qt-6/reference-overview.html>`_ and `PySide6 <https://wiki.qt.io/Qt_for_Python>`_.

.. note::
   Main cutter packages are now using QT6, but Qt5 builds are still provided for compatibilty with older OS versions. If you
   want your plugin to support both, Qt usage process is a bit more complicated.

In our ``setupInterface()`` method, we create an instance of our dock widget and an action to be
added to the menu for showing and hiding the widget.
MainWindow provides a helper method called ``addPluginDockWidget()`` to easily register these.

When running Cutter now, you should see the widget:

.. image:: mydockwidget.png

... as well as the action:

.. image:: mydockwidget-action.png


Fetching Data
-------------

Next, we want to show some actual data from the binary in our widget.
As an example, we will display the instruction and instruction size at the current position.
Extend the code as follows:

.. code-block:: python

   # ...

   class MyDockWidget(cutter.CutterDockWidget):
       def __init__(self, parent, action):
           # ...

           label = QLabel(self)
           self.setWidget(label)

           disasm = cutter.cmd("pd 1").strip()

           instruction = cutter.cmdj("pdj 1")
           size = instruction[0]["size"]

           label.setText("Current disassembly:\n{}\nwith size {}".format(disasm, size))

   # ...

We can access the data by calling Rizin commands and utilizing their output.
This is done by using the two functions ``cmd()`` and ``cmdj()``, which behave just as they
do in `rz-pipe <https://book.rizin.re/scripting/rz-pipe.html>`_.

Many commands in Rizin can be suffixed with a ``j`` to return JSON output.
``cmdj()`` will automatically deserialize the JSON into python dicts and lists, so the
information can be easily accessed.

.. warning::
   When fetching data that is not meant to be used only as readable text, **always** use the JSON variant of a command!
   Regular command output is not meant to be parsed and is subject to change at any time, which will break your code.

In our case, we use the two commands ``pd`` (Print Disassembly) and ``pdj`` (Print Disassembly as JSON)
with a parameter of 1 to fetch a single line of disassembly.

.. note::
   To try out commands, you can use the Console widget in Cutter. Almost all commands support a ``?`` suffix, like in
   ``pd?``, to show help and available sub-commands.
   To get a general overview, enter a single ``?``.

The result will look like the following:

.. image:: disasm-static.png

Of course, since we only fetch the info once during the creation of the widget, the content never updates.
We are going to change that in the next section.


Reacting to Events
------------------

We want to update the content of our widget on every seek.
This can be done like the following:

.. code-block:: python

   # ...

   from PySide6.QtCore import QObject, SIGNAL

   # ...

   class MyDockWidget(cutter.CutterDockWidget):
       def __init__(self, parent, action):
           # ...

           self._label = QLabel(self)
           self.setWidget(self._label)

           QObject.connect(cutter.core(), SIGNAL("seekChanged(RVA)"), self.update_contents)

       def update_contents(self):
           disasm = cutter.cmd("pd 1").strip()

           instruction = cutter.cmdj("pdj 1")
           size = instruction[0]["size"]

           self._label.setText("Current disassembly:\n{}\nwith size {}".format(disasm, size))


First, we move the update code to a separate method.
Then we call ``cutter.core()``, which returns the global instance of ``CutterCore``.
This class provides the Qt signal ``seekChanged(RVA)``, which is emitted every time the current seek changes.
We can simply connect this signal to our method and our widget will update as we expect it to:

.. image:: disasm-dynamic.png

For more information about Qt signals and slots, refer to `<https://doc.qt.io/qt-6/signalsandslots.html>`_.

Full Code
---------

.. code-block:: python

   import cutter

   from PySide6.QtCore import QObject, SIGNAL
   from PySide6.QtWidgets import QLabel
   from PySide6.QtGui import QAction

   class MyDockWidget(cutter.CutterDockWidget):
       def __init__(self, parent, action):
           super(MyDockWidget, self).__init__(parent, action)
           self.setObjectName("MyDockWidget")
           self.setWindowTitle("My cool DockWidget")

           self._label = QLabel(self)
           self.setWidget(self._label)

           QObject.connect(cutter.core(), SIGNAL("seekChanged(RVA)"), self.update_contents)

       def update_contents(self):
           disasm = cutter.cmd("pd 1").strip()

           instruction = cutter.cmdj("pdj 1")
           size = instruction[0]["size"]

           self._label.setText("Current disassembly:\n{}\nwith size {}".format(disasm, size))


   class MyCutterPlugin(cutter.CutterPlugin):
       name = "My Plugin"
       description = "This plugin does awesome things!"
       version = "1.0"
       author = "1337 h4x0r"

       def setupPlugin(self):
           pass

       def setupInterface(self, main):
           action = QAction("My Plugin", main)
           action.setCheckable(True)
           widget = MyDockWidget(main, action)
           main.addPluginDockWidget(widget, action)

       def terminate(self):
           pass

   def create_cutter_plugin():
       return MyCutterPlugin()

---

## File: docs/source/contributing/code.rst

Developer Documentation
=======================

.. note::
   New to Cutter development? Check out our :doc:`tutorial for new developers <code/getting-started>`.

.. toctree::
   :maxdepth: 2
   :glob:

   Getting Started <code/getting-started>
   code/development-guidelines
   code/ide-setup
   code/*

## 2. Official Technical Reference & Guides (rizinorg/website)

# Rizin Website

## Local Installation

1. Install or download the **Extended** version of [Hugo](https://gohugo.io/getting-started/installing/)
   - Newer version of Hugo might not work. The version used here is [v0.111.3](https://github.com/gohugoio/hugo/releases/tag/v0.111.3)
2. Clone this repository and its submodules:
    ```
    $ git clone --recurse-submodules https://github.com/rizinorg/website
    ```
3. Enter the cloned repository and "serve" the website using Hugo
    ```bash
    $ cd website
    # Check hugo version
    $ hugo version
    hugo v0.111.3-5d4eb5154e1fed125ca8e9b5a0315c4180dab192+extended linux/amd64 BuildDate=2023-03-12T11:40:50Z VendorInfo=gohugoio
    $ hugo serve
    ```

## File tree description

```
.
├── assets
│  └── css
│     └── custom
│        └── rizin.css           <--- Edit CSS here
├── config.yml                   <--- Hugo Config for the website
├── content                      <--- Markdown files for single pages
│  ├── archives.md
│  ├── code-of-conduct.md        
│  ├── organization.md
│  ├── posts                     <--- Markdown blog posts
│  │  └── example
│  │     └── index.md
│  └── teams                     <--- Special folder for team pages
│     ├── community.md
│     ├── core.md
│     ├── Distributions and Packaging.md
│     ├── package-manager-and-plugins.md
│     └── . . .
├── data
│  └── teams.json                <--- JSON with teams data and descriptions
├── layouts                      <--- Special layouts
│  ├── _default
│  │  ├── organization.html
│  │  └── team.html
│  ├── index.html                <--- Main page
│  └── partials                  <--- override theme or introduce new partials
│     ├── extend_head.html
│     ├── header.html
│     └── main-page.html
├── static
│  └── images
│     └── rizin.svg
|
|
└── themes                       <--- The base theme. Don't touch files in here
   └── hugo-PaperMod

```

## Demo GIF

When showing Rizin demos the GIF are generated with
[Terminalizer](https://www.terminalizer.com/) by using this [config
file](https://github.com/rizinorg/website/blob/main/.terminalizer-config).