doc: Improve gui/src/qt README.md #139

pull jarolrod wants to merge 1 commits into bitcoin-core:master from jarolrod:improve-qt-readme changing 1 files +75 −46
  1. jarolrod commented at 7:29 am on November 28, 2020: member

    Master/Before: Render of Master

    PR/After: Render of PR

    Changes: The README.md found in gui/src/qt seems to not have gotten any love in a while. This PR fixes some grammatical errors, makes it easier to follow, and modernizes the logic of using Qt Creator.

    1. Makes several sections more informative
    2. Directories under Files and Directories now end with a forward slash denoting that they are a directory
    3. Modernize the Qt Creator Logic for the current setup flow
    4. Add UNIX Qt Creator Setup Instructions (Ubuntu & Debian)
  2. fanquake added the label Doc on Nov 28, 2020
  3. in src/qt/README.md:1 in 30ec2e4d9f outdated 
    0@@ -1,62 +1,61 @@
1-This directory contains the BitcoinQT graphical user interface (GUI). It uses the cross-platform framework [Qt](https://www1.qt.io/developers/).
2+This directory contains the source code for the reference implementation of the Bitcoin Core graphical user interface (GUI). It uses the [Qt](https://www1.qt.io/developers/) cross-platform framework.
    hebasto commented at 4:40 pm on November 28, 2020:

    I don’t think that the “reference implementation” notion corresponds to the decentralized nature of bitcoin clients development.

    While here: s|https://www1.qt.io/developers/|https://www.qt.io/developers|

    jarolrod commented at 9:05 pm on November 28, 2020:
    I was drawing on conversations had about the role of the Bitcoin Core GUI. Here is an example #45 (comment). I think it’s OK to call this the reference implementation. If it’s not OK with the community, I’ll change this to: This directory contains the source code for the Bitcoin Core graphical user interface (GUI).
    RandyMcMillan commented at 11:50 pm on November 28, 2020:

    I like this better..

    This directory contains the source code for the Bitcoin Core graphical user interface (GUI).

    It is more correct IMO.

    jarolrod commented at 2:50 am on January 15, 2021:
    Addressed this in f6584d9c84f4d840dd5cb49f7dcc9984e9a16304. Used @RandyMcMillan suggestion, thanks!
  4. in src/qt/README.md:7 in 30ec2e4d9f outdated 
    0@@ -1,62 +1,61 @@
1-This directory contains the BitcoinQT graphical user interface (GUI). It uses the cross-platform framework [Qt](https://www1.qt.io/developers/).
2+This directory contains the source code for the reference implementation of the Bitcoin Core graphical user interface (GUI). It uses the [Qt](https://www1.qt.io/developers/) cross-platform framework.
3 
4 The current precise version for Qt 5 is specified in [qt.mk](/depends/packages/qt.mk).
5 
6 ## Compile and run
7 
8-See build instructions ([macOS](/doc/build-osx.md), [Windows](/doc/build-windows.md), [Unix](/doc/build-unix.md), etc).
9+See build instructions ([macOS](/doc/build-osx.md), [Windows](/doc/build-windows.md), [Unix](/doc/build-unix.md), etc). Compiling generates the `bitcoin-qt` executable.
    hebasto commented at 4:42 pm on November 28, 2020:

    For Windows the executable binary is named bitcoin-qt.exe :D

    Also test_bitcoin-qt is built.

    jarolrod commented at 2:51 am on January 15, 2021:
    Addresses this in f6584d9c84f4d840dd5cb49f7dcc9984e9a16304. Removed this string in favor of just referring users to the build instruction.
  5. in src/qt/README.md:17 in 30ec2e4d9f outdated 
    16 
17-## Files and directories
18+## Files and Directories
19 
20-### forms
21+#### /forms
    hebasto commented at 4:47 pm on November 28, 2020:
    The slash character (/) in the beginning of the path means a root directory in the Linux world, and here it looks confusing.
    jarolrod commented at 9:10 pm on November 28, 2020:
    You’re right, forms/ is more appropriate
  6. in src/qt/README.md:23 in 30ec2e4d9f outdated 
    25 
26-### locale
27+#### /locale
28 
29-Contains translations. They are periodically updated. The process is described [here](/doc/translation_process.md).
30+- Contains translations of the strings used throughout the GUI. They are periodically updated and an effort is made to support as many languages as possible. The process of contributing translations is described [here](/doc/translation_process.md).
    hebasto commented at 4:54 pm on November 28, 2020:

    Addition "… of the strings used throughout the GUI" is not correct, as translations of non-GUI strings are included as well.

    See: share/qt/extract_strings_qt.py and src/qt/bitcoinstrings.cpp.

    jarolrod commented at 9:23 pm on November 28, 2020:
    gui/src/qt/locale/ seems to only contain translations for the GUI
    jarolrod commented at 2:52 am on January 15, 2021:
    addressed this in f6584d9c84f4d840dd5cb49f7dcc9984e9a16304. Removed the gui specific part.
  7. in src/qt/README.md:29 in 30ec2e4d9f outdated 
    31 
32-### res
33+#### /res
34 
35-Resources such as the icon.
36+ - Contains graphical resources used to enhance the UI experience.
    hebasto commented at 4:57 pm on November 28, 2020:
    Actually, all of them are icons :D
  8. hebasto commented at 5:05 pm on November 28, 2020: member
    For editing *.ui files the Qt Designer is enough for me, but this opinion is personal, ofc.
  9. in src/qt/README.md:52 in 30ec2e4d9f outdated 
    68 
69-Various dialogs, e.g. to open a URL. Inherit from [QDialog](https://doc.qt.io/qt-5/qdialog.html).
70+#### paymentserver.(h/cpp)
71 
72-### paymentserver.(h/cpp)
73+- Used to process BIP21 payment URI requests. Also handles URI based application switching (e.g. when following a bitcoin:... link from a browser).
    jonasschnelli commented at 9:38 am on December 1, 2020:
    Maybe add (deprecated)?
    jarolrod commented at 2:52 am on January 15, 2021:
    Done in f6584d9c84f4d840dd5cb49f7dcc9984e9a16304
  10. in src/qt/README.md:112 in 30ec2e4d9f outdated 
    106+6. Check over the file selection, you may need to select the `"forms"` directory (necessary if you intend to edit *.ui files)
107+7. Confirm the `Summary` page
108+8. In the `Projects` tab, select `Manage Kits...`
109+ - Under `Kits`: select the default "Desktop" kit
110+ - Under `Compilers`: select an appropriate compiler. (on macOS select `"Clang (x86 64bit in /usr/bin)"`)
111+ - Under `Debuggers`: select `"LLDB"` as debugger (you might need to set the path to your LLDB installation)
    jonasschnelli commented at 9:40 am on December 1, 2020:
    I guess this is Mac specific (clang in /usr/bin/ as well as LLDB). I would probably keep this as “Mac” instructions (Linux/Win) people might need to adapt but they are not blinded by not telling them its made for Mac.
    jarolrod commented at 2:52 am on January 15, 2021:
    Done in f6584d9c84f4d840dd5cb49f7dcc9984e9a16304
  11. jonasschnelli commented at 9:40 am on December 1, 2020: contributor
    ACK modulo 2xcomments
  12. RandyMcMillan commented at 5:28 pm on December 2, 2020: contributor

    @jarolrod - You should be able to trigger a rebuild yourself. https://cirrus-ci.com/task/6120245750398976

    ACK :)

  14. jarolrod force-pushed on Jan 15, 2021
  15. jarolrod force-pushed on Jan 15, 2021
  16. jarolrod force-pushed on Jan 15, 2021
  17. jarolrod commented at 2:57 am on January 15, 2021: member

    updated to f6584d9c84f4d840dd5cb49f7dcc9984e9a16304

    Addressed @hebasto comments and @jonasschnelli suggestions

  18. in src/qt/README.md:52 in f6584d9c84 outdated 
    68 
69-Various dialogs, e.g. to open a URL. Inherit from [QDialog](https://doc.qt.io/qt-5/qdialog.html).
70+#### paymentserver.(h/cpp)
71 
72-### paymentserver.(h/cpp)
73+- (Deprecated) Used to process BIP21 payment URI requests. Also handles URI based application switching (e.g. when following a bitcoin:... link from a browser).
    jonatack commented at 9:40 am on January 15, 2021: 
    0- (Deprecated) Used to process BIP21 payment URI requests. Also handles URI-based application switching (e.g. when following a bitcoin:... link from a browser).
  19. in src/qt/README.md:73 in f6584d9c84 outdated 
    69@@ -71,25 +70,27 @@ Represents the view to a single wallet.
70 
71 See [CONTRIBUTING.md](/CONTRIBUTING.md) for general guidelines. Specifically for Qt:
72 
73-* don't change `local/bitcoin_en.ts`; this happens [automatically](/doc/translation_process.md#writing-code-with-translations)
74+**Note:** Do not change `local/bitcoin_en.ts`. This happens [automatically](/doc/translation_process.md#writing-code-with-translations).
    jonatack commented at 9:41 am on January 15, 2021:
    s/This happens/It is updated/
  20. in src/qt/README.md:77 in f6584d9c84 outdated 
    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)
96+[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.
    jonatack commented at 9:41 am on January 15, 2021: 
    0[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.
  21. in src/qt/README.md:75 in f6584d9c84 outdated 
    69@@ -71,25 +70,27 @@ Represents the view to a single wallet.
70 
71 See [CONTRIBUTING.md](/CONTRIBUTING.md) for general guidelines. Specifically for Qt:
72 
73-* don't change `local/bitcoin_en.ts`; this happens [automatically](/doc/translation_process.md#writing-code-with-translations)
74+**Note:** Do not change `local/bitcoin_en.ts`. This happens [automatically](/doc/translation_process.md#writing-code-with-translations).
75 
76 ## Using Qt Creator as IDE
    jonatack commented at 9:41 am on January 15, 2021: 
    0## Using Qt Creator as an IDE
  22. in src/qt/README.md:83 in f6584d9c84 outdated 
     97+
 98+#### Download Qt Creator
 99+On Linux 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/).
100+During the installation process, uncheck everything except for `Qt Creator`.
101+
102+#### Setup Qt Creator on macOS
    jonatack commented at 9:43 am on January 15, 2021:
    Can these steps be updated for Linux and/or Win as well?
  23. in src/qt/README.md:87 in f6584d9c84 outdated 
    101+
102+#### Setup Qt Creator on macOS
103+1. Make sure you've installed all dependencies specified in your systems build instructions
104+2. Follow the compile instructions for your system, run `./configure` with the `--enable-debug` flag
105+3. Start Qt Creator. At the start page, do: `New` -> `Import Project` -> `Import Existing Project`
106+5. Enter `"bitcoin-qt"` as the Project Name, enter `"{repo}/src/qt"` as Location (replace `{repo}` with the actual repo path)
    jonatack commented at 9:45 am on January 15, 2021:
    perhaps just “and enter the absolute path to src/qt as Location”
  24. in src/qt/README.md:92 in f6584d9c84 outdated 
    106+5. Enter `"bitcoin-qt"` as the Project Name, enter `"{repo}/src/qt"` as Location (replace `{repo}` with the actual repo path)
107+6. Check over the file selection, you may need to select the `"forms"` directory (necessary if you intend to edit *.ui files)
108+7. Confirm the `Summary` page
109+8. In the `Projects` tab, select `Manage Kits...`
110+ - Under `Kits`: select the default "Desktop" kit
111+ - Under `Compilers`: select an appropriate compiler. (on macOS select `"Clang (x86 64bit in /usr/bin)"`)
    jonatack commented at 9:46 am on January 15, 2021: 
    0 - Under `Compilers`: select an appropriate compiler (on macOS, select `"Clang (x86 64bit in /usr/bin)"`)
  25. in src/qt/README.md:112 in f6584d9c84 outdated 
    107+6. Check over the file selection, you may need to select the `"forms"` directory (necessary if you intend to edit *.ui files)
108+7. Confirm the `Summary` page
109+8. In the `Projects` tab, select `Manage Kits...`
110+ - Under `Kits`: select the default "Desktop" kit
111+ - Under `Compilers`: select an appropriate compiler. (on macOS 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)
    jonatack commented at 9:47 am on January 15, 2021:
    Is GDB an option on Linux?
  26. in src/qt/README.md:95 in f6584d9c84 outdated 
    109+8. In the `Projects` tab, select `Manage Kits...`
110+ - Under `Kits`: select the default "Desktop" kit
111+ - Under `Compilers`: select an appropriate compiler. (on macOS 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)
113+9. While in the `Projects` tab, ensure that you have the `bitcoin-qt` executable specified under `Run`
114+ - If the executable is not specified: click `"Choose..."`, navigate to `{repo}/src/qt`, and select `bitcoin-qt`
    jonatack commented at 9:48 am on January 15, 2021: 
    0 - If the executable is not specified: click `"Choose..."`, navigate to `src/qt`, and select `bitcoin-qt`
  27. in src/qt/README.md:19 in f6584d9c84 outdated 
    19 
20-### forms
21+#### forms/
22 
23-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.
24+- A directory which 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 are normally altered with [Qt Creator](#using-qt-creator-as-ide), but can be edited using any text editor.
    jonatack commented at 10:12 am on January 15, 2021:
    • s/which/that/
    • s/normally altered/can be edited/
    • s/, but can be edited/or/
  28. jonatack commented at 10:15 am on January 15, 2021: contributor
    Concept ACK
  29. jarolrod force-pushed on Jan 16, 2021
  30. jarolrod commented at 5:00 am on January 16, 2021: member

    updated f6584d9 -> a9e641d

    Implemented @jonatack suggestions. Thanks for the in-depth review!

    Additionally, I have included some Qt Creator setup instructions for UNIX (Ubuntu & Debian). Windows instructions still need to be done. I will take care of that in a follow-up PR.

    New Render: src/qt/README.md

  31. jonatack commented at 10:35 pm on January 16, 2021: contributor
    Thanks, will re-review.
  32. in src/qt/README.md:25 in a9e641d40d outdated 
    29 
30-Contains translations. They are periodically updated. The process is described [here](/doc/translation_process.md).
31+#### locale/
32 
33-### res
34+- 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 [here](/doc/translation_process.md).
    jonatack commented at 12:41 pm on January 21, 2021:

    like line 73 below

    0- 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).
  33. in src/qt/README.md:33 in a9e641d40d outdated 
    41 
42-Tests.
43+#### test/
44 
45-### bitcoingui.(h/cpp)
46+- Functional tests used to ensure proper functionality of the GUI. Significant changes to the GUI code normally require new tests to be written.
    jonatack commented at 12:42 pm on January 21, 2021: 
    0- Functional tests used to ensure proper functionality of the GUI. Significant changes to the GUI code normally require new or updated tests.
  34. in src/qt/README.md:112 in a9e641d40d outdated 
    112-You can use Qt Creator as an IDE. This is especially useful if you want to change
113-the UI layout.
114+ **macOS**
115+ - Under `Kits`: select the default "Desktop" kit
116+ - Under `Compilers`: select `"Clang (x86 64bit in /usr/bin)"`
117+ - Under `Debuggers`: select `"LLDB"` as debugger (you might need to set the path to your LLDB installation)
    jonatack commented at 5:25 pm on January 21, 2021:

    remove whitespace at EOL

    0  - Under `Compilers`: select `"Clang (x86 64bit in /usr/bin)"`
1- - Under `Debuggers`: select `"LLDB"` as debugger (you might need to set the path to your LLDB installation)  
2+ - Under `Debuggers`: select `"LLDB"` as debugger (you might need to set the path to your LLDB installation)
3 
4- **Ubuntu & Debian**  
5+ **Ubuntu & Debian**
6  **Note:** Some of these options may already be set
  35. in src/qt/README.md:60 in a9e641d40d outdated 
    81 
82-Represents the view to a single wallet.
83+- Represents the view to a single wallet.
84 
85-### Other .h/cpp files
86+#### Other .h/cpp files
    jonatack commented at 5:29 pm on January 21, 2021:
    lines 64 and 66: s/etc/etc./
  36. jonatack commented at 5:30 pm on January 21, 2021: contributor
    Almost-ACK, just a couple more items below.
  37. jarolrod force-pushed on Jan 22, 2021
  38. jarolrod commented at 9:54 pm on January 22, 2021: member
    updated a9e641d -> 63d0f29c9945dcf512bf494a4f24190121c48648, addressed @jonatack suggestions
  39. 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
    5d1f260713
  40. in src/qt/README.md:114 in 63d0f29c99 outdated 
    144+ - Under `Compilers`: select `"Clang (x86 64bit in /usr/bin)"`
145+ - Under `Debuggers`: select `"LLDB"` as debugger (you might need to set the path to your LLDB installation)
146 
147-Download and install the community edition of [Qt Creator](https://www.qt.io/download/).
148-Uncheck everything except Qt Creator during the installation process.
149+ **Ubuntu & Debian**
    jonatack commented at 11:03 pm on January 22, 2021: 
    0 **Ubuntu & Debian**
    jarolrod commented at 7:07 pm on January 28, 2021:
    addressed in 5d1f260
  41. jarolrod force-pushed on Jan 28, 2021
  42. jarolrod commented at 7:07 pm on January 28, 2021: member
    updated 63d0f29c9945dcf512bf494a4f24190121c48648 -> 5d1f260, addressed leading whitespace issue
  43. jonatack approved
  44. jonatack commented at 8:43 pm on January 28, 2021: contributor
    ACK 5d1f260713f9f1d29c0db68f2917dfe7368d4ba0
  45. RandyMcMillan commented at 11:01 pm on January 28, 2021: contributor
    ACK 5d1f260 👍🏼
  46. MarcoFalke merged this on Jan 29, 2021
  47. MarcoFalke closed this on Jan 29, 2021
  48. sidhujag referenced this in commit 41af9ddee9 on Jan 29, 2021
  49. jarolrod deleted the branch on Jan 29, 2021
  50. bitcoin-core locked this on Aug 16, 2022


jarolrod hebasto RandyMcMillan jonasschnelli jonatack

Labels
Doc

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin-core/gui. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2024-11-21 13:20 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me