diff --git a/docs/source/building.rst b/docs/source/building.rst index f45a89f7..6b58b10c 100644 --- a/docs/source/building.rst +++ b/docs/source/building.rst @@ -24,7 +24,7 @@ under **cutter** and you should see the following dir structure: cutter/-| |-docs/ # Cutter Documentation - |-rizin/ # rizin submodule + |-rizin/ # Rizin submodule |-src/ # Cutter Source Code Following sections assume that **cutter** is your working dir. (if not, do ``cd cutter``) @@ -72,7 +72,7 @@ On Arch-based Linux distributions: Building Steps ~~~~~~~~~~~~~~ -The recommended way to build Cutter on Linux is by using CMake. Simply invoke CMake to build Cutter and its dependency radare2. +The recommended way to build Cutter on Linux is by using CMake. Simply invoke CMake to build Cutter and its dependency Rizin. .. code:: sh @@ -88,7 +88,7 @@ If your operating system has a newer version of CMake (> v3.12) you can use this cmake --build build .. note:: -If you want to use Cutter with another version of rizin you can omit ``-DCUTTER_USE_BUNDLED_RIZIN=ON``. Note that using a version of rizin which isn't the version Cutter is using can cause issues and the compilation might fail. +If you want to use Cutter with another version of Rizin you can omit ``-DCUTTER_USE_BUNDLED_RIZIN=ON``. Note that using a version of Rizin which isn't the version Cutter is using can cause issues and the compilation might fail. .. note:: @@ -178,7 +178,7 @@ To compile Cutter, run: .. code:: batch - CALL prepare_r2.bat + CALL prepare_rizin.bat CALL build.bat @@ -198,7 +198,7 @@ QtCreator will then allow you to directly edit the source code and build the pro .. note:: On **Windows**, for the ``.pro`` file to be compiled successfully, it is required - to run ``prepare_r2.bat`` beforehand. + to run ``prepare_rizin.bat`` beforehand. Compiling on Linux / macOS ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -244,7 +244,7 @@ Note that there are some major building options available: Cutter binary release options, not needed for most users and might not work easily outside CI environment: * ``CUTTER_ENABLE_CRASH_REPORTS`` is used to compile Cutter with crash handling system enabled (Breakpad). -* ``CUTTER_ENABLE_DEPENDENCY_DOWNLOADS`` Enable downloading of dependencies. Setting to OFF doesn't affect any downloads done by r2 build. This option is used for preparing Cutter binary release packges. Turned off by default. +* ``CUTTER_ENABLE_DEPENDENCY_DOWNLOADS`` Enable downloading of dependencies. Setting to OFF doesn't affect any downloads done by Rizin build. This option is used for preparing Cutter binary release packges. Turned off by default. * ``CUTTER_PACKAGE_DEPENDENCIES`` During install step include the third party dependencies. This option is used for preparing Cutter binary release packges. @@ -305,12 +305,12 @@ containing bin/, lib/, include/, etc.) and specify it to CMake using rm CMakeCache.txt # the cache may be polluted with unwanted libraries found before cmake -DCMAKE_PREFIX_PATH=/opt/Qt/5.9.1/gcc_64 .. -* **Radare2's libr_*.so cannot be found when running Cutter** +* **Rizin's librz_*.so cannot be found when running Cutter** - ./Cutter: error while loading shared libraries: libr_lang.so: cannot open shared object file: No such file or directory + ./Cutter: error while loading shared libraries: librz_lang.so: cannot open shared object file: No such file or directory -The exact r2 .so file that cannot be found may vary. On some systems, the linker by default uses RUNPATH instead of RPATH which is incompatible with the way r2 is currently compiled. It results in some of the r2 libraries not being found when running cutter. You can verify if this is the problem by running `ldd ./Cutter`. If all the r2 libraries are missing you have a different problem. -The workaround is to either add the `--disable-new-dtags` linker flag when compiling Cutter or add the r2 installation path to LD_LIBRARY_PATH environment variable. +The exact Rizin .so file that cannot be found may vary. On some systems, the linker by default uses RUNPATH instead of RPATH which is incompatible with the way Rizin is currently compiled. It results in some of the Rizin libraries not being found when running cutter. You can verify if this is the problem by running `ldd ./Cutter`. If all the Rizin libraries are missing you have a different problem. +The workaround is to either add the `--disable-new-dtags` linker flag when compiling Cutter or add the Rizin installation path to LD_LIBRARY_PATH environment variable. :: @@ -320,7 +320,7 @@ The workaround is to either add the `--disable-new-dtags` linker flag when compi rz_util/rz_annotated_code.h: No such file or directory -If you face an error where some header file starting with ``r_`` is missing, you should check the **radare2** submodule and +If you face an error where some header file starting with ``rz_`` is missing, you should check the **rizin** submodule and make sure it is in sync with upstream **Cutter** repo. Simply run: :: @@ -329,9 +329,9 @@ make sure it is in sync with upstream **Cutter** repo. Simply run: * **rz_core development package not found** -If you installed radare2 and still encounter this error, it could be that your +If you installed Rizin and still encounter this error, it could be that your ``PATH`` environment variable is set improperly (doesn’t contain -``/usr/local/bin``). You can fix this by adding the radare2 installation dir to +``/usr/local/bin``). You can fix this by adding the Rizin installation dir to your ``PATH`` variable. macOS specific solutions: @@ -344,13 +344,13 @@ encounter any problems. You can also try: -- ``PKG_CONFIG_PATH=$HOME/bin/prefix/radare2/lib/pkgconfig qmake`` -- ``PKG_CONFIG_PATH=$HOME/cutter/radare2/pkgcfg qmake`` (for a newer - version and if the radare2 submodule is being built and used) +- ``PKG_CONFIG_PATH=$HOME/bin/prefix/rizin/lib/pkgconfig qmake`` +- ``PKG_CONFIG_PATH=$HOME/cutter/rizin/pkgcfg qmake`` (for a newer + version and if the rizin submodule is being built and used) .. image:: images/cutter_path_settings.png -You can also install radare2 into ``/usr/lib/pkgconfig/`` and then +You can also install Rizin into ``/usr/lib/pkgconfig/`` and then add a variable ``PKG_CONFIG_PATH`` with the value ``/usr/lib/pkgconfig/``. * **macOS libjpeg error** diff --git a/docs/source/contributing/code/development-guidelines.rst b/docs/source/contributing/code/development-guidelines.rst index 6e2ee9c0..7c2316c4 100644 --- a/docs/source/contributing/code/development-guidelines.rst +++ b/docs/source/contributing/code/development-guidelines.rst @@ -12,7 +12,7 @@ Common Usage CutterCore Class ~~~~~~~~~~~~~~~~ -This is the main class where every link with r2 is made. It is *unique* +This is the main class where every link with Rizin is made. It is *unique* across the whole process. To access it, simply call ``Core()``. Example: @@ -21,26 +21,26 @@ Example: Core()->getOffset(); -Calling a radare2 Command +Calling a Rizin Command ~~~~~~~~~~~~~~~~~~~~~~~~~ -There are multiple ways to call a radare2 command: +There are multiple ways to call a Rizin command: - ``CutterCore::cmdj()`` - To be used with json commands like ``cmdj("agj")`` or ``cmdj("aflj")``. - This is the command we used to fetch structured data from radare2. + This is the command we used to fetch structured data from Rizin. -- ``CutterCore::cmdRaw()`` - Executes a single radare2 command - without going through radare2 shell functionality like output redirects, grep, and multiple command parsing. +- ``CutterCore::cmdRaw()`` - Executes a single Rizin command + without going through Rizin shell functionality like output redirects, grep, and multiple command parsing. The command then returns its output. This should be used when a command doesn't have output or the output should be handled as-is. If possible, using the JSON variation with ``cmdj`` is always preferred. -- ``CutterCore::cmdRawAt(,
)`` - Executes a single radare2 command in a given address and returns the output. This helps avoiding weird strings concatenation like ``cmd("ph " + hash + " @ " + QString::num(address))``. +- ``CutterCore::cmdRawAt(,
)`` - Executes a single Rizin command in a given address and returns the output. This helps avoiding weird strings concatenation like ``cmd("ph " + hash + " @ " + QString::num(address))``. - ``CutterCore::cmd()`` - *(Discouraged)* Only use it when ``cmdj`` or ``cmdRaw`` cannot be used. This is used for complex commands using concatenation of several commands (``px 5; pd 7; afl;``), for grepping (``pd 5~call``). for commands inside commands (``?e `afn.```) and so on. This is also used when the output is complex and is not parsed correctly in ``cmdRaw``. Make sure to carefully sanitize user-controlled variables that are passed to the command, to avoid unexpected command injections. -Generally, if one needs to retrieve information from a radare2 command, it +Generally, if one needs to retrieve information from a Rizin command, it is preferred to use the JSON API. Example: @@ -52,7 +52,7 @@ Example: Seek the Current File ~~~~~~~~~~~~~~~~~~~~~ -To modify radare2 seek use ``CutterCore::seek(const RVA offset)``. This +To modify Rizin 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")``; @@ -72,7 +72,7 @@ Creating a Widget ~~~~~~~~~~~~~~~~~ Make sure to connect the ``CutterCore::seekChanged(RVA offset)`` signal -so your widget refreshes its output when radare2 seek is modified +so your widget refreshes its output when Rizin seek is modified (switching to another function, etc.). Coding Style @@ -225,10 +225,10 @@ Updating the Git Submodules ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Git submodules play a major part in Cutter. This, because Cutter is powered -by radare2, its parent project, and it tries to stay up-to-date with its +by Rizin, its parent project, and it tries to stay up-to-date with its recent version, which allows us to implement new features, and enjoy bug -fixes and performance improvements on radare2. Often, we need to update -the radare2 submodule or the others, to push their most recent +fixes and performance improvements on Rizin. Often, we need to update +the Rizin submodule or the others, to push their most recent version to Cutter. You can view the list of all the submodules from the cutter root folder with: @@ -246,16 +246,16 @@ cutter root folder: git add submodule_name_1 submodule_name_2 git commit -m "Update submodules" -More likely, you'll only need to update the radare2 submodule. +More likely, you'll only need to update the *rizin* submodule. In order to update one submodule individually, use the following code: .. code:: sh - cd radare2 + cd rizin git checkout master && git pull cd .. - git add radare2 - git commit -m "Update radare2 submodule" + git add rizin + git commit -m "Update rizin submodule" Useful Resources (Qt Development) diff --git a/docs/source/contributing/code/getting-started.rst b/docs/source/contributing/code/getting-started.rst index 77925dd5..abec6231 100644 --- a/docs/source/contributing/code/getting-started.rst +++ b/docs/source/contributing/code/getting-started.rst @@ -1,12 +1,12 @@ Contributing code to Cutter -============================ +=========================== Thank you so much for your interest in contributing to Cutter! Contributors like you are a treasured resource for Cutter and their contributions have made the project what it is. And so, we appreciate everyone who gives the community the gift of their time <3. The following section in our documentation is *not* intended to be comprehensive but rather a quick guide to walk you through the basic flow of contributing to Cutter. For more thorough documentation, follow the links on this page and read our Development Guidelines. Clone and compile Cutter -------------------------- +------------------------ The first step before starting to add code to Cutter is to build it on your environment. Whether it is Linux, Windows, or macOS, we have you covered and detailed the instructions to compile Cutter on our :doc:`/building`. Once you are done and Cutter is built successfully, test that it works correctly and continue to the next steps. .. tip:: @@ -18,42 +18,42 @@ The first step before starting to add code to Cutter is to build it on your envi Find something to work on --------------------------- +------------------------- Some will reach this page with a clear idea of what issue they want to fix or what feature they wish to implement. But some would simply want to help Cutter getting better while doing open-source, without having a specific thing in mind. If you already have something in mind - great! Move forward to the next section. If you don't have anything specific, stick with us a little bit more. -The issues and the feature-requests of Cutter are listed and tracked on our `Github Issues `_ page. Don't get scared by the number of issues open, we will learn how to filter them to find those which fit you best. +The issues and the feature-requests of Cutter are listed and tracked on our `Github Issues `_ page. Don't get scared by the number of issues open, we will learn how to filter them to find those which fit you best. .. tip:: **Fix your pet peeve!** Anything specific that annoys you about Cutter? Fantastic! This can be a great place to start. Organizing issues -******************* +***************** In order to organize the hundreds of Issues opened on Cutter, we use several features of Github for project management. Get yourself familiar with the following features, it will help you filter the issues. Labels -^^^^^^^^ -Tagging issues and pull requests with labels allows us to quickly search for them later. We use labels to describe the type of the issue, the feature it belongs to, the difficulty, and even its priority. We recommend you to start from issues labeled as `good-first-issue `_. These issues were tagged by us as suitable for new contributors. +^^^^^^ +Tagging issues and pull requests with labels allows us to quickly search for them later. We use labels to describe the type of the issue, the feature it belongs to, the difficulty, and even its priority. We recommend you to start from issues labeled as `good-first-issue `_. These issues were tagged by us as suitable for new contributors. Projects -^^^^^^^^^^ -We use `project boards `_ to gather together tasks and issues for specific features or problems. For example, we have dedicated project boards for Debugger, Hexdump widget, Decompiler widget, and High DPI support. If you are interested to take part in developing a major feature, or you want to get a broader look at a progress of a specific part in Cutter, this can be a good place to visit. +^^^^^^^^ +We use `project boards `_ to gather together tasks and issues for specific features or problems. For example, we have dedicated project boards for Debugger, Hexdump widget, Decompiler widget, and High DPI support. If you are interested to take part in developing a major feature, or you want to get a broader look at a progress of a specific part in Cutter, this can be a good place to visit. Milestones -^^^^^^^^^^^^ +^^^^^^^^^^ -When starting working on a new release, we gather together the bug and feature-requests that we consider of high-priority into a `Milestone `_. If you want to work on a feature or fix a bug that is needed and prioritized for the next release, then check out the open Milestone,. +When starting working on a new release, we gather together the bug and feature-requests that we consider of high-priority into a `Milestone `_. If you want to work on a feature or fix a bug that is needed and prioritized for the next release, then check out the open Milestone,. Assigning Issues -^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^ Before choosing an issue to work on, make sure it is not assigned to anyone. If it is, you can comment and ask if this person is intended to work on the issue. Some assigned issues are abandoned by their assignee and can be picked up by other contributors. Get familiar with the current situation ----------------------------------------- +--------------------------------------- Run Cutter and get familiar with how the functionality you want to modify works currently. For example, if it is a dialog, make sure you understand its role and how our users are using it. If it is a bug, try to repeat it using the instructions from the bug report. @@ -83,13 +83,13 @@ In the Pull Request template you will be required to add a "Test plan". For exam Repeat -------- +------ **Thank you!** You've made your very first contribution, and Cutter is better for it. But don't stop now. Go back to the first steps, as there is plenty more to do. A mentor or other developers might suggest a new issue for you to work on. More Information ------------------ +---------------- .. important:: We're always in the process of improving the information on this page for newcomers to the Cutter. Please help us by suggesting improvements and tell us about the information that this page lacks. diff --git a/docs/source/contributing/code/ide-setup.rst b/docs/source/contributing/code/ide-setup.rst index 8f09cacb..e0866302 100644 --- a/docs/source/contributing/code/ide-setup.rst +++ b/docs/source/contributing/code/ide-setup.rst @@ -10,7 +10,7 @@ Everyone has their own preferences for their favorite IDE or code editor. There are no strict requirements for using a specific one for Cutter development. Any IDE with good CMake integration should work well. -For most development builds, unless you are working on packaging issues, it is recommended to use ``CUTTER_USE_BUNDLED_RADARE2=ON`` Cmake option. It is the easiest way to ensure that a compatible r2 version is used, and helps you deal with different versions of radare2 when working with multiple Cutter branches. On Linux, in case you have multiple r2 versions without ``CUTTER_USE_BUNDLED_RADARE2``, the ``PKG_CONFIG_PATH`` environment variable can be used to select the desired radare2 installation. +For most development builds, unless you are working on packaging issues, it is recommended to use ``CUTTER_USE_BUNDLED_RIZIN=ON`` Cmake option. It is the easiest way to ensure that a compatible Rizin version is used, and helps you deal with different versions of Rizin when working with multiple Cutter branches. On Linux, in case you have multiple Rizin versions without ``CUTTER_USE_BUNDLED_RIZIN``, the ``PKG_CONFIG_PATH`` environment variable can be used to select the desired Rizin installation. While `Qt Creator`_ has a builtin visual form and widget editor, not having it in other IDEs is not a major problem. It is also available as a standalone tool called Qt Designer and you can configure the file associations so that ``.ui`` files are opened using it. Depending on the ``.ui`` file and changes you want to make, it is sometimes easier to perform them by editing the ``.ui`` file as a text file. Essentially, ``.ui`` files are XML files. Most code editors should have some support for XML highlighting and possibly block folding. @@ -25,7 +25,7 @@ Windows ------- Assuming you have a sufficiently powerful computer, a nice way of getting and configuring Qt for Cutter is to use `vcpkg `_. -For a quick test, the exact versions of libraries used by Cutter release packages can be obtained from `cutter-deps `_ but they don't contain debug +For a quick test, the exact versions of libraries used by Cutter release packages can be obtained from `cutter-deps `_ but they don't contain debug versions of libraries so they are not suitable for more serious Cutter development on Windows. Qt Creator @@ -41,7 +41,7 @@ Pros and Cons - builtin help for Qt API - builtin .ui file editor (Qt Designer - visual form editor) - builtin helper for displaying Qt types in the debugger -- Viewing source files that are not directly part of the project (R2 source code) is somewhat inconvenient. +- Viewing source files that are not directly part of the project (Rizin source code) is somewhat inconvenient. - The simplest way of installing on non-Linux operating systems require login with Qt account Project setup @@ -50,10 +50,10 @@ The following instructions were made based on version 4.12.4 of Qt Creator. The - Go to :menuselection:`File --> Open File or Project..` and select :file:`cutter/src/CMakeList.txt` - Select kit and press :guilabel:`Configure Project` -- Configuration step might fail due to r2 not being found, that's normal +- Configuration step might fail due to Rizin not being found, that's normal - Click :guilabel:`Projects` button with wrench icon on the left side of the screen - Click :menuselection:`Add --> Boolean` in the CMake section -- Enter ``CUTTER_USE_BUNDLED_RADARE2`` as a key name and change the value to ON. In earlier Qt Creator versions it is necessary to do this during the initial kit selection and configuration step. +- Enter ``CUTTER_USE_BUNDLED_RIZIN`` as a key name and change the value to ON. In earlier Qt Creator versions it is necessary to do this during the initial kit selection and configuration step. - Click :guilabel:`Apply Configuration Changes`:. The configuration should succeed now. In case of errors inspect the output log. Either in :menuselection:`Projects --> Code Style --> C++` or :menuselection:`Tools --> Options --> C++ --> Code Style` select :guilabel:`Qt [built-in]`. It should be selected by default unless you have used Qt Creator for other projects. Cutter Coding style is almost identical to Qt one. This will help with using correct indentation type and basic formatting without running code formatter. @@ -140,7 +140,7 @@ Pros and Cons Project setup ~~~~~~~~~~~~~ - Go to :menuselection:`File --> Open` and select the folder in which you cloned Cutter -- Go to :menuselection:`File --> Settings --> Build, Execution, Deployment --> CMake`. In the :guilabel:`CMake Options` field enter ``-DCUTTER_USE_BUNDLED_RADARE2=ON`` +- Go to :menuselection:`File --> Settings --> Build, Execution, Deployment --> CMake`. In the :guilabel:`CMake Options` field enter ``-DCUTTER_USE_BUNDLED_RIZIN=ON`` - Open :file:`cutter/src/CMakeLists.txt` using the project file list on the left side of the screen - A yellow bar with a message :guilabel:`CMake project is not loaded` should appear, click :guilabel:`Load CMake project` @@ -183,7 +183,7 @@ Project setup ~~~~~~~~~~~~~ - Open folder in which you cloned Cutter source using Visual Studio - Open CMake settings configurator using either :menuselection:`Project --> CMake Settings` or by clicking :guilabel:`Open the CMake Settings Editor` in the overview page. -- Check ``CUTTER_USE_BUNDLED_RADARE2`` option +- Check ``CUTTER_USE_BUNDLED_RIZIN`` option - If you are using vcpkg, Visual Studio should detect it automatically. The list of CMake options in the configurator should have some referring to vcpkg. If they are not there, specify the path to vcpkg toolchain file in the :guilabel:`CMake toolchain file` field. - If you are not using vcpkg, configure the path to Qt as mentioned in :ref:`windows CMake instructions`. You can specify the CMake flag in :guilabel:`CMake command arguments:` field. - To Ensure that VS debugger can display Qt types in a readable way, it is recommended to install `Qt Visual Studio Tools `_ plugin. It will create a :file:`Documents/Visual Studio 2019/Visualizers/qt5.natvis` file. Once :file:`qt5.natvis` has been created you can uninstall the plugin. diff --git a/docs/source/contributing/code/release-procedure.rst b/docs/source/contributing/code/release-procedure.rst index d2e7293a..7eff7acc 100644 --- a/docs/source/contributing/code/release-procedure.rst +++ b/docs/source/contributing/code/release-procedure.rst @@ -1,11 +1,11 @@ Release Procedure ================= -1. Update translations submodule `https://github.com/radareorg/cutter-translations`_ - 1. The latest archive from Crowdin should already be in the repository, if not make sure to merge any automated Pull Request from Crowdin (e.g. https://github.com/radareorg/cutter-translations/pull/9) +1. Update translations submodule `https://github.com/rizinorg/cutter-translations`_ + 1. The latest archive from Crowdin should already be in the repository, if not make sure to merge any automated Pull Request from Crowdin (e.g. https://github.com/rizinorg/cutter-translations/pull/9) 2. Update submodule in cutter 2. If there is a desire to keep working in the master branch, create branch for the release and do all the following work there. -3. Lock r2ghidra and r2dec versions downloaded by packaging scripts. Specify a tag or commit hash. +3. Lock rzghidra and rzdec versions downloaded by packaging scripts. Specify a tag or commit hash. 4. Update version #. appveyor.yml #. docs/sourc/conf.py @@ -23,7 +23,7 @@ Release Procedure 10. Update version to 1.11.0 11. Create tag 12. Create release - * Fill the release notes in the Release description. Preparing release notes can begin earlier. Compare current master or release branch against previous release to find all the changes. Choose the most important ones. Don't duplicate the commit log. Release notes should be a summary for people who don't want to read whole commit log. Group related changes together under titles such as "New features", "Bug Fixes", "Decompiler", "radare2" and similar. + * Fill the release notes in the Release description. Preparing release notes can begin earlier. Compare current master or release branch against previous release to find all the changes. Choose the most important ones. Don't duplicate the commit log. Release notes should be a summary for people who don't want to read whole commit log. Group related changes together under titles such as "New features", "Bug Fixes", "Decompiler", "Rizin" and similar. 13. Prepare announcement tweets and messages to send in the Telegram group, reddit, and others. 14. Close milestone if there was one @@ -49,7 +49,7 @@ If it makes sense repeat the step multiple times at different offsets and click * The Disassembly widget shows proper disassembly. * Bundled plugins work * Open decompiler and select ghidra, it shows some C code at least for some functions - * Open r2dec in decompiler widget, make sure it shows code + * Open rzdec in decompiler widget, make sure it shows code * Test that sample python plugin works * Try debugger * Insert breakpoint in main diff --git a/docs/source/contributing/docs/getting-started.rst b/docs/source/contributing/docs/getting-started.rst index 230d4369..f624edda 100644 --- a/docs/source/contributing/docs/getting-started.rst +++ b/docs/source/contributing/docs/getting-started.rst @@ -1,5 +1,5 @@ Contributing documentation to Cutter -======================================= +==================================== If you reached this place you were probably looking to help and improve Cutter's documentation - Fantastic, welcome aboard! @@ -16,18 +16,18 @@ How can you help? The following sections suggest ways you can contribute to Cutter's documentation. The list isn't complete as the possibilities are limitless. -The source for this documentation is available in the `docs directory `_ on Cutter's repository. This source can be generated according to the steps described in the :ref:`building docs page`. When the docs are updated, they are generated and pushed directly to the website at . The source for the website and blog are available on the `cutter.re's repository `_ and are served from the ``gh-pages`` branch. +The source for this documentation is available in the `docs directory `_ on Cutter's repository. This source can be generated according to the steps described in the :ref:`building docs page`. When the docs are updated, they are generated and pushed directly to the website at . The source for the website and blog are available on the `cutter.re's repository `_ and are served from the ``gh-pages`` branch. .. tip:: Document what you wished to see. If you are a user of Cutter, try to think what things you would want to see documented when you started using the project. Sometimes, the best contributions are coming from your own needs. User documentation -^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^ The documentation for users describes how to use Cutter and what the different features in Cutter do. The possibilities for contributing are endless since there are so many features that weren't even described on our docs yet. To contribute to our user documentation, all you need to do is pick a subject, widget, or functionality and document it. Describe the different visual components, how to use them, and what this feature even does. Common Errors and Troubleshooting -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As our community gets bigger, more and more people are using, installing or building Cutter on different setups. Naturally, different environments might cause different issues. The :ref:`common issues` section in our docs aims to go over the most popular issues that you might face while using Cutter and the :ref:`building errors troubleshooting` section goes over common errors that you might face while building Cutter from sources. These docs sections also explain what causes these issues and how to solve them. @@ -35,17 +35,17 @@ If you know of such a common issue, whether you faced it yourself or noticed it Developers documentation -^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^ The documentation for Cutter developers aims to instruct new contributors on how to get started with developing to Cutter's codebase. It also describes best practices and development guidelines for all developers in the project. Think you have something to add to the developers' docs? We would love you to contribute. API documentation -^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^ The documentation for Cutter's API is an important reference for Cutter developers as well as Plugin developers. It thoroughly describes for developers how some functions and features work. While some of the functions are thoroughly documented, most of them aren't. Any help with improving these documentations will be blessed. Blog posts -^^^^^^^^^^^^^ +^^^^^^^^^^ We would love to see people writing and sharing their experiences with Cutter. Whether you are solving CTF challenges with Cutter, analyzing malware, finding vulnerabilities, or working on personal projects - we would love to see these published. If you have a personal blog, we would be proud to share and retweet your Cutter-related publications on our profiles, bringing you more engagement and followers. If you don't have a personal blog, we would love to host your publication on our community blog over at https://cutter.re/blog. diff --git a/docs/source/contributing/plugins/getting-started.rst b/docs/source/contributing/plugins/getting-started.rst index 3a321b97..de5365ac 100644 --- a/docs/source/contributing/plugins/getting-started.rst +++ b/docs/source/contributing/plugins/getting-started.rst @@ -139,11 +139,11 @@ Extend the code as follows: # ... -We can access the data by calling radare2 commands and utilizing their output. +We can access the data by calling Rizin commands and utilizing their output. This is done by using the two functions ``cmd()`` and ``cmdj()``, which behave just as they -do in `r2pipe `_. +do in `rz-pipe `_. -Many commands in radare2 can be suffixed with a ``j`` to return JSON output. +Many commands in Rizin can be suffixed with a ``j`` to return JSON output. ``cmdj()`` will automatically deserialize the JSON into python dicts and lists, so the information can be easily accessed. diff --git a/docs/source/index.rst b/docs/source/index.rst index 24fd4903..ebb33a5d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,7 +1,7 @@ Cutter ====== -Cutter is a Qt and C++ GUI for radare2. Its goal is to provide an advanced, +Cutter is a Qt and C++ GUI for Rizin. Its goal is to provide an advanced, customizable and FOSS reverse-engineering platform while keeping the user experience in mind. Cutter was created by reverse engineers for reverse engineers. @@ -14,7 +14,7 @@ Getting Cutter Cutter is available for all major platforms. You can download the latest release from -`here `__. +`here `__. - **macOS**: Download the ``.dmg`` file and install it. - **Windows**: Download the ``.zip`` archive and extract it. @@ -35,9 +35,9 @@ Need help? You can contact the *Cutter* developers and community on: -- Telegram: https://t.me/r2cutter +- Telegram: https://t.me/cutter_re - #cutter on irc.freenode.net -- Twitter: https://twitter.com/r2gui +- Twitter: https://twitter.com/cutter_re Want to help the project? ------------------------- diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index b0f7154c..0f755285 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -6,7 +6,7 @@ If you are unsure of which language to choose, starting with Python is strongly it provides a faster and simpler workflow. If you plan to implement support for a new file format or architecture, Cutter plugins are not the correct approach. -Instead, you will want to implement a radare2 plugin, which is documented `here `_. +Instead, you will want to implement a Rizin plugin, which is documented `here `_. Loading and Overview diff --git a/docs/source/user-docs.rst b/docs/source/user-docs.rst index f90994ed..21f5e2b4 100644 --- a/docs/source/user-docs.rst +++ b/docs/source/user-docs.rst @@ -1,9 +1,9 @@ User Documentation -======================= +================== This page contains information about the different menus in Cutter. -Cutter is an advanced reverse engineering platform powered by radare2. +Cutter is an advanced reverse engineering platform powered by Rizin. This user's guide provides detailed information on how to use Cutter. The documentation for users is still on its early stages and will be improved over time. diff --git a/docs/source/user-docs/common-issues.rst b/docs/source/user-docs/common-issues.rst index 520108f7..f9d6646a 100644 --- a/docs/source/user-docs/common-issues.rst +++ b/docs/source/user-docs/common-issues.rst @@ -8,7 +8,7 @@ AppImage Crashes If the Linux AppImage binary crashes upon startup, make sure your ``LD_LIBRARY_PATH`` environment variable is empty. -For a detailed explanation, see the issue `#579 `__ +For a detailed explanation, see the issue `#579 `__ Keyboard Layout Issue --------------------- @@ -21,7 +21,7 @@ not be enough and require a more advanced Xorg configuration. Initial Analysis takes a long time or Cutter UI freezes ------------------------------------------------------- -Cutter and radare2 currently don't work very well with large and very large binaries. +Cutter and Rizin currently don't work very well with large and very large binaries. The exact limits depend on the content of the binary, but roughly a few MB can be considered large and may take a few minutes to analyze. More than 100MB is very large, analysis with default settings will likely take a very long time and it might occasionally diff --git a/docs/source/user-docs/features.rst b/docs/source/user-docs/features.rst index 80a81876..b10c13d4 100644 --- a/docs/source/user-docs/features.rst +++ b/docs/source/user-docs/features.rst @@ -1,11 +1,11 @@ Features -============= +======== This section in the user docs gives a more detailed information about different features in Cutter. These are the different utilities and views that can be used and controlled by you during your session. As more familiar and comfort you feel with the different features in Cutter, the more efficient and effective you are during your reverse-engineering experience. Decompiler -------------- +---------- A decompiler is a program that will analyze binaries and attempt to create a high-level representation of the machine code in it. In other words, it tries to reconstruct the source code from which the binary was compiled in the first place. Here's an image that compares one of the decompiler Cutter supports with the Cutter's disassembler. @@ -13,7 +13,7 @@ Here's an image that compares one of the decompiler Cutter supports with the Cut .. image:: ../images/decompiler_vs_disassembly.png -Cutter provides an interface that supports plugins of multiple decompilers including Ghidra, RetDec and R2Dec. The interface receives data from the decompiler and presenting the decompiler code in a context-sensitive decompiler widget. Check the `Decompilers `_ section on our Plugins repository to know more about the decompilers we support. +Cutter provides an interface that supports plugins of multiple decompilers including Ghidra, RetDec and R2Dec. The interface receives data from the decompiler and presenting the decompiler code in a context-sensitive decompiler widget. Check the `Decompilers `_ section on our Plugins repository to know more about the decompilers we support. Out of the decompiler plugins that we support, the one that's officially maintained by the developers of Cutter is R2Ghidra. :doc:`Click here ` to learn more about the functionalities we provide in the decompiler. diff --git a/docs/source/user-docs/menus/menu-bar/file-menu.rst b/docs/source/user-docs/menus/menu-bar/file-menu.rst index 9537e16f..f575f9de 100644 --- a/docs/source/user-docs/menus/menu-bar/file-menu.rst +++ b/docs/source/user-docs/menus/menu-bar/file-menu.rst @@ -76,9 +76,9 @@ Export to Code **Steps:** File -> Export as code -Run a radare2 Script +Run a Rizin Script ---------------------------------------- -**Description:** Cutter allows you to execute radare2 scripts to automate task or transfer information. Radare2 scripts are files that contain list of radare2 commands. The scripts can be created manually by you, or automatically generated by radare2 commands (which typically end with a star character. e.g. ``afl*``). +**Description:** Cutter allows you to execute Rizin scripts to automate task or transfer information. Rizin scripts are files that contain list of Rizin commands. The scripts can be created manually by you, or automatically generated by Rizin commands (which typically end with a star character. e.g. ``afl*``). Such a script can look like this: @@ -88,7 +88,7 @@ Such a script can look like this: ?v 10+5 pdf @ main -**Steps:** File -> Run radare2 script +**Steps:** File -> Run Rizin script Quit Cutter ---------------------------------------- diff --git a/docs/source/user-docs/menus/menu-bar/view-menu.rst b/docs/source/user-docs/menus/menu-bar/view-menu.rst index 8465d4fe..5960e5d1 100644 --- a/docs/source/user-docs/menus/menu-bar/view-menu.rst +++ b/docs/source/user-docs/menus/menu-bar/view-menu.rst @@ -4,7 +4,7 @@ View Menu Refresh Contents ---------------------------------------- -**Description:** In some cases, not all the displayed information on Cutter's widgets will be up-to-date, for example - after defining a new function from the integrated radare2 console. By refreshing the contents, Cutter will fetch the most up to date information from the session and will update the different views. +**Description:** In some cases, not all the displayed information on Cutter's widgets will be up-to-date, for example - after defining a new function from the integrated Rizin console. By refreshing the contents, Cutter will fetch the most up to date information from the session and will update the different views. ***Note:** In the future, Cutter will be aware to any underlying change and will update everything automatically. This is currently a work-in-progress.* diff --git a/docs/source/user-docs/menus/menu-bar/windows-menu.rst b/docs/source/user-docs/menus/menu-bar/windows-menu.rst index 256836f6..66e6e97b 100644 --- a/docs/source/user-docs/menus/menu-bar/windows-menu.rst +++ b/docs/source/user-docs/menus/menu-bar/windows-menu.rst @@ -31,7 +31,7 @@ Show Functions Show Decompiler ---------------------------------------- -**Description:** Cutter releases are shipped with two decompilers by default - [r2ghidra](https://github.com/radareorg/r2ghidra-dec) and [r2dec](https://github.com/radareorg/r2dec-js). The Decompiler view will display the decompilation of the current function. The widget is interactive and support address-syncing, renaming, re-typing and more. Cutter can be extended with more decompilers. +**Description:** Cutter releases are shipped with two decompilers by default - [rz-ghidra](https://github.com/rizinorg/rz-ghidra) and [rz-dec](#) which will be available soon. The Decompiler view will display the decompilation of the current function. The widget is interactive and support address-syncing, renaming, re-typing and more. Cutter can be extended with more decompilers. **Steps:** Windows -> Decompiler @@ -96,8 +96,8 @@ Show Comments Show Console ---------------------------------------- -**Description:** Open the integrated radare2 console. This will allow you to execute radare2 commands straight from Cutter. +**Description:** Open the integrated Rizin console. This will allow you to execute Rizin commands straight from Cutter. **Steps:** Windows -> Console -**Shortcut:** :kbd:`:` or :kbd:`Ctrl` + :kbd:`\`` \ No newline at end of file +**Shortcut:** :kbd:`:` or :kbd:`Ctrl` + :kbd:`\`` diff --git a/docs/source/user-docs/preferences/analysis.rst b/docs/source/user-docs/preferences/analysis.rst index 55442a03..c1396d7a 100644 --- a/docs/source/user-docs/preferences/analysis.rst +++ b/docs/source/user-docs/preferences/analysis.rst @@ -1,7 +1,7 @@ Analysis Options ================ -Cutter will use the underlying radare2 analysis options to analyze a binary. These options are usually +Cutter will use the underlying Rizin analysis options to analyze a binary. These options are usually configured when the binary is first loaded. However, they can be later changed using the Analysis dialog, and a new analysis that takes these options into account can then be performed. @@ -11,10 +11,10 @@ Analysis Dialog .. image:: ../../images/analysis_dialog.png :alt: Analysis dialog -**Description:** The Analysis dialog allows setting some radare2's analysis options. The supported options are described +**Description:** The Analysis dialog allows setting some Rizin's analysis options. The supported options are described below. -Clicking on the "Analyze Program" button will trigger an analysis of the current binary with radare2's ``aaa`` +Clicking on the "Analyze Program" button will trigger an analysis of the current binary with Rizin's ``aaa`` command, taking into account the configured values of the analysis options. **Steps to open:** ``Edit -> Preferences -> Analysis``