ch0ic3/cutter
1
0
Fork 0
mirror of https://github.com/rizinorg/cutter.git synced 2024-12-18 10:56:11 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Moved old markdown files to rst

Browse Source
This commit is contained in:
xarkes 2019-02-26 18:49:41 +01:00
parent 2b85d7bfaf
commit b2f43ca0ee
13 changed files with 458 additions and 385 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs-ref/source/api.rst
View File

@ -1,4 +1,4 @@
API
API Reference
===========
.. toctree::

171
docs-ref/source/building.rst Normal file
View File

@ -0,0 +1,171 @@
Building
========
First you must get the source of Cutter by cloning the repository:
::
git clone --recurse-submodules https://github.com/radareorg/cutter
The “official” way to build Cutter is by using qmake, but there are two
alternatives – cmake and meson.
In any case, there are obviously some requirements: \* Radare2 installed
from submodule \* Qt 5.9 or above \* Python3.6
**Before compiling, note that we also provide binaries available for
windows/linux/MacOS
X**\ `here <https://github.com/radareorg/cutter/releases>`__\ **.**
--------------
Building options
----------------
Note that there are two major building options available: \*
``CUTTER_ENABLE_JUPYTER`` is used to compile Cutter with bundled Python
and Jupyter module \* ``CUTTER_ENABLE_QTWEBENGINE`` is used to compile
Cutter with bundled QtWebEngine (to ease jupyter console usage)
--------------
Building with Qmake
-------------------
Compiling on Linux / macOS
^^^^^^^^^^^^^^^^^^^^^^^^^^
The easy way is to simply run ``./build.sh`` from the root directory,
and let the magic happen. The script will use qmake to build Cutter.
If you want to manually use qmake, follow this steps:
.. code:: sh
mkdir build; cd build
qmake ../src/Cutter.pro
make
cd ..
Additional steps for macOS
^^^^^^^^^^^^^^^^^^^^^^^^^^
On macOS you will also have to copy the launcher bash script:
.. code:: sh
mv Cutter.app/Contents/MacOS/Cutter Cutter.app/Contents/MacOS/Cutter.bin
cp ../src/macos/Cutter Cutter.app/Contents/MacOS/Cutter && chmod +x Cutter.app/Contents/MacOS/Cutter
--------------
Building with Cmake
-------------------
Requirements
~~~~~~~~~~~~
- CMake >= 3.1
Building on Linux
~~~~~~~~~~~~~~~~~
The root for CMake is in src/. In-source builds are **not allowed**, so
you **must** run CMake from a separate directory:
::
cd src
mkdir build
cd build
cmake ..
If all went well, you should now have a working Makefile in your build
directory:
::
make
--------------
Building on Windows
-------------------
Alternatively, on Windows you can run something like this (depending on
your Cmake installation)
.. code:: batch
set CMAKE_PREFIX_PATH=c:\Qt\qt-5.6.2-msvc2013-x86\5.6\msvc2013\lib\cmake
cd src
mkdir build
cd build
cmake-gui ..
Click ``Configure`` and select ``Visual Studio 14 2015`` from the list.
After configuration is done, click ``Generate`` and you can open
``Cutter.sln`` to compile the code as usual.
Troubleshooting
---------------
Cmake: qt development package not found
Depending on how Qt installed (Distribution packages or using the Qt
installer application), CMake may not be able to find it by itself if it
is not in a common place. If that is the case, double check that the
correct Qt version is installed. Locate its prefix (a directory
containing bin/, lib/, include/, etc.) and specify it to CMake using
``CMAKE_PREFIX_PATH`` in the above process, e.g.:
::
rm CMakeCache.txt # the cache may be polluted with unwanted libraries found before
cmake -DCMAKE_PREFIX_PATH=/opt/Qt/5.9.1/gcc_64 ..
..
``ModuleNotFoundError`` upon starting Cutter.
This can be resolved by either: 1. Disabling the optional jupyter
support during building by modifying ``build.sh`` as follows:
- Uncomment
``#QMAKE_CONF="CUTTER_ENABLE_JUPYTER=false CUTTER_ENABLE_QTWEBENGINE=false"``
- Comment out the prior empty ``QMAKE_CONF=""``
2. Or alternatively by installing the two python dependencies manually
afterwards via:
::
pip3 install notebook jupyter_client
Building with Meson (Windows)
-----------------------------
Additional requirements:
- Visual Studio 2015 or Visual Studio 2017
- Ninja build system
- Meson build system
Download and unpack
`Ninja <https://github.com/ninja-build/ninja/releases>`__ to the Cutter
source root directory.
Environment settings (example for x64 version):
``batch :: Export MSVC variables CALL "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x64 :: Add qmake to PATH SET "PATH=C:\Qt\5.10.1\msvc2015_64\bin;%PATH%" :: Add Python to PATH SET "PATH=C:\Program Files\Python36;%PATH%"``
Install Meson:
.. code:: batch
python -m pip install meson
To compile Cutter run:
.. code:: batch
CALL prepare_r2.bat
CALL build.bat

