diff --git a/doc/build-osx.md b/doc/build-osx.md index ef8f3ff6a..99615062d 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -1,110 +1,93 @@ Mac OS X Build Instructions and Notes ==================================== The commands in this guide should be executed in a Terminal application. The built-in one is located in `/Applications/Utilities/Terminal.app`. Preparation ----------- 1. Install Xcode from the app store if you don't have it already (it's a dependency for qt5) NOTE: Building with Qt4 is still supported, however, could result in a broken UI. Building with Qt5 is recommended. 2. Install the OS X command line tools: `xcode-select --install` When the popup appears, click `Install`. 3. Install [Homebrew](https://brew.sh). Dependencies ---------------------- Install dependencies: brew install automake berkeley-db libtool boost miniupnpc openssl pkg-config protobuf python qt libevent See [dependencies.md](dependencies.md) for a complete overview. If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG brew install librsvg Build Bitcoin ABC ----------------- Before you start building, please make sure that your compiler supports C++14. 1. Clone the Bitcoin ABC source code and cd into `bitcoin-abc` git clone https://github.com/Bitcoin-ABC/bitcoin-abc.git cd bitcoin-abc 2. Build bitcoin-abc: Configure and build the headless bitcoin binaries as well as the GUI (if Qt is found). You can disable the GUI build by passing `--without-gui` to configure. It is recommended to create a build directory to build out-of-tree. ./autogen.sh mkdir build cd build ../configure make 3. It is recommended to build and run the unit tests: make check 4. You can also create a .dmg that contains the .app bundle (optional): make deploy Running ------- Bitcoin ABC is now available at `./src/bitcoind` Before running, it's recommended you create an RPC configuration file. echo -e "rpcuser=bitcoinrpc\nrpcpassword=$(xxd -l 16 -p /dev/urandom)" > "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" The first time you run bitcoind, it will start downloading the blockchain. This process could take several hours. You can monitor the download process by looking at the debug.log file: tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log Other commands: ------- ./src/bitcoind -daemon # Starts the bitcoin daemon. ./src/bitcoin-cli --help # Outputs a list of command-line options. ./src/bitcoin-cli help # Outputs a list of RPC commands when the daemon is running. -Using Qt Creator as IDE ------------------------- -You can use Qt Creator as an IDE, for bitcoin development. -Download and install the community edition of [Qt Creator](https://www.qt.io/download/). -Uncheck everything except Qt Creator during the installation process. - -1. Make sure you installed everything through Homebrew mentioned above -2. Do a proper ./configure --enable-debug -3. In Qt Creator do "New Project" -> Import Project -> Import Existing Project -4. Enter "bitcoin-qt" as project name, enter src/qt as location -5. Leave the file selection as it is -6. Confirm the "summary page" -7. In the "Projects" tab select "Manage Kits..." -8. Select the default "Desktop" kit and select "Clang (x86 64bit in /usr/bin)" as compiler -9. Select LLDB as debugger (you might need to set the path to your installation) -10. Start debugging with Qt Creator - Notes ----- * Building with downloaded Qt binaries is not officially supported. See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714) diff --git a/src/qt/README.md b/src/qt/README.md new file mode 100644 index 000000000..824055230 --- /dev/null +++ b/src/qt/README.md @@ -0,0 +1,95 @@ +This directory contains the BitcoinQT graphical user interface (GUI). It uses the cross platform framework [QT](https://www1.qt.io/developers/). + +The current precise version for QT 5 is specified in [qt.mk](/depends/packages/qt.mk). + +## Compile and run + +See build instructions ([OSX](/doc/build-osx.md), [Windows](/doc/build-windows.md), [Unix](/doc/build-unix.md), etc). + +To run: + +```sh +./src/qt/bitcoin-qt +``` + +## Files and directories + +### forms + +Contains [Designer UI](http://doc.qt.io/qt-5.9/designer-using-a-ui-file.html) files. They are created with [Qt Creator](#use-qt-Creator-as IDE), but can be edited using any text editor. + +### locale + +Contains translations. They are periodically updated. The process is described [here](/doc/translation_process.md). + +### res + +Resources such as the icon. + +### test + +Tests. + +### bitcoingui.(h/cpp) + +Represents the main window of the Bitcoin UI. + +### \*model.(h/cpp) + +The model. When it has a corresponding controller, it generally inherits from [QAbstractTableModel](http://doc.qt.io/qt-5/qabstracttablemodel.html). Models that are used by controllers as helpers inherit from other QT classes like [QValidator](http://doc.qt.io/qt-5/qvalidator.html). + +ClientModel is used by the main application `bitcoingui` and several models like `peertablemodel`. + +### \*page.(h/cpp) + +A controller. `:NAMEpage.cpp` generally includes `:NAMEmodel.h` and `forms/:NAME.page.ui` with a similar `:NAME`. + +### \*dialog.(h/cpp) + +Various dialogs, e.g. to open a URL. Inherit from [QDialog](http://doc.qt.io/qt-5.5/qdialog.html). + +### paymentserver.(h/cpp) + +Used to process BIP21 and BIP70 payment URI / requests. Also handles URI based application switching (e.g. when following a bitcoincash:... link from a browser). + +### walletview.(h/cpp) + +Represents the view to a single wallet. + +### Other .h/cpp files + +* UI elements like BitcoinAmountField, which inherit from QWidget. +* `bitcoinstrings.cpp`: automatically generated +* `bitcoinunits.(h/cpp)`: BCH / mBCH / etc handling +* `callback.h` +* `guiconstants.h`: UI colors, app name, etc +* `guiutil.h`: several helper functions +* `macdockiconhandler.(h/cpp)` +* `macdockiconhandler.(h/cpp)`: display notifications in OSX + +## Contribute + +See [CONTRIBUTING.md](/CONTRIBUTING.md) for general guidelines. Specifically for QT: + +* don't change `local/bitcoin_en.ts`; this happens [automatically](/doc/translation_process.md#writing-code-with-translations) + +## Using Qt Creator as IDE + +You can use Qt Creator as an IDE. This is especially useful if you want to change +the UI layout. + +Download and install the community edition of [Qt Creator](https://www.qt.io/download/). +Uncheck everything except Qt Creator during the installation process. + +Instructions for OSX: + +1. Make sure you installed everything through Homebrew mentioned in the [OSX build instructions](/docs/build-osx.md) +2. Use `./configure` with the `--enable-debug` flag +3. In Qt Creator do "New Project" -> Import Project -> Import Existing Project +4. Enter "bitcoin-qt" as project name, enter src/qt as location +5. Leave the file selection as it is +6. Confirm the "summary page" +7. In the "Projects" tab select "Manage Kits..." +8. Select the default "Desktop" kit and select "Clang (x86 64bit in /usr/bin)" as compiler +9. Select LLDB as debugger (you might need to set the path to your installation) +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)