Skip to content

Commit 5d1f260

Browse files
committed
Improve gui/src/qt README.md
The current readme is a little bit outdated and contains some grammatical mistakes. This commit updates the doc so that: - It is easier to follow and is more informative - Fixes grammatical mistakes - Modernizes the Qt Creater setup instructions - Adds UNIX instructions for Qt Creator setup
1 parent f5cdc29 commit 5d1f260

File tree

1 file changed

+75
-46
lines changed

1 file changed

+75
-46
lines changed

src/qt/README.md

+75-46
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,124 @@
1-
This directory contains the BitcoinQT graphical user interface (GUI). It uses the cross-platform framework [Qt](https://www1.qt.io/developers/).
1+
This directory contains the source code for the Bitcoin Core graphical user interface (GUI). It uses the [Qt](https://www1.qt.io/developers/) cross-platform framework.
22

33
The current precise version for Qt 5 is specified in [qt.mk](/depends/packages/qt.mk).
44

55
## Compile and run
66

7-
See build instructions ([macOS](/doc/build-osx.md), [Windows](/doc/build-windows.md), [Unix](/doc/build-unix.md), etc).
7+
See build instructions: [Unix](/doc/build-unix.md), [macOS](/doc/build-osx.md), [Windows](/doc/build-windows.md), [FreeBSD](/doc/build-freebsd.md), [NetBSD](/doc/build-netbsd.md), [OpenBSD](/doc/build-openbsd.md)
8+
9+
When following your systems build instructions, make sure to install the `Qt` dependencies.
810

911
To run:
1012

1113
```sh
1214
./src/qt/bitcoin-qt
1315
```
1416

15-
## Files and directories
16-
17-
### forms
17+
## Files and Directories
1818

19-
Contains [Designer UI](https://doc.qt.io/qt-5.9/designer-using-a-ui-file.html) files. They are created with [Qt Creator](#using-qt-creator-as-ide), but can be edited using any text editor.
19+
#### forms/
2020

21-
### locale
21+
- A directory that contains [Designer UI](https://doc.qt.io/qt-5.9/designer-using-a-ui-file.html) files. These files specify the characteristics of form elements in XML. Qt UI files can be edited with [Qt Creator](#using-qt-creator-as-ide) or using any text editor.
2222

23-
Contains translations. They are periodically updated. The process is described [here](/doc/translation_process.md).
23+
#### locale/
2424

25-
### res
25+
- Contains translations. They are periodically updated and an effort is made to support as many languages as possible. The process of contributing translations is described in [doc/translation_process.md](/doc/translation_process.md).
2626

27-
Resources such as the icon.
27+
#### res/
2828

29-
### test
29+
- Contains graphical resources used to enhance the UI experience.
3030

31-
Tests.
31+
#### test/
3232

33-
### bitcoingui.(h/cpp)
33+
- Functional tests used to ensure proper functionality of the GUI. Significant changes to the GUI code normally require new or updated tests.
3434

35-
Represents the main window of the Bitcoin UI.
35+
#### bitcoingui.(h/cpp)
3636

37-
### \*model.(h/cpp)
37+
- Represents the main window of the Bitcoin UI.
3838

39-
The model. When it has a corresponding controller, it generally inherits from [QAbstractTableModel](https://doc.qt.io/qt-5/qabstracttablemodel.html). Models that are used by controllers as helpers inherit from other Qt classes like [QValidator](https://doc.qt.io/qt-5/qvalidator.html).
39+
#### \*model.(h/cpp)
4040

41-
ClientModel is used by the main application `bitcoingui` and several models like `peertablemodel`.
41+
- The model. When it has a corresponding controller, it generally inherits from [QAbstractTableModel](https://doc.qt.io/qt-5/qabstracttablemodel.html). Models that are used by controllers as helpers inherit from other Qt classes like [QValidator](https://doc.qt.io/qt-5/qvalidator.html).
42+
- ClientModel is used by the main application `bitcoingui` and several models like `peertablemodel`.
4243

43-
### \*page.(h/cpp)
44+
#### \*page.(h/cpp)
4445

45-
A controller. `:NAMEpage.cpp` generally includes `:NAMEmodel.h` and `forms/:NAME.page.ui` with a similar `:NAME`.
46+
- A controller. `:NAMEpage.cpp` generally includes `:NAMEmodel.h` and `forms/:NAME.page.ui` with a similar `:NAME`.
4647

47-
### \*dialog.(h/cpp)
48+
#### \*dialog.(h/cpp)
4849

49-
Various dialogs, e.g. to open a URL. Inherit from [QDialog](https://doc.qt.io/qt-5/qdialog.html).
50+
- Various dialogs, e.g. to open a URL. Inherit from [QDialog](https://doc.qt.io/qt-5/qdialog.html).
5051

51-
### paymentserver.(h/cpp)
52+
#### paymentserver.(h/cpp)
5253

53-
Used to process BIP21 payment URI requests. Also handles URI based application switching (e.g. when following a bitcoin:... link from a browser).
54+
- (Deprecated) Used to process BIP21 payment URI requests. Also handles URI-based application switching (e.g. when following a bitcoin:... link from a browser).
5455

55-
### walletview.(h/cpp)
56+
#### walletview.(h/cpp)
5657

57-
Represents the view to a single wallet.
58+
- Represents the view to a single wallet.
5859

59-
### Other .h/cpp files
60+
#### Other .h/cpp files
6061

6162
* UI elements like BitcoinAmountField, which inherit from QWidget.
6263
* `bitcoinstrings.cpp`: automatically generated
63-
* `bitcoinunits.(h/cpp)`: BTC / mBTC / etc handling
64+
* `bitcoinunits.(h/cpp)`: BTC / mBTC / etc. handling
6465
* `callback.h`
65-
* `guiconstants.h`: UI colors, app name, etc
66+
* `guiconstants.h`: UI colors, app name, etc.
6667
* `guiutil.h`: several helper functions
6768
* `macdockiconhandler.(h/mm)`: macOS dock icon handler
6869
* `macnotificationhandler.(h/mm)`: display notifications in macOS
6970

7071
## Contribute
7172

72-
See [CONTRIBUTING.md](/CONTRIBUTING.md) for general guidelines. Specifically for Qt:
73+
See [CONTRIBUTING.md](/CONTRIBUTING.md) for general guidelines.
74+
75+
**Note:** Do not change `local/bitcoin_en.ts`. It is updated [automatically](/doc/translation_process.md#writing-code-with-translations).
76+
77+
## Using Qt Creator as an IDE
78+
79+
[Qt Creator](https://www.qt.io/product/development-tools) is a powerful tool which packages a UI designer tool (Qt Designer) and a C++ IDE into one application. This is especially useful if you want to change the UI layout.
80+
81+
#### Download Qt Creator
82+
83+
On Unix and macOS, Qt Creator can be installed through your package manager. Alternatively, you can download a binary from the [Qt Website](https://www.qt.io/download/).
84+
85+
**Note:** If installing from a binary grabbed from the Qt Website: During the installation process, uncheck everything except for `Qt Creator`.
86+
87+
##### macOS
88+
89+
```sh
90+
brew install qt-creator
91+
```
92+
93+
##### Ubuntu & Debian
94+
95+
```sh
96+
sudo apt-get install qtcreator
97+
```
98+
99+
#### Setup Qt Creator
73100

74-
* don't change `local/bitcoin_en.ts`; this happens [automatically](/doc/translation_process.md#writing-code-with-translations)
101+
1. Make sure you've installed all dependencies specified in your systems build instructions
102+
2. Follow the compile instructions for your system, run `./configure` with the `--enable-debug` flag
103+
3. Start Qt Creator. At the start page, do: `New` -> `Import Project` -> `Import Existing Project`
104+
4. Enter `bitcoin-qt` as the Project Name and enter the absolute path to `src/qt` as Location
105+
5. Check over the file selection, you may need to select the `forms` directory (necessary if you intend to edit *.ui files)
106+
6. Confirm the `Summary` page
107+
7. In the `Projects` tab, select `Manage Kits...`
75108

76-
## Using Qt Creator as IDE
109+
**macOS**
110+
- Under `Kits`: select the default "Desktop" kit
111+
- Under `Compilers`: select `"Clang (x86 64bit in /usr/bin)"`
112+
- Under `Debuggers`: select `"LLDB"` as debugger (you might need to set the path to your LLDB installation)
77113

78-
You can use Qt Creator as an IDE. This is especially useful if you want to change
79-
the UI layout.
114+
**Ubuntu & Debian**
80115

81-
Download and install the community edition of [Qt Creator](https://www.qt.io/download/).
82-
Uncheck everything except Qt Creator during the installation process.
116+
Note: Some of these options may already be set
83117

84-
Instructions for macOS:
118+
- Under `Kits`: select the default "Desktop" kit
119+
- Under `Compilers`: select `"GCC (x86 64bit in /usr/bin)"`
120+
- Under `Debuggers`: select `"GDB"` as debugger
85121

86-
1. Make sure you installed everything through Homebrew mentioned in the [macOS build instructions](/doc/build-osx.md)
87-
2. Use `./configure` with the `--enable-debug` flag
88-
3. In Qt Creator do "New Project" -> Import Project -> Import Existing Project
89-
4. Enter "bitcoin-qt" as project name, enter src/qt as location
90-
5. Leave the file selection as it is
91-
6. Confirm the "summary page"
92-
7. In the "Projects" tab select "Manage Kits..."
93-
8. Select the default "Desktop" kit and select "Clang (x86 64bit in /usr/bin)" as compiler
94-
9. Select LLDB as debugger (you might need to set the path to your installation)
95-
10. Start debugging with Qt Creator (you might need to the executable to "bitcoin-qt" under "Run", which is where you can also add command line arguments)
122+
8. While in the `Projects` tab, ensure that you have the `bitcoin-qt` executable specified under `Run`
123+
- If the executable is not specified: click `"Choose..."`, navigate to `src/qt`, and select `bitcoin-qt`
124+
9. You're all set! Start developing, building, and debugging the Bitcoin Core GUI

0 commit comments

Comments
 (0)