112
docs-ref/source/code.rst Normal file
View File

@ -0,0 +1,112 @@
Contributing
============
This page shows some hints about the coding conventions.
*Disclaimer: It is a work in progress and we will provide soon a fully
documented API.*
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:
.. code:: cpp
Core()->getOffset();
Calling a radare2 command
~~~~~~~~~~~~~~~~~~~~~~~~~
There are two ways to do it: \* ``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")``.
It is way easier to parse a json output.
Example:
.. code:: cpp
QJsonArray array = Core()->cmdj("pdj 1 @ main").array();
Seek the current file
~~~~~~~~~~~~~~~~~~~~~
To modify radare2 seek use ``CutterCore::seek(const RVA offset)``. This
is important because it will emit a
``CutterCore::seekChanged(RVA offset)`` signal. Never ever call
``cmd("s offset")``;
Example:
.. code:: cpp
Core()->seek(0x00C0FFEE);
Creating a widget
~~~~~~~~~~~~~~~~~
Make sure to connect the ``CutterCore::seekChanged(RVA offset)`` signal
so your widget refreshes its output when radare2 seek is modified
(switching to another function, etc.).
General coding guidelines
-------------------------
Coding style
~~~~~~~~~~~~
We follow `these guidelines <https://wiki.qt.io/Qt_Coding_Style>`__ to
format the code. If in doubt, you can use `AStyle
2.06 <https://sourceforge.net/projects/astyle/files/astyle/astyle%202.06/>`__
to format the code. The command line for formatting the code according
to the style is:
.. code:: bash
astyle --project=src/Cutter.astylerc src/filename.cpp
Loops
^^^^^
We use C++11 foreach loop style which means any “foreach” loop should
look like:
.. code:: cpp
for (QJsonValue value : importsArray) {
doSomething(value);
}
Nullptr
^^^^^^^
Please do not use ``0`` nor ``Q_NULLPTR``, only use ``nullptr``.
Example:
.. code:: cpp
QObject *object = nullptr;
Connecting signals
^^^^^^^^^^^^^^^^^^
To connect a signal to a slot, this is the preferred way to do it:
.. code:: cpp
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.

56
docs-ref/source/common-errors.rst Normal file
View File

@ -0,0 +1,56 @@
Common errors
=============
This page lists common issues met by our users.
AppImage crashes
----------------
If the linux AppImage binary crashes upon startup, make sure your
``LD_LIBRARY_PATH`` environment variable is empty.
`#579 <https://github.com/radareorg/cutter/issues/579>`__
--------------
Compilation error
-----------------
r_core development package not found
If you installed radare2 and still encounter this error, could be your
``PATH`` environment variable is set improperly (doesn’t contain
``/usr/local/bin``). That can be, for example, due to ``Qt Creator.app``
being copied over to ``/Applications``. To fix this, append
``:/usr/local/bin`` to the ``PATH`` variable within the *Build
Environment* section in Qt Creator. See the screenshot below should you
encounter any problems.
On OS X you can also try:
- ``PKG_CONFIG_PATH=$HOME/bin/prefix/radare2/lib/pkgconfig qmake``
- ``PKG_CONFIG_PATH=$HOME/cutter/radare2/pkgcfg qmake`` (for modern
version and if radare2 was installed like the submodule)
.. image:: images/cutter_path_settings.png
Or radare2 libs could be installed to ``/usr/lib/pkgconfig/``, so you
can add variable ``PKG_CONFIG_PATH`` with value ``/usr/lib/pkgconfig/``
--------------
OS X libjpeg error
On Mac, QT5 apps fail to build on QtCreator if you have the libjpeg lib
installed with brew. Run this command to workaround the issue:
::
sudo mv /usr/local/lib/libjpeg.dylib /usr/local/lib/libjpeg.dylib.not-found
Keyboard layout issue
---------------------
Some people report that they have keyboard issues. Usually it is because
the Xorg layout is wrong. You can check it with: ``setxkbmap -query``
Most of the time using ``setxkbmap us`` solves the issue, but it might
not be enough and require some more advanced Xorg configuration.

0
docs/images/cutter_path_settings.png → docs-ref/source/images/cutter_path_settings.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 203 KiB

After

Width:  |  Height:  |  Size: 203 KiB

0
docs/images/screenshot.png → docs-ref/source/images/screenshot.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 416 KiB

After

Width:  |  Height:  |  Size: 416 KiB

60
docs-ref/source/index.rst
View File

@ -1,10 +1,48 @@
.. Cutter documentation master file, created by
sphinx-quickstart on Thu Feb 7 13:57:44 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Cutter Documentation
====================
Cutter is a Qt and C++ GUI for radare2. Its goal is making an advanced,
customizable and FOSS reverse-engineering platform while keeping the
user experience at mind. Cutter is created by reverse engineers for
reverse engineers.
.. image:: images/screenshot.png
Get Cutter
----------
Cutter is available for all platforms (Linux, OS X, Windows). You can
download the latest release
`here <https://github.com/radareorg/cutter/releases>`__. \* OSX:
Download the latest ``.dmg`` file. \* Windows: Download the latest
archive. \* Linux: use the AppImage file. Then just make it executable
and run it: \* ``chmod +x Cutter-v1.7.4-x86_64.AppImage`` \*
``./Cutter-v1.7.4-x86_64.AppImage``
Building from sources
---------------------
To build Cutter on your local machine, please follow this guide:
`Building from source <building.html>`__
Need help?
----------
You can contact the *Cutter* developers and community on:
- Telegram: https://t.me/r2cutter
- #cutter on irc.freenode.net
- Twitter: [@r2gui](https://twitter.com/r2gui)
Want to help the project?
-------------------------
If you want to contribute to Cutter, take a look
`here <https://github.com/radareorg/cutter/blob/master/CONTRIBUTING.md>`__
to know what you can do to help the project!
Welcome to Cutter's documentation!
==================================
.. toctree::
:maxdepth: 2
@ -12,13 +50,3 @@ Welcome to Cutter's documentation!
:glob:
*
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

74
docs-ref/source/shortcuts.rst Normal file
View File

@ -0,0 +1,74 @@
Shortcuts
=========
This page regroups the common shortcuts available in Cutter.
Global shortcuts
----------------
+------------+---------------------+
| Shortcut | Function |
+============+=====================+
| . | Focus console input |
| G/S | Focus search bar |
| Ctrl/Cmd+R | Refresh contents |
+------------+---------------------+
Widget shortcuts
----------------
+-----------+---------+
| Shortcut | Widget |
+===========+=========+
| Shift+F12 | Strings |
| Shift+G | Graph |
| Shift+I | Imports |
| Shift+E | Exports |
+-----------+---------+
Disassembly view shortcuts
--------------------------
+------------+----------------------------------+
| Shortcut | Function |
+============+==================================+
| Esc | Seek to previous position |
| Space | Switch to disassembly graph view |
| Ctrl/Cmd+C | Copy |
| ; | Add comment |
| N | Rename current function/flag |
| Shift+N | Rename flag/function used here |
| X | Show Xrefs |
+------------+----------------------------------+
Graph view shortcuts
--------------------
+---------------------+-----------------------------------+
| Shortcut | Function |
+=====================+===================================+
| Esc | Seek to previous position |
| Space | Switch to disassembly view |
| Ctrl/Cmd+MouseWheel | Zoom |
| + | Zoom in |
| - | Zoom out |
| = | Reset zoom |
| J | Next instruction |
| K | Previous instruction |
| T | Follow True/Unconditional branch |
| F | Follow False/Unconditional branch |
+---------------------+-----------------------------------+
Debug shortcuts
---------------
+-----------------+----------------+
| Shortcut | Function |
+=================+================+
| F9 | Start debug |
| F7 | Step into |
| F8 | Step over |
| F5 | Continue |
| F2/(Ctrl/Cmd)+B | Add breakpoint |
+-----------------+----------------+

141
docs/building.md
View File

@ -1,141 +0,0 @@
# Building
First you must get the source of Cutter by cloning the repository:
```
git clone --recurse-submodules https://github.com/radareorg/cutter
```
The "official" way to build Cutter is by using qmake, but there are two alternatives -- cmake and meson.
In any case, there are obviously some requirements:
* Radare2 installed from submodule
* Qt 5.9 or above
* Python3.6
**Before compiling, note that we also provide binaries available for windows/linux/MacOS X [here](https://github.com/radareorg/cutter/releases).**
---
# Building options
Note that there are two major building options available:
* `CUTTER_ENABLE_JUPYTER` is used to compile Cutter with bundled Python and Jupyter module
* `CUTTER_ENABLE_QTWEBENGINE` is used to compile Cutter with bundled QtWebEngine (to ease jupyter console usage)
---
# Building with Qmake
#### Compiling on Linux / macOS
The easy way is to simply run `./build.sh` from the root directory, and let the magic happen. The script will use qmake to build Cutter.
If you want to manually use qmake, follow this steps:
```sh
mkdir build; cd build
qmake ../src/Cutter.pro
make
cd ..
```
#### Additional steps for macOS
On macOS you will also have to copy the launcher bash script:
```sh
mv Cutter.app/Contents/MacOS/Cutter Cutter.app/Contents/MacOS/Cutter.bin
cp ../src/macos/Cutter Cutter.app/Contents/MacOS/Cutter && chmod +x Cutter.app/Contents/MacOS/Cutter
```
---
# Building with Cmake
### Requirements
* CMake >= 3.1
### Building on Linux
The root for CMake is in src/. In-source builds are **not allowed**, so you **must** run CMake from a separate directory:
```
cd src
mkdir build
cd build
cmake ..
```
If all went well, you should now have a working Makefile in your build directory:
```
make
```
---
# Building on Windows
Alternatively, on Windows you can run something like this (depending on your Cmake installation)
```batch
set CMAKE_PREFIX_PATH=c:\Qt\qt-5.6.2-msvc2013-x86\5.6\msvc2013\lib\cmake
cd src
mkdir build
cd build
cmake-gui ..
```
Click `Configure` and select `Visual Studio 14 2015` from the list. After configuration is done, click `Generate` and you can open `Cutter.sln` to compile the code as usual.
## Troubleshooting
> Cmake: qt development package not found
Depending on how Qt installed (Distribution packages or using the Qt installer application), CMake may not be able to find it by itself if it is not in a common place. If that is the case, double check that the correct Qt version is installed. Locate its prefix (a directory containing bin/, lib/, include/, etc.) and specify it to CMake using `CMAKE_PREFIX_PATH` in the above process, e.g.:
```
rm CMakeCache.txt # the cache may be polluted with unwanted libraries found before
cmake -DCMAKE_PREFIX_PATH=/opt/Qt/5.9.1/gcc_64 ..
```
> `ModuleNotFoundError` upon starting Cutter.
This can be resolved by either:
1. Disabling the optional jupyter support during building by modifying `build.sh` as follows:
* Uncomment `#QMAKE_CONF="CUTTER_ENABLE_JUPYTER=false CUTTER_ENABLE_QTWEBENGINE=false"`
* Comment out the prior empty `QMAKE_CONF=""`
2. Or alternatively by installing the two python dependencies manually afterwards via:
```
pip3 install notebook jupyter_client
```
## Building with Meson (Windows)
Additional requirements:
* Visual Studio 2015 or Visual Studio 2017
* Ninja build system
* Meson build system
Download and unpack [Ninja](https://github.com/ninja-build/ninja/releases) to the Cutter source root directory.
Environment settings (example for x64 version):
```batch
:: Export MSVC variables
CALL "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x64
:: Add qmake to PATH
SET "PATH=C:\Qt\5.10.1\msvc2015_64\bin;%PATH%"
:: Add Python to PATH
SET "PATH=C:\Program Files\Python36;%PATH%" ```
Install Meson:
```batch
python -m pip install meson
```
To compile Cutter run:
```batch
CALL prepare_r2.bat
CALL build.bat
```

82
docs/code.md
View File

@ -1,82 +0,0 @@
# Contributing
This page shows some hints about the coding conventions.
*Disclaimer: It is a work in progress and we will provide soon a fully documented API.*
## 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:
```c++
Core()->getOffset();
```
### Calling a radare2 command
There are two ways to do it:
* `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")`. It is way easier to parse a json output.
Example:
```c++
QJsonArray array = Core()->cmdj("pdj 1 @ main").array();
```
### Seek the current file
To modify radare2 seek use `CutterCore::seek(const RVA offset)`. This is important because it will emit a `CutterCore::seekChanged(RVA offset)` signal.
Never ever call `cmd("s offset")`;
Example:
```c++
Core()->seek(0x00C0FFEE);
```
### Creating a widget
Make sure to connect the `CutterCore::seekChanged(RVA offset)` signal so your widget refreshes its output when radare2 seek is modified (switching to another function, etc.).
## General coding guidelines
### Coding style
We follow [these guidelines](https://wiki.qt.io/Qt_Coding_Style) to format the code.
If in doubt, you can use [AStyle 2.06](https://sourceforge.net/projects/astyle/files/astyle/astyle%202.06/) to format the code. The command line for formatting the code according to the style is:
```bash
astyle --project=src/Cutter.astylerc src/filename.cpp
```
#### Loops
We use C++11 foreach loop style which means any "foreach" loop should look like:
```c++
for (QJsonValue value : importsArray) {
doSomething(value);
}
```
#### Nullptr
Please do not use `0` nor `Q_NULLPTR`, only use `nullptr`.
Example:
```c++
QObject *object = nullptr;
```
#### Connecting signals
To connect a signal to a slot, this is the preferred way to do it:
```c++
connect(sender, &QObject::destroyed, this, &MyObject::objectDestroyed);
```
The main reason is that this syntax allows the use of lambda functions.
### Functions documentation
*TODO*

40
docs/common-errors.md
View File

@ -1,40 +0,0 @@
# Common errors
This page lists common issues met by our users.
---
# AppImage crashes
If the linux AppImage binary crashes upon startup, make sure your `LD_LIBRARY_PATH` environment variable is empty. [#579](https://github.com/radareorg/cutter/issues/579)
---
# Compilation error
> r_core development package not found
If you installed radare2 and still encounter this error, could be your `PATH` environment variable is set improperly (doesn't contain `/usr/local/bin`). That can be, for example, due to `Qt Creator.app` being copied over to `/Applications`.
To fix this, append `:/usr/local/bin` to the `PATH` variable within the *Build Environment* section in Qt Creator. See the screenshot below should you encounter any problems.
On OS X you can also try:
- `PKG_CONFIG_PATH=$HOME/bin/prefix/radare2/lib/pkgconfig qmake`
- `PKG_CONFIG_PATH=$HOME/cutter/radare2/pkgcfg qmake` (for modern version and if radare2 was installed like the submodule)
<img src="images/cutter_path_settings.png" alt="Cutter screenshot">
Or radare2 libs could be installed to `/usr/lib/pkgconfig/`, so you can add variable `PKG_CONFIG_PATH` with value `/usr/lib/pkgconfig/`
---
> OS X libjpeg error
On Mac, QT5 apps fail to build on QtCreator if you have the libjpeg lib installed with brew. Run this command to workaround the issue:
```
sudo mv /usr/local/lib/libjpeg.dylib /usr/local/lib/libjpeg.dylib.not-found
```
# Keyboard layout issue
Some people report that they have keyboard issues. Usually it is because the Xorg layout is wrong. You can check it with:
```setxkbmap -query``` Most of the time using ```setxkbmap us``` solves the issue, but it might not be enough and require some more advanced Xorg configuration.

41
docs/index.md
View File

@ -1,41 +0,0 @@
---
homepage: true
---
# Overview
Cutter is a Qt and C++ GUI for radare2. Its goal is making an advanced, customizable and FOSS reverse-engineering platform while keeping the user experience at mind. Cutter is created by reverse engineers for reverse engineers.
<img src="images/screenshot.png" alt="Cutter screenshot">
---
# Get Cutter
Cutter is available for all platforms (Linux, OS X, Windows).
You can download the latest release [here](https://github.com/radareorg/cutter/releases).
* OSX: Download the latest `.dmg` file.
* Windows: Download the latest archive.
* Linux: use the AppImage file. Then just make it executable and run it:
* `chmod +x Cutter-v1.7.4-x86_64.AppImage`
* `./Cutter-v1.7.4-x86_64.AppImage`
---
# Building from sources
To build Cutter on your local machine, please follow this guide: [Building from source](building.html)
---
# Need help?
You can contact the *Cutter* developers and community on:
- Telegram: https://t.me/r2cutter
- #cutter on irc.freenode.net
- Twitter: [@r2gui](https://twitter.com/r2gui)
# Want to help the project?
If you want to contribute to Cutter, take a look [here](https://github.com/radareorg/cutter/blob/master/CONTRIBUTING.md) to know what you can do to help the project!

64
docs/shortcuts.md
View File

@ -1,64 +0,0 @@
# Shortcuts
This page regroups the common shortcuts available in Cutter.
# Global shortcuts
{:.table}
| Shortcut | Function |
| ---------- | ------------------- |
| . | Focus console input |
| G/S | Focus search bar |
| Ctrl/Cmd+R | Refresh contents |
# Widget shortcuts
{:.table}
| Shortcut | Widget |
|-----------|---------|
| Shift+F12 | Strings |
| Shift+G | Graph |
| Shift+I | Imports |
| Shift+E | Exports |
# Disassembly view shortcuts
{:.table}
| Shortcut | Function |
| ---------- | -------------------------------- |
| Esc | Seek to previous position |
| Space | Switch to disassembly graph view |
| Ctrl/Cmd+C | Copy |
| ; | Add comment |
| N | Rename current function/flag |
| Shift+N | Rename flag/function used here |
| X | Show Xrefs |
# Graph view shortcuts
{:.table}
| Shortcut | Function |
| ------------------- | -------------------------- |
| Esc | Seek to previous position |
| Space | Switch to disassembly view |
| Ctrl/Cmd+MouseWheel | Zoom |
| + | Zoom in |
| - | Zoom out |
| = | Reset zoom |
| J | Next instruction |
| K | Previous instruction |
| T | Follow True/Unconditional branch |
| F | Follow False/Unconditional branch |
# Debug shortcuts
{:.table}
| Shortcut | Function |
| --------------- | -------------- |
| F9 | Start debug |
| F7 | Step into |
| F8 | Step over |
| F5 | Continue |
| F2/(Ctrl/Cmd)+B | Add breakpoint |