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

Improved documentation and README.md (#735)

Browse Source
This commit is contained in:
xarkes 2018-09-30 12:52:48 +02:00 committed by GitHub
parent f5b161c0fa
commit e63744fd79
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 172 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
README.md
View File

@ -4,118 +4,38 @@
A Qt and C++ GUI for radare2 reverse engineering framework (originally named Iaito).
## Screenshot
![Screenshot](https://raw.githubusercontent.com/radareorg/cutter/master/docs/images/screenshot.png)
## Disclaimer
# Disclaimer
Cutter is not aimed at existing radare2 users. It instead focuses on those whose are not yet radare2 users because of the learning curve, because they don't like CLI applications or because of the difficulty/instability of radare2.
## Installing
### Downloading a release
# Downloading a release
Cutter is available for all platforms (Linux, OS X, Windows).
You can download the latest release [here](https://github.com/radareorg/cutter/releases).
* Linux: use the [AppImage](https://github.com/radareorg/cutter/releases/download/v1.7.1/Cutter-v1.7.1-x86_64.AppImage) file. Then just make it executable and run it:
* OSX: Download the latest `.dmg` file.
* Windows: Download the latest archive.
* Linux: use the [AppImage](https://github.com/radareorg/cutter/releases/download/v1.7.1/Cutter-v1.7.1-x86_64.AppImage) file. Then just make it executable and run it:
* `chmod +x Cutter-v1.7.1-x86_64.AppImage`
* `./Cutter-v1.7.1-x86_64.AppImage`
### Building from source
## [Building from source](https://radareorg.github.io/cutter/building.html)
#### Requirements
Cutter is based on Qt so you will need to have it installed.
- Download: [Qt Open Source](https://www.qt.io/download-qt-for-application-development)
- Add Qt 5.9: http://doc.qt.io/qtcreator/creator-project-qmake.html
#### Building
First you must clone the repository:
```sh
git clone --recurse-submodules https://github.com/radareorg/cutter
cd cutter
```
Building on linux:
```sh
./build.sh
```
##### Important note:
When using the default `build.sh` script you might encounter a `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 on Windows:
```
prepare_r2.bat
build.bat
```
If any of those do not work, check the more detailed version [here](https://github.com/radareorg/cutter/blob/master/docs/Compiling.md).
Check this [page](https://github.com/radareorg/cutter/blob/master/docs/Common-errors.md) for common issues.
### Docker
## Docker
To deploy *cutter* using a pre-built `Dockerfile`, it's possible to use the [provided configuration](docker). The corresponding `README.md` file also contains instructions on how to get started using the docker image with minimal effort.
### Global shortcuts
| Shortcut | Function |
| ---------- | ------------------- |
| . | Focus console input |
| G/S | Focus search bar |
| Ctrl/Cmd+R | Refresh contents |
# Documentation
### 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 |
You can find our documentation [here](https://radareorg.github.io/cutter/).
### 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 |
# Help
### Debug shortcuts
| Shortcut | Function |
| --------------- | -------------- |
| F9 | Start debug |
| F7 | Step into |
| F8 | Step over |
| F5 | Continue |
| F2/(Ctrl/Cmd)+B | Add breakpoint |
## Help
Right now the best place to obtain help from *cutter* developers and community is joining this telegram group:
Right now the best place to obtain help from *Cutter* developers and community is to contact us on:
- https://t.me/r2cutter
- #cutter on irc.freenode.net

5
docs/.gitignore vendored
View File

@ -1 +1,4 @@
_site/
_site
.sass-cache
.jekyll-metadata
Gemfile.lock

24
docs/404.html Normal file
View File

@ -0,0 +1,24 @@
---
layout: default
---
<style type="text/css" media="screen">
.container {
margin: 10px auto;
max-width: 600px;
text-align: center;
}
h1 {
margin: 30px 0;
font-size: 4em;
line-height: 1;
letter-spacing: -1px;
}
</style>
<div class="container">
<h1>404</h1>
<p><strong>Page not found :(</strong></p>
<p>The requested page could not be found.</p>
</div>

30
docs/Gemfile Normal file
View File

@ -0,0 +1,30 @@
source "https://rubygems.org"
# Hello! This is where you manage which Jekyll version is used to run.
# When you want to use a different version, change it below, save the
# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
#
# bundle exec jekyll serve
#
# This will help ensure the proper Jekyll version is running.
# Happy Jekylling!
#gem "jekyll", "~> 3.7.4"
# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima", "~> 2.0"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
gem "github-pages", group: :jekyll_plugins
# If you have any plugins, put them here!
group :jekyll_plugins do
#gem "jekyll-feed", "~> 0.6"
end
# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
# Performance-booster for watching directories on Windows
gem "wdm", "~> 0.1.0" if Gem.win_platform?

42
docs/_config.yml
View File

@ -1,10 +1,48 @@
name: Cutter
title: Cutter
project:
version: 1.7.1
download_url: https://github.com/radareorg/cutter/releases
license:
software: GPLv3
software_url: https://opensource.org/licenses/GPL-3.0
docs: CC BY 3.0
docs_url: http://creativecommons.org/licenses/by/3.0/
links:
header:
- title: GitHub
url: https://github.com/radareorg/cutter
footer:
- title: GitHub
url: https://github.com/radareorg/cutter
- title: Issues
url: https://github.com/radareorg/cutter/issues
ui:
header:
color1: "#080331"
color2: "#673051"
trianglify: true
social:
github:
user: radareorg
repo: cutter
twitter:
enabled: false
via: r2gui
hash:
account: r2gui
description: >-
Cutter is a Qt and C++ graphical user interface for the reverse
engineering framework radare2.
twitter_username: r2gui
github_username: radareorg
# Build settings
markdown: kramdown
remote_theme: allejo/jekyll-docs-theme

44
docs/cmake.md
View File

@ -1,44 +0,0 @@
# Compiling with CMake
The "official" way to build Cutter is by using qmake, but as an alternative, a [CMakeLists.txt](https://github.com/radareorg/cutter/blob/master/src/CMakeLists.txt) is provided, so CMake can be used as well.
## Requirements
* CMake >= 3.1
* Radare2 installed from submodule, see [README.md](https://github.com/radareorg/cutter#requirements)
* Qt 5.9
## Building
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
```
### 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 12 2013` from the list. After configuration is done, click `Generate` and you can open `Cutter.sln` to compile the code as usual.
## Troubleshooting
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 ..
```

63
docs/compiling.md
View File

@ -1,63 +0,0 @@
# Compiling Cutter
Cutter supports different build systems:
* Building with qmake
* [Building with cmake](cmake.md)
* Building with meson (see ./meson.py)
Each time in the section below, the prefered method will be explained. For other methods check associated documentation.
**Before compiling, note that we also provide binaries available for windows/linux/MacOS X [here](https://github.com/radareorg/cutter/releases).**
## Requirements
* Qt (version differs from time to time but >= 5.6.1 should be fine)
* Radare2 (version changes, see `git submodule` to check the exact version)
* Python 3.6
### Compiling on Linux / OsX
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 ..
```
### Compiling on 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
```
Pass `CUTTER_ENABLE_JUPYTER=false` argument to `build.bat` if you want to disable Jupyter support. Use `CUTTER_ENABLE_QTWEBENGINE=false` argument to disable QtWebEngine support for Jupyter.
## It doesn't work!
Check this [page](common-errors.md) for common issues.

20
docs/index.md
View File

@ -1,17 +1,23 @@
# Cutter
---
homepage: true
---
# Overview
Cutter is a C++ graphical user interface for the reverse engineering framework radare2.
## Getting started
[//]: # ![Screenshot](https://raw.githubusercontent.com/radareorg/cutter/master/docs/images/screenshot.png)
# Getting started
To start playing with Cutter, download the software for your platform on this link: [https://github.com/radareorg/cutter/releases](https://github.com/radareorg/cutter/releases).
### Analysis
## Analysis
### Interface
Analysis in Cutter is (for now) quite different than other reverse engineering applications.
The analysis must complete before you can actually work on the binary.
# Building Cutter
## Building Cutter
To build Cutter, follow [this guide.][compiling.md]
To build Cutter, follow [this guide](building.md).

50
docs/shortcuts.md Normal file
View File

@ -0,0 +1,50 @@
# 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 |
# 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 |