1Development environment setup 2============================= 3 4This page contains recommendations and tips on how to better setup different IDEs for Cutter development. 5 6 7General advice 8-------------- 9Everyone has their own preferences for their favorite IDE or code editor. 10There are no strict requirements for using a specific one for Cutter development. 11Any IDE with good CMake integration should work well. 12 13For 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. 14 15While `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. 16 17The following instructions and recommendations assume that you have already download Cutter source and obtained required dependencies as described in :doc:`/building`. 18 19Linux 20----- 21 22On a rolling-release distribution or a somewhat recent version of traditional distributions like Ubuntu 18.04, it should be possible to get all the dependencies from the official repository. There might be some problems with PySide2 and Shiboken2 but it can be easily disabled and isn't necessary for most work on Cutter. Don't try to install PySide using pip. 23 24Windows 25------- 26 27Assuming you have a sufficiently powerful computer, a nice way of getting and configuring Qt for Cutter is to use `vcpkg <https://github.com/Microsoft/vcpkg>`_. 28For a quick test, the exact versions of libraries used by Cutter release packages can be obtained from `cutter-deps <https://github.com/radareorg/cutter-deps/releases>`_ but they don't contain debug 29versions of libraries so they are not suitable for more serious Cutter development on Windows. 30 31Qt Creator 32---------- 33QT Creator is an open-source IDE made by the same developers as Qt. 34 35Even though Cutter has qmake project cutter.pro it is recommended to use the CMake project in QTCreator. 36QTCreator support for CMake is as good as qmake one but not all Cutter project configuration options are available in qmake project and in future Cutter qmake project might be removed. 37 38Pros and Cons 39~~~~~~~~~~~~~ 40 41- builtin help for Qt API 42- builtin .ui file editor (Qt Designer - visual form editor) 43- builtin helper for displaying Qt types in the debugger 44- Viewing source files that are not directly part of the project (R2 source code) is somewhat inconvenient. 45- The simplest way of installing on non-Linux operating systems require login with Qt account 46 47Project setup 48~~~~~~~~~~~~~ 49The following instructions were made based on version 4.12.4 of Qt Creator. The steps might slightly differ between the versions. 50 51- Go to :menuselection:`File --> Open File or Project..` and select :file:`cutter/src/CMakeList.txt` 52- Select kit and press :guilabel:`Configure Project` 53- Configuration step might fail due to r2 not being found, that's normal 54- Click :guilabel:`Projects` button with wrench icon on the left side of the screen 55- Click :menuselection:`Add --> Boolean` in the CMake section 56- 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. 57- Click :guilabel:`Apply Configuration Changes`:. The configuration should succeed now. In case of errors inspect the output log. 58 59Either 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. 60 61To configure AStyle for formatting a file go to :menuselection:`Tools --> Options --> Beautifier --> Artistic Style`. If necessary, specify the path to astyle executable. The :guilabel:`Use file \*.astylerc defined in project files` option doesn't seem to be working reliably so it is necessary to use :guilabel:`Use specific config file` option. Cutter astyle configuration is stored in :file:`cutter/src/Cutter.astylerc`. 62 63Changing CMake configuration 64~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 65Click on the "Projects" button on the left side of the screen and then select "Build". All the project CMake options are listed and can be edited there in a graphical editor. 66 67Editing Qt .ui files 68~~~~~~~~~~~~~~~~~~~~ 69Double-clicking a ``.ui`` file in a file list opens it inside a visual editor. If you want to make changes that are easier to do by editing ``.ui`` file as text - right-click the file and select :menuselection:`Open With --> Plain Text Editor`. Switching from visual form editor back to code editor mode will open the ``.ui`` file in read-only mode with the following warning "This file can only be edited in Design mode". To edit use the same steps as described before. 70 71VS Code 72------- 73`VS Code <https://github.com/Microsoft/vscode>`_ is an open-source code editor made by Microsoft. 74 75Pros and Cons 76~~~~~~~~~~~~~ 77 78- A large number of plugins 79- A good fallback mechanism for files that are not directly part of a project. 80 81Recommended plugins 82~~~~~~~~~~~~~~~~~~~ 83- `C/C++ <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools>`_ - The official C++ support plugin made by Microsoft 84- `CMake Tools <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools>`_ - Provides CMake project integration. Originally developed by vector-of-bool and currently maintained by Microsoft. 85- `CMake <https://marketplace.visualstudio.com/items?itemName=twxs.cmake>`_ - CMake language support when editing CMake files. Does not replace the previous CMake plugin. They provide non-overlapping functionality and should be used together. 86 87Project setup 88~~~~~~~~~~~~~ 89- :menuselection:`File --> Open Folder...` and select the folder in which you cloned Cutter 90- Install the recommended plugins. 91- Once the `CMake Tools` plugin is installed, in the corner you will see a popup asking you "Would you like to configure project 'cutter'? Source: CMake Tools (Extension)". Click Yes. 92- In the kit selection popup, choose :guilabel:`[Unspecified]` unless you have more specific needs. 93- If you initially dismissed the configuration window or didn't have the plugins installed yet - open command-palette using :kbd:`Ctrl-Shift-P` and select :guilabel:`Cmake: Configure` 94 95Changing CMake configuration 96~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 97After the first configuration :kbd:`Ctrl-Shift-P`/:guilabel:`CMake: Edit CMake Cache` opens a text editor with all CMake options. Cutter specific ones mostly start with "CUTTER". 98 99.. note:: 100 ``CUTTER_USE_BUNDLED_RADARE2`` option is also defined in ``.vscode/settings.json`` file and it will be overridden from there. It is set to ``ON`` by default as it is recommended during development. 101 102.. _vscode-debug-setup: 103 104Building, Running, Debugging 105~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 106Build and running commands are available in the status bar at the bottom and in the Command Palette menu (:kbd:`Ctrl-Shift-P`) named ``CMake: Build F7``, ``CMake: Run Without Debugging Shift+F5``, and ``CMake Debug Ctrl + F5``. 107Shortcuts can be viewed in the :kbd:`Ctrl-Shift-P` menu. They don't match default VS Code ones since those depend on :file:`tasks.json``. 108 109Running and debugging launches the executable without any arguments. Command-line arguments can be passed to the debug 110executable by creating a ``.vscode/launch.json`` configuration. Read the `documentation <https://code.visualstudio.com/docs/cpp/launch-json-reference>`_ for more information. Instead of creating :file:`launch.json` manually it can be created from template: :kbd:`Ctrl-Shift-P`/:menuselection:`Debug: Select and Start Debugging --> Add configuration.. --> C,C++: (gdb) Launch`. 111 112To setup gdb pretty printers for Qt types on Linux, download the scripts from `Kdevelop <https://github.com/KDE/kdevelop/tree/master/plugins/gdb/printers>`_. In the :file:`~/.gdbinit` file add the following code: 113 114 115.. code-block:: python 116 117 python 118 import sys 119 120 sys.path.insert(0, '/path/to/folder/with/pretty_printer_scripts') 121 from qt import register_qt_printers 122 register_qt_printers (None) 123 124 end 125 set print pretty 1 126 127 128CLion 129----- 130`CLion <https://www.jetbrains.com/clion/>`_ is a C and C++ IDE from the popular software development tool maker - JetBrains. 131 132 133Pros and Cons 134~~~~~~~~~~~~~ 135 136- Medium amount of plugins, many first-party plugins made by JetBrains for their IntelliJ based IDE family 137- There is no free version 138- Takes some time to analyze the files after opening a project. Switching between .cpp and corresponding .h file may for the first time may take a few seconds. 139 140Project setup 141~~~~~~~~~~~~~ 142- Go to :menuselection:`File --> Open` and select the folder in which you cloned Cutter 143- Go to :menuselection:`File --> Settings --> Build, Execution, Deployment --> CMake`. In the :guilabel:`CMake Options` field enter ``-DCUTTER_USE_BUNDLED_RADARE2=ON`` 144- Open :file:`cutter/src/CMakeLists.txt` using the project file list on the left side of the screen 145- A yellow bar with a message :guilabel:`CMake project is not loaded` should appear, click :guilabel:`Load CMake project` 146 147Changing CMake configuration 148~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 149Go to :menuselection:`File --> Settings --> Build,Execution,Deployment --> CMake`. CMake options are specified the same way as on command-line ``-DOPTION_NAME=VALUE``. 150 151Building, Running, Debugging 152~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 153Follow the `Clion documentation <https://www.jetbrains.com/help/clion/qt-tutorial.html#debug-renderers>`_ for how to configure Qt type debugger renderers. If you are using the MSVC toolchain 154it can use :file:`qt5.natvis`. In rest of the cases you can use ``.gdbinit`` or ``..ldbinit`` based approach similar to one described for :ref:`VSCode setup<vscode-debug-setup>` 155 156Editing Qt .ui files 157~~~~~~~~~~~~~~~~~~~~ 158Default CLion behavior for opening .ui files is `somewhat buggy <https://youtrack.jetbrains.com/issue/CPP-17197>`_. Double-clicking the file does nothing, but it can be opened by dragging it to the text editor side. 159This can be somewhat improved by changing `file association <https://www.jetbrains.com/help/clion/creating-and-registering-file-types.html>`_. Open :menuselection:`File --> Settings --> Editor --> File Types` and change type association of \*.ui files from :guilabel:`Qt UI Designer Form` to either "XML" or :guilabel:`Files Opened in Associated Applications`. 160The first one will open it within CLion as an XML file and the second will use the operating system configuration. 161 162Visual Studio 163------------- 164Visual Studio Community edition is available for free and can be used for contributing to open source projects. 165 166It is recommended to use the latest Visual Studio version 2019 because it has the best CMake integration. 167Older VS versions can be used but CMake integration isn't as good. With those, it might be better to generate Visual Studio 168project from CMake project using the command-line or :command:`cmake-gui` and opening the generated Visual Studio project instead of opening the 169CMake project directly. 170 171Visual Studio supports many different languages and use-cases. Full installation takes a lot of space. To keep the size minimal during installation 172select only component called "Desktop development with C++". Don't worry too much about missing something. 173Additional components can be later added or removed through the VS installer which also serves as an updater and package manager for Visual Studio components. 174 175Pros and Cons 176~~~~~~~~~~~~~ 177- good debugger 178- medium amount of plugins 179- completely closed source 180- Windows only 181 182Project setup 183~~~~~~~~~~~~~ 184- Open folder in which you cloned Cutter source using Visual Studio 185- Open CMake settings configurator using either :menuselection:`Project --> CMake Settings` or by clicking :guilabel:`Open the CMake Settings Editor` in the overview page. 186- Check ``CUTTER_USE_BUNDLED_RADARE2`` option 187- 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. 188- If you are not using vcpkg, configure the path to Qt as mentioned in :ref:`windows CMake instructions<building:Building on Windows>`. You can specify the CMake flag in :guilabel:`CMake command arguments:` field. 189- To Ensure that VS debugger can display Qt types in a readable way, it is recommended to install `Qt Visual Studio Tools <https://marketplace.visualstudio.com/items?itemName=TheQtCompany.QtVisualStudioTools2019>`_ 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. 190 191Changing CMake configuration 192~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 193Open :menuselection:`Project --> CMake Settings`. CMake options can be modified either in graphical table editor, as a command-line flag or by switching to the JSON view. 194 195Editing Qt .ui files and Qt integration 196~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 197By default Visual Studio will open ``.ui`` files as XML text documents. You can configure to open it using Qt Designer by right-clicking and selecting :guilabel:`Open With...`. 198 199There is a Qt plugin for Visual Studio from Qt. It isn't very useful for Cutter development since it is aimed more at helping with Qt integration into Visual Studio projects. 200It doesn't do much for CMake based projects. The biggest benefit is that it automatically installs :file:`qt5.natvis` file for more readable displaying of Qt types in the debugger. 201