diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 0000000000..b8b2672602 --- /dev/null +++ b/BUILDING.md @@ -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 +``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 572804310c..939b9907de 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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: diff --git a/DEVELOPERS.md b/DEVELOPERS.md index 58888d8a39..fdbe44a881 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -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 diff --git a/README.md b/README.md index f1c6157f6e..5b8470c4a4 100644 --- a/README.md +++ b/README.md @@ -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) - -Packaging status - - # 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 diff --git a/meson.build b/meson.build index 63024e96f6..a3d14193a8 100644 --- a/meson.build +++ b/meson.build @@ -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.') diff --git a/test/README.md b/test/README.md index 14a2c04486..8f0f4441bf 100644 --- a/test/README.md +++ b/test/README.md @@ -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=< + +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).