portugalfuturista/rizin
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rewrite some documentation (#49)

Browse source
This commit is contained in:
Riccardo Schirone 2020-10-26 17:12:19 +01:00 committed by GitHub
parent 4e18226c8d
commit cb09988b9d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 307 additions and 401 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

125
BUILDING.md Normal file
View file

@ -0,0 +1,125 @@
# Clone the Rizin project and keep it updated
Rizin uses submodules, so make sure to clone them as well. The first time you
download Rizin you can use:
```
$ git clone --recurse-submodules https://github.com/rizinorg/rizin
```
or:
```
$ git clone https://github.com/rizinorg/rizin
$ cd rizin
$ git submodule init
$ git submodule update
```
After that, use `git pull --recurse-submodules` to update both the Rizin
codebase and submodules, or `git submodule update` to just update the
submodules.
# Build
Rizin uses [`meson`](https://mesonbuild.com/) to build. As not all systems have
a version of `meson` that is recent enough, we suggest to install it directly
from `pip` with `pip install meson`. If necessary, also install `ninja` with
`pip install ninja`.
## *NIX systems
### Build system-wide, in `/usr/local`
This is the default configuration and it allows you to install your built Rizin
version while keeping, if provided, the Rizin version shipped by your
distribution in `/usr`.
```
$ meson build
$ ninja -C build # or `meson compile -C build`
$ sudo ninja -C build install # or `meson install -C build`
```
As not all systems look for libraries in `/usr/local` subdirectories, you may
have to set `LD_LIBRARY_PATH` to the proper path (e.g. `/usr/local/lib64` or
`/usr/local/lib`). Otherwise, if you don't want to change your `LD_LIBRARY_PATH`
you can use `meson -Dlocal=true build` in the first step to use `RPATH` and make
sure the rizin binary can find its libraries by itself.
### Build system-wide, in `/usr`
If your system does not already provide rizin in `/usr/bin`, you want to package
Rizin on your preferred distribution or you just prefer to have Rizin together
with all other binaries on your system, you can also install it system-wide in
`/usr`.
```
$ meson --prefix=/usr build
$ ninja -C build
$ sudo ninja -C build install
```
This kind of installation usually does not require any change to
`LD_LIBRARY_PATH` and it should work out of the box.
### Build user-wide, in `~/.local`
You are not forced to install Rizin in your system, you can just make it
available for your current user, without requiring you to have `sudo` access to
the machine (or if you don't trust our build scripts enough).
```
$ meson --prefix=~/.local build
$ ninja -C build
$ ninja -C build install
```
The `install` step will install rizin in `~/.local/bin`, so make sure to add it
to your `PATH` variable. As most systems don't look for libraries in
`~/.local/lib`/`~/.local/lib64`, you will have to set `LD_LIBRARY_PATH`
accordingly or, if you prefer, use `meson -Dlocal=true --prefix=~/.local build`
instead of just `meson --prefix=~/.local build`.
## Windows
The building steps on Windows are the same as on *NIX systems, however you will
have to run the following commands from the Visual Studio Developer shell
[FIXME: proper name, I don't remember right now]. We also suggest to compile
Rizin statically, to avoid dealing with libraries when running the Rizin
binaries.
```
$ meson --prefix=$PWD\rizin-install --default-library=static -Dstatic_runtime=true build
$ ninja -C build
$ ninja -C build install
```
You can run rizin from `$PWD\rizin-install\bin`.
## Build with ASAN/UBSAN
Use `-Db_sanitize=address,undefined` during the setup phase.
```
$ meson -Db_sanitize=address,undefined build
```
## Build fully-static binaries
It may be useful to run Rizin just by using a single file, which can be copied
on other systems if necessary.
```
$ CFLAGS="-static" meson --default-library=static build
```
# Build with acr/Makefile (deprecated)
Rizin also support compilation with configure+make, however this is not
suggested and it is going to be removed in future releases.
To compile use:
```
$ ./configure --prefix=/usr
$ make
$ sudo make install
```

43
CONTRIBUTING.md
View file

@ -1,14 +1,15 @@
# How to report issues
Before reporting an issue with GitHub, be sure that:
* you are using the git version of rizin
* you are using the latest released version of Rizin or the latest git version
* you are using a clean installation
* the issue was not already reported
When the above conditions are satisfied, feel free to submit an issue
while trying to be as precise as possible. If you can, provide the problematic
binary, the steps to reproduce the error and a backtrace in case of SEGFAULTs.
Any information will help to fix the problem.
When the above conditions are satisfied, feel free to submit an issue while
trying to be as precise as possible. If you can, provide the problematic binary,
the steps to reproduce the error and a backtrace in case of SEGFAULTs. Try to
follow the issue template that comes by default. Any information will help to
fix the problem.
# How to contribute
@ -19,27 +20,22 @@ try to keep the codebase consistent and clean.
* Make sure you have a GitHub account and solid ability to use `git`.
* Fork the repository on GitHub.
* Create a topic branch from master. Please avoid working directly on the `master` branch.
* Create a topic branch from `dev`. Please avoid working directly on the `dev` branch.
* Make commits of logical units.
* Check for coding style issues with:
git diff master..mybranch | ./sys/clang-format-diff.py -p1
and be sure to follow the CODINGSTYLE (more on this in [DEVELOPERS.md][]).
* Be sure to follow the CODINGSTYLE (more on this in [DEVELOPERS.md][]).
* Submit the Pull Request(PR) on Github.
* Prefix the PR title with `WIP:` if it's not yet ready to be merged
* When relevant, write a test in [test/](test).
## Rebasing onto updated master
## Rebasing onto updated dev
Every so often, your PR will lag behind `master` and get conflicts.
Every so often, your PR will lag behind `dev` and get conflicts.
To "update" your branch `my-awesome-feature`, you *rebase* it onto
the latest `rizinorg/master`, and *force-push* the result into your fork.
the latest `rizinorg/dev`, and *force-push* the result into your fork.
#### Step 1: Switch to `master` branch.
#### Step 1: Switch to `dev` branch.
$ git checkout master
$ git checkout dev
#### Step 2: Pull new commits published to rizinorg repo.
@ -51,12 +47,12 @@ the latest `rizinorg/master`, and *force-push* the result into your fork.
#### Step 4: Rebase the `my-awesome-feature` branch.
$ git rebase master
$ git rebase dev
Optionally, use the alternative mode "interactive rebase". It allows
to `squash` your commits all into one, reorder, reword them, etc.
$ git rebase -i master
$ git rebase -i dev
Follow git instructions when conflicts arise.
@ -69,7 +65,7 @@ creates newer versions of them. git needs to confirm the destruction of
previous incarnations.
When afraid to touch force and risk losing your work (do backups!..),
try *merging master into your branch* instead of rebasing onto it.
try *merging dev into your branch* instead of rebasing onto it.
This is discouraged, as it produces ugly hard-to-maintain commit history.
## Commit message rules
@ -80,10 +76,9 @@ rules to make the git history more readable and consistent:
* Start the message capitalized (only the first character must be in uppercase)
* Be short and concise, the whole concept must fit one line
* If a command is inlined, use backticks
* Add a double-hashtag if the change matters for the changelog (See below)
* If the commit fixes a bug start with 'Fix #number - '
* For extra details, add an empty line and use asterisk item list below
* Use present simple grammar tense (Add vs Added, Fix vs Fixed/Fixes)
* Add a double-hashtag if the change matters for the changelog (See below)
### Commit message hashtag list:
@ -124,8 +119,8 @@ rules to make the git history more readable and consistent:
* [README.md][]
* [DEVELOPERS.md][]
[README.md]: https://github.com/rizinorg/rizin/blob/master/README.md
[DEVELOPERS.md]: https://github.com/rizinorg/rizin/blob/master/DEVELOPERS.md
[README.md]: https://github.com/rizinorg/rizin/blob/dev/README.md
[DEVELOPERS.md]: https://github.com/rizinorg/rizin/blob/dev/DEVELOPERS.md
If you need more confidence in your git skills, check out this quick guide:
<https://learnxinyminutes.com/docs/git/>

238
DEVELOPERS.md
View file

@ -1,7 +1,6 @@
# DEVELOPERS
This file aims to describe an introduction for developers to work
on the code base of rizin project.
This file is aimed at developers who want to work on the Rizin code base.
## Documentation
There is support for Doxygen document generation in this repo.
@ -36,14 +35,6 @@ static int findMinMax(RzList *maps, ut64 *min, ut64 *max, int skip, int width);
In order to contribute with patches or plugins, we encourage you to
use the same coding style as the rest of the code base.
Please use `./sys/clang-format-diff.py` before submitting a PR to be sure you
are following the coding style. If you find a bug in this script, please create
an issue on GitHub. You can also install the pre-commit hook
`./sys/pre-commit-indent.sh` by copying it in `.git/hooks/pre-commit` which
will check the coding style of the modified lines before committing them.
You may find some additional notes on this topic in doc/vim.
* Tabs are used for indentation. In a switch statement, the
cases are indented at the switch level.
@ -57,7 +48,9 @@ default:
}
```
* Lines should be at most 78 chars. A tab is considered as 8 chars.
* Lines should be at most 100 chars. A tab is considered as 8 chars. If it makes
things more readable, you can use more than 100 characters, but this should be
the exception, not the rule.
* Braces open on the same line as the for/while/if/else/function/etc. Closing
braces are put on a line of their own, except in the else of an if statement
@ -162,7 +155,7 @@ a = (b << 3) * 5;
* Structure in the C files
The structure of the C files in rizin must be like this:
The structure of the C files in Rizin must be like this:
```c
/* Copyright ... */ ## copyright
@ -177,7 +170,7 @@ RZ_API void public(void) {} ## public apis starting with constructor/destruct
* Why return int vs enum
The reason why many places in rizin-land functions return int instead of an enum type is because enums can't be OR'ed; otherwise, it breaks the usage within a switch statement and swig can't handle that stuff.
The reason why many places in Rizin-land functions return int instead of an enum type is because enums can't be OR'ed; otherwise, it breaks the usage within a switch statement and swig can't handle that stuff.
```
rz_core_wrap.cxx:28612:60: error: assigning to 'RzRegisterType' from incompatible type 'long'
@ -199,10 +192,6 @@ rz_core_wrap.cxx:32103:61: error: assigning to 'RzDebugReasonType' from incompat
- This way we reduce the number of local variables per function
and it's easier to find which variables are used, where and so on.
* Always put a space before every parenthesis (function calls, conditionals,
fors, etc, ...) except when defining the function signature. This is
useful for grepping.
* Function names should be explicit enough to not require a comment
explaining what it does when seen elsewhere in code.
@ -210,26 +199,18 @@ rz_core_wrap.cxx:32103:61: error: assigning to 'RzDebugReasonType' from incompat
* The rest of functions must be static, to avoid polluting the global space.
* Avoid using global variables, they are evil. Only use them for singletons
and WIP code, placing a comment explaining the reason for them to stay there.
* If you *really* need to comment out some code, use #if 0 (...) #endif. In
general, don't comment out code because it makes the code less readable.
* Avoid using global variables, they are evil.
* Do not write ultra-large functions: split them into multiple or simplify
the algorithm, only external-copy-pasted-not-going-to-be-maintained code
can be accepted in this way (gnu code, external disassemblers, etc..)
* See sys/indent.sh for indenting your code automatically
* See .clang-format for automated indentation
* See doc/vim for vimrc
* See .clang-format for work-in-progress support for automated indentation
* Use the rizin types instead of the ones in stdint, which are known to cause some
* Use the Rizin types instead of the ones in stdint, which are known to cause some
portability issues. So, instead of uint8_t, use ut8, etc..
* Never ever use %lld or %llx. This is not portable. Always use the PFMT64x
* Never ever use `%lld` or `%llx`. This is not portable. Always use the PFMT64x
macros. Those are similar to the ones in GLIB.
### Shell Scripts
@ -281,7 +262,7 @@ within the integer value, REGARDLESS of the host endian of the machine.
## Endian helper functions
Radare2 now uses helper functions to interpret all byte streams in a known endian.
Rizin now uses helper functions to interpret all byte streams in a known endian.
Please use these at all times, eg:
@ -296,44 +277,9 @@ There are a number of helper functions for 64, 32, 16, and 8 bit reads and write
(Note that 8 bit reads are equivalent to casting a single byte of the buffer
to a ut8 value, ie endian is irrelevant).
### Editor configuration
Vim/Neovim:
```vim
setl cindent
setl tabstop=4
setl noexpandtab
setl cino=:0,+0,(2,J0,{1,}0,>4,)1,m2
```
Emacs:
```elisp
(c-add-style "rizin"
'((c-basic-offset . 4)
(tab-width . 4)
(indent-tabs-mode . t)
;;;; You would need (put 'c-auto-align-backslashes 'safe-local-variable 'booleanp) to enable this
;; (c-auto-align-backslashes . nil)
(c-offsets-alist
(arglist-intro . ++)
(arglist-cont . ++)
(arglist-cont-nonempty . ++)
(statement-cont . ++)
)))
```
You may use directory-local variables by putting
```elisp
((c-mode . ((c-file-style . "rizin"))))
```
into `.dir-locals.el`.
## Packed structures
Due to the various differences between platforms and compilers rizin
Due to the various differences between platforms and compilers Rizin
has a special helper macro - `RZ_PACKED()`. Instead of non-portable
`#pragma pack` or `__attribute__((packed))` it is advised to use this macro
instead. To wrap the code inside of it you just need to write:
@ -353,162 +299,6 @@ RZ_PACKED (typedef structmystruct {
## Modules
The rizin code base is modularized into different libraries that are
found in librz/ directory. The binrz/ directory contains the programs
The Rizin code base is modularized into different libraries that are
found in `librz/` directory. The `binrz/` directory contains the programs
which use the libraries.
It is possible to generate PIC/nonPIC builds of the libraries and also
to create a single static library so you can use a single library
archive (.a) to link your programs and get your programs using radare
framework libraries without depending on them. See doc/static for more info.
The following presentation gives a good overview of the libraries:
http://radare.org/get/lacon-radare-2009/
## API
As mentioned in README.md, the API itself is maintained in a different
repository. The API function definitions in C header files are derived
from and documented in the rizin-bindings repository, found at:
```sh
git clone git://github.com/rizinorg/rizin-bindings
```
Currently the process of updating the header files from changed API
bindings requires human intervention, to ensure that proper review
occurs. Incorrect definitions in the C header files will trigger
a build failure in the bindings repository.
If you are able to write a plugin for various IDE that can associate
the bindings with the header files, such a contribution would be
very welcome.
## Dependencies
rizin can be built without any special dependency. It just requires
a C compiler, a GNU make and a unix-like system.
## Cross compilation
The instructions to crosscompile rizin to Windows are in doc/windows.
You may find other documents in doc/ explaining how to build it on iOS,
linux-arm and others, but the procedure is like this:
- define `CC`
- use a different compiler profile with `--with-compiler`
- use a different OS with `--with-ostype`
- type `make`
- install in `DESTDIR`
## Source repository
The source of rizin can be found in the following GitHub repository.
```sh
git clone git://github.com/rizinorg/rizin
```
Other packages rizin depends on, such as Capstone, are pulled from
their git repository as required.
To get an up-to-date copy of the repository, you should perform the
following steps:
```sh
git pull
```
If you have conflicts in your local copy, it's because you have modified
files which are conflicting with the incoming patchsets. To get a clean
source directory, type the following command:
```sh
git clean -xdf
git reset --hard
```
## Compilation
Inter-module rebuild dependencies are not handled automatically and
require human interaction to recompile the affected modules.
This is a common issue and can end up having outdated libraries trying
to use deprecated structures which may result into segfaults.
You have to make clean on the affected modules. If you are not
sure enough that everything is OK, just make clean the whole project.
If you want to accelerate the build process after full make cleans,
you should use ccache in this way:
```
export CC="ccache gcc"
```
## Installation
Developers use to modify the code, type make and then try.
rizin has a specific makefile target that allows you to install
system wide but using symlinks instead of hard copies.
```sh
sudo make symstall
```
This kind of installation is really helpful if you do lot of changes
in the code for various reasons.
- only one install is required across multiple builds
- installation time is much faster
## Regression testing
The source of the rizin regression test suite can be found in the
`test/` directory, while binaries for this test are located in the
following GitHub repository.
```sh
git clone git://github.com/rizinorg/rizin-testbins
```
See the `README.md` file in that repository for further information.
The existing test coverage can always do with improvement. So if you can
contribute additional tests, that would be gratefully accepted.
## Reporting bugs
If you notice any misfeature, issue, error, problem or you just
don't know how to do something which is supposed to be covered
by this framework.
You should report it into the GitHub issues page.
https://github.com/rizinorg/rizin/issues
Otherwise, if you are looking for some more feedback, I will
encourage you to send an email to any of the emails enumerated
in the AUTHORS file.
Anyway, if you want to get even more feedback and discuss this
in a public place: join the #radare channel on irc.freenode.net.
The issues page of GitHub contains a list of all the bugs that
have been reported classified with labels by difficulty, type,
milestone, etc. It is a good place to start if you are looking
to contribute.
## HOW TO RELEASE
- Set `RELEASE=1` in global.mk and rizin-bindings/config.mk.acr.
- Use `bsdtar` from libarchive package. GNU tar is broken.
RIZIN
---
- bump revision
- `./configure`
- `make dist`
RIZIN-BINDINGS
---
- `./configure --enable-devel`
- `make`
- `make dist`
- Update the [paths on the website](https://github.com/rizinorg/rizinorg/blob/master/source/download_paths.rst)
--pancake

177
README.md
View file

@ -1,52 +1,68 @@
```
____ ___ ___ ___ ____ ___ ____
| _ \/ \| \/ \ _ \/ _ \ (__ \
| ( - | | ) - | ( _/ / __/
|__\__|_|__|___/__|__|_\__|___| |____|
https://www.radare.org
--pancake
```
| Service | Badge |
|----------|---------------------------------------------------------------------|
| **GithubCI** | [![Tests Status](https://github.com/rizinorg/rizin/workflows/Radare2%20CI/badge.svg)](https://github.com/rizinorg/rizin/actions?query=workflow%3A%22Radare2+CI%22)|
| **TravisCI** | [![Build Status](https://travis-ci.com/rizinorg/rizin.svg?branch=master)](https://travis-ci.com/rizinorg/rizin)|
| **AppVeyor** | [![Build status](https://ci.appveyor.com/api/projects/status/9cgkgxkc3203fm1o/branch/master?svg=true)](https://ci.appveyor.com/project/rizinorg/rizin/branch/master)|
| **FreeBSD (sr.ht)** | [![builds.sr.ht status](https://builds.sr.ht/~xvilka/rizin/commits/freebsd.yml.svg)](https://builds.sr.ht/~xvilka/rizin/commits/freebsd.yml?)|
| **OpenBSD (sr.ht)** | [![builds.sr.ht status](https://builds.sr.ht/~xvilka/rizin/commits/openbsd.yml.svg)](https://builds.sr.ht/~xvilka/rizin/commits/openbsd.yml?)|
| **Coverity** | [![Build Status](https://scan.coverity.com/projects/416/badge.svg)](https://scan.coverity.com/projects/416) |
| **LGTM** | [![Total alerts](https://img.shields.io/lgtm/alerts/g/rizinorg/rizin.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/rizinorg/rizin/alerts/)
| **Infrastructure** | [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/741/badge)](https://bestpractices.coreinfrastructure.org/projects/741) |
| **Codecov** | [![codecov](https://codecov.io/gh/rizinorg/rizin/branch/master/graph/badge.svg)](https://codecov.io/gh/rizinorg/rizin)
| **Fuzzit** | [![fuzzit](https://app.fuzzit.dev/badge?org_id=2zv5qI33roZkRm0oO2Mi&target_id=YVkkS6RPVpKhSixyFWcT&branch=master)](https://app.fuzzit.dev/admin/2zv5qI33roZkRm0oO2Mi/target)
<a href="https://repology.org/metapackage/rizin">
<img src="https://repology.org/badge/vertical-allrepos/rizin.svg" alt="Packaging status" align="right" width="150px">
</a>
# Introduction
r2 is a rewrite from scratch of radare in order to provide
a set of libraries and tools to work with binary files.
Rizin is a fork of the radare2 reverse engineering framework with a focus on
usability, working features and code cleanliness.
Radare project started as a forensics tool, a scriptable
command-line hexadecimal editor able to open disk files,
but later added support for analyzing binaries, disassembling
code, debugging programs, attaching to remote gdb servers...
Rizin is portable and it can be used to analyze binaries, disassemble code,
debug programs, as a forensics tool, as a scriptable command-line hexadecimal
editor able to open disk files, and much more!
rizin is portable.
To learn more on Rizin you may want to read the
[official Rizin book](https://book.rizin.re).
To learn more on rizin you may want to read the [official rizin book](https://book.rada.re).
# How to install
You can also use [r2lrn](https://github.com/0ki/r2lrn) or r2golf for a hands-on learning experience.
You can find the latest release binaries for Android, Debian, Ubuntu, MacOS,
Windows [here](https://github.com/radareorg/radare2/releases/latest). If we
don't provide a released binary for your system, you can still build Rizin
yourself.
## Operating Systems
# How to build
Use `meson` to compile and install Rizin. Please make sure to get an updated
`meson` (e.g. get it with `pip install meson` if your system does not provide
one that is at least version 0.50.1).
Clone this repository and make sure to clone the submodules as well:
```
$ git clone --recurse-submodules https://github.com/rizinorg/rizin
```
Then compile and install with:
```
$ meson build
$ meson compile -C build
$ meson install -C build
$ rizin
Usage: rizin [-ACdfLMnNqStuvwzX] [-P patch] [-p prj] [-a arch] [-b bits] [-i file]
[-s addr] [-B baddr] [-m maddr] [-c cmd] [-e k=v] file|pid|-|--|=
```
NOTE: You may have to add `LD_LIBRARY_PATH=/usr/local/lib64` or
`LD_LIBRARY_PATH=/usr/local/lib` based on your system to make sure rizin will
find the installed libraries.
Please have a look at [BUILDING.md][] for more information about building Rizin.
# Contributing
We very much welcome any kind of contributions, from typos, to documentation, to
refactoring, up to completely new features you may think of. Before
contributing, we would like you to read the file [CONTRIBUTING.md][]. so that we
can all be on the same page.
## Tests
Look at [test/README.md][].
# Supported features
## Supported Operating Systems
Windows (since XP), GNU/Linux, GNU/Darwin, GNU/Hurd, Apple's {Mac,i,iPad,watch}OS,
[Dragonfly|Net|Free|Open]BSD, Android, QNX, Solaris, Haiku, FirefoxOS.
## Architectures
## Supported Architectures
i386, x86-64, ARM, MIPS, PowerPC, SPARC, RISC-V, SH, m68k, m680x, AVR,
XAP, System Z, XCore, CR16, HPPA, ARC, Blackfin, Z80, H8/300, V810,
@ -56,7 +72,7 @@ NIOS II, Java, Dalvik, WebAssembly, MSIL, EBC, TMS320 (c54x, c55x,
c55+, c66), Hexagon, Brainfuck, Malbolge, whitespace, DCPU16, LANAI,
MCORE, mcs96, RSP, SuperH-4, VAX.
## File Formats
## Supported File Formats
ELF, Mach-O, Fatmach-O, PE, PE+, MZ, COFF, OMF, TE, XBE, BIOS/UEFI,
Dyldcache, DEX, ART, CGC, Java class, Android boot image, Plan9 executable,
@ -66,82 +82,17 @@ Game Boy (Advance), Nintendo DS ROMs and Nintendo 3DS FIRMs, various filesystems
## Scripting
Native bindings are supported but the recommended way to interact with r2
from other languages is by using [rzpipe](https://github.com/rizinorg/rizin-rzpipe)
Python, Ruby, JavaScript, Lua, Perl, PHP, Go, Rust, Swift, C#, Java,
Shell, OCaml, Haskell, Scheme (Guile), Common Lisp, Clojure, Erlang, D,
Vala/Genie, Prolog, Nim, Newlisp...
# Install / Update
The recommended way to install or update rizin from git for single-user systems:
$ sys/install.sh
If you don't have root, or just want to install it in your home use:
$ sys/user.sh
Note that those scripts will install using configure+make using symlinks, so you
don't need to reinstall every time you change something in the builddir.
* If you don't like symlinks use `sys/install.sh --install`
* To use capstone5 use the `--with-capstone5` flag.
Alternatively you can also build with meson + ninja:
$ ./sys/meson.py --prefix=/usr --shared --install
## Uninstall
In case of a polluted filesystem, you can uninstall the current
version or remove all previous installations:
$ make uninstall
$ make purge
To remove all stuff including libraries, use
$ make system-purge
## Package Manager
Radare2 has its own package manager - rz-pm. Its packages
repository is on [GitHub too](https://github.com/rizinorg/rizin-pm).
To start to using it for the first time, you need to initialize packages:
$ rz-pm init
Refresh the packages database before installing any package:
$ rz-pm update
To install a package, use the following command:
$ rz-pm install [package name]
# Development
## Coding Style
Look at [CONTRIBUTING.md](https://github.com/rizinorg/rizin/blob/master/CONTRIBUTING.md).
## Tests
Running `make tests` will fetch the test binaries
repository and run all the tests in order to verify that no changes break any functionality.
We run those tests on every commit, and they are also executed with ASAN
and valgrind on different platforms to catch other unwanted 'features'.
We provide a way to interact with Rizin from Python/Haskell/OCaml languages
through [rzpipe](https://github.com/rizinorg/rizin-rzpipe). Other languages
although not currently supported could be easily added.
# Community
Website: [https://www.radare.org/](https://www.radare.org/)
Website: [https://www.rizin.re/](https://www.rizin.re/)
Telegram: [https://t.me/radare](https://t.me/radare)
IRC: irc.freenode.net #rizin
Twitter: [@rizinorg](https://twitter.com/rizinorg)
IRC: irc.freenode.net #radare
[CONTRIBUTING.md]: https://github.com/rizinorg/rizin/blob/dev/CONTRIBUTING.md
[test/README.md]: https://github.com/rizinorg/rizin/blob/dev/test/README.md
[BUILDING.md]: https://github.com/rizinorg/rizin/blob/dev/BUILDING.md
[DEVELOPERS.md]: https://github.com/rizinorg/rizin/blob/dev/DEVELOPERS.md

2
meson.build
View file

@ -270,7 +270,7 @@ endif
# handle libuv library
if get_option('use_libuv')
libuv_dep = dependency('libuv', version: '>=1.0.0', required: false)
libuv_dep = dependency('libuv', version: '>=1.0.0', required: false, static: get_option('default_library') == 'static')
use_libuv = libuv_dep.found()
if not libuv_dep.found()
warning('use_libuv option was set to true, but libuv was not found.')

123
test/README.md
View file

@ -1,32 +1,48 @@
Radare2 Regression Test Suite
Rizin tests
=============================
A set of regression tests for Radare2 (http://radare.org).
Rizin uses both regression and unit tests.
Originally based on work by and now in collaboration with pancake.
# Directory Hierarchy
Directory Hierarchy
-------------------
* db/: The tests sources
* db/: The regressions tests sources
* unit/: Unit tests (written in C, using minunit).
* fuzz/: Fuzzing helper scripts
* bins/: Sample binaries (fetched from the [external repository](https://github.com/rizinorg/rizin-testbins))
Requirements
------------
# Requirements
* Radare2 installed (and in `$PATH` or set the R2 environment).
* Valgrind (optional).
* rizin installed and in `$PATH` (you can also use a rizin not in `$PATH`, but
other files like calling convention files, format files, etc. must have been
installed).
* rz-test compiled and/or installed, which is done by default automatically
when building Rizin.
Usage
-----
# Usage
* To run *all* tests, use `make -k all`.
* To execute only the unit tests use `make -k unit_tests`.
## Regression tests
To run regressions tests use `rz-test` from within the `test` directory.
By default it will run all tests under the `db` subdirectory, however you can
also specify which tests you want to run, by providing its name as argument to
`rz-test`.
Failure Levels
--------------
For example, to run only the asm tests for x86_64, you can do `rz-test
db/asm/x86_64`. `rz-test` provides other interesting options that you can check
out by doing `rz-test -h`.
An option that you may find interesting, in particular when doing changes that
may affect the output of multiple tests, is the `-i` option, which enables
interactive mode. When running tests in this mode, `rz-test` will warn you for
each failed test and it will ask for your input on how to treat the issue. It
can automatically fix the test so that it matches the new output (if that is the
right behaviour!) or it can mark it as broken for you.
## Unit tests
To run unit tests, just use `ninja -C build test` (or `meson test -C build`)
from the top directory (replace `build` with the name of the directory you used
to build Rizin).
# Failure Levels
A test can have one of the following results:
* success: The test passed, and that was expected.
@ -34,16 +50,7 @@ A test can have one of the following results:
* broken: Failure was expected, and happened.
* failed: The test failed unexpectedly. This is a regression.
Reporting Radare2 Bugs
----------------------
Please do not post Radare2 bugs on the r2-regressions github tracker. Instead
use the official r2 tracker:
https://github.com/rizinorg/rizin/issues?state=open
Writing Assembly tests
----------------------
# Writing Assembly tests
Example tests for `db/asm/*`:
@ -85,46 +92,84 @@ Example tests for `db/asm/*`:
arm_v7_64 means what it means
Writing JSON tests
----------
# Writing JSON tests
The JSON tests `db/json` are executed on 3 standard files (1 ELF, 1 MachO, 1 PE). The tests need to be working on the 3 files to pass.
# Commands tests
----------------
Example commands tests for the other `db/` folders:
NAME=test_db
FILE=bins/elf/ls
CMDS=<<EXPECT
CMDS=<<EOF
pd 4
EXPECT=<<RUN
EOF
EXPECT=<<EOF
;-- main:
;-- entry0:
;-- func.100001174:
0x100001174 55 Push rbp
0x100001175 4889e5 Mov rbp, rsp
0x100001178 4157 Push r15
EOF
RUN
* **NAME** is the name of the test, it must be unique
* **FILE** is the path of the file used for the test
* **ARGS** (optional) are the command line argument passed to r2 (e.g -b 16)
* **ARGS** (optional) are the command line argument passed to rizin (e.g -b 16)
* **CMDS** are the commands to be executed by the test
* **EXPECT** is the expected output of the test
* **BROKEN** (optional) is 1 if the tests is expected to be fail, 0 otherwise
* **BROKEN** (optional) is 1 if the tests is expected to be fail, 0 or unspecified otherwise
* **TIMEOUT** (optional) is the number of seconds to wait before considering the test timeout
You must end the test by adding RUN keyword
Advices
-------
## Advices
* For portability reasons Do not use shell pipes, use `~`
* For portability reasons do not use shell pipes, use `~`
* dont use `pd` if not necessary, use `pi`
License
-------
# Unit tests
Assembly, JSON and commands tests are useful to test the overall behaviour of
Rizin, but to test new API or new code we suggest to write small unit tests.
The basic structure of a unit test is the following:
```C
#include "minunit.h"
#include <rz_XXXXX.h>
static bool test_my_feature(void) {
// code to test the behaviour
mu_end;
}
static bool all_tests() {
mu_run_test(test_my_feature);
return tests_passed != tests_run;
}
int main(int argc, char **argv) {
return all_tests();
}
```
Minunit provides various functions to check the actual output of a function with
the expected one. For example:
- `mu_assert_true(actual, message)` checks that `actual` evaluates to true, otherwise it prints `message` on stderr.
- `mu_assert_false(actual, message)` checks that `actual` evaluates to false, otherwise it prints `message` on stderr.
- `mu_assert_eq(actual, expected, message)` checks that the integer (ut64 at most) `actual` is equal to the integer `expected`, otherwise it prints `message` on stderr.
- `mu_assert_ptreq(actual, expected, message)` checks that the pointer `actual` is equal to `expected`.
- `mu_assert_null(actual, message)`
- `mu_assert_streq(actual, expected, message)`
- `mu_assert_memeq(actual, expected, len, message)`
- etc.
If you add a unit test file, be sure to also add it to `unit/meson.build`, so it
is compiled when you compile Rizin.
# License
The test files are licensed under GPL 3 (or later).