diff --git a/.travis/README.md b/.travis/README.md index 21d1b9cc..9f4b80ef 100644 --- a/.travis/README.md +++ b/.travis/README.md @@ -1,8 +1,10 @@ ## travis build scripts +Status: legacy documentation. The current Agrarian 2.0 modernization work is +validated with local build helpers and smoke tests, not Travis CI. + The `.travis` directory contains scripts for each build step in each build stage. Currently the travis build defines two stages `lint` and `test`. Each stage has it's own [lifecycle](https://docs.travis-ci.com/user/customizing-the-build/#the-build-lifecycle). Every script in here is named and numbered according to which stage and lifecycle step it belongs to. - diff --git a/README.md b/README.md index 856d0f6c..1c31de88 100644 --- a/README.md +++ b/README.md @@ -114,6 +114,7 @@ To see configuration options: For current build notes, see: +- `doc/modernization.md` for the current 2.0 dependency and build baseline. - `doc/build-ubuntu-24.md` for native Ubuntu daemon and wallet builds. - `doc/build-windows.md` for Windows cross-compilation. - `doc/build-wallets.md` for the repeatable desktop wallet quick start. diff --git a/contrib/rpm/README.md b/contrib/rpm/README.md index e1e0745f..d8ad6f68 100644 --- a/contrib/rpm/README.md +++ b/contrib/rpm/README.md @@ -1,6 +1,10 @@ RPM Spec File Notes ------------------- +Status: this RPM packaging guide is historical. It has not been revalidated for +the Agrarian 2.0 Qt6/OpenSSL3/Boost modernization path. Prefer the Ubuntu 24.04 +depends-based build docs until RPM packaging is refreshed. + The RPM spec file provided here is for Bitcoin-Core 0.12.0 and builds on CentOS 7 with either the CentOS provided OpenSSL library or with LibreSSL as packaged at [LibreLAMP.com](https://librelamp.com/). It should hopefully not be too @@ -72,10 +76,9 @@ difficult for a user to recover from backup in the event of a system failure. ## Graphical User Interface and Qt Version -The RPM spec file will by default build the GUI client linked against the Qt5 -libraries. If you wish instead to link against the Qt4 libraries you need to -pass the switch `-D '_use_qt4 1'` at build time to the `rpmbuild` or `mock` -command used to build the packages. +The historical RPM spec targeted older Qt libraries. For Agrarian 2.0, new RPM +work should target Qt 6.8 LTS and the dependency baseline in +`doc/modernization.md`. If you would prefer not to build the GUI at all, you can pass the switch `-D '_no_gui 1'` to the `rpmbuild` or `mock` build command. diff --git a/doc/README.md b/doc/README.md index 9260c1be..6f2ff905 100644 --- a/doc/README.md +++ b/doc/README.md @@ -36,6 +36,7 @@ Building The following are developer notes on how to build Agrarian Core on your native platform. They are not complete guides, but include notes on the necessary libraries, compile flags, etc. - [Dependencies](dependencies.md) +- [Agrarian 2.0 Modernization Status](modernization.md) - [Ubuntu 24.04 Build Notes](build-ubuntu-24.md) - [Desktop Wallet Build Quick Start](build-wallets.md) - [macOS Build Notes](build-osx.md) @@ -43,6 +44,10 @@ The following are developer notes on how to build Agrarian Core on your native p - [Windows Build Notes](build-windows.md) - [Gitian Building Guide](gitian-building.md) +The verified 2.0 build path is Ubuntu 24.04 with deterministic `depends/`. +macOS, RPM, Gitian, and Travis documentation is retained as historical +reference unless the individual document says it has been revalidated. + Development --------------------- The Agrarian repo's [root README](/README.md) contains relevant information on the development process and automated testing. diff --git a/doc/build-osx.md b/doc/build-osx.md index c677c41c..5f226430 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -13,17 +13,21 @@ When the popup appears, click `Install`. Then install [Homebrew](https://brew.sh). +Status +------ + +This macOS guide is legacy documentation. It has not been revalidated for the +Agrarian 2.0 Qt6/OpenSSL3/Boost modernization path. The currently verified +desktop wallet paths are Ubuntu 24.04 native and Windows x86_64 cross-compiled +from Ubuntu. See `doc/modernization.md`. + Dependencies ---------------------- - brew install autoconf automake berkeley-db4 libtool boost miniupnpc openssl pkg-config protobuf python3 qt5 zmq libevent qrencode gmp + brew install autoconf automake berkeley-db4 libtool boost miniupnpc openssl pkg-config protobuf python3 qt6 zmq libevent qrencode gmp See [dependencies.md](dependencies.md) for a complete overview. -Status note: this macOS system-library path is legacy and has not been part of -the current Qt6/OpenSSL3/Boost modernization smoke-test pass. The verified -modern desktop wallet path is native Ubuntu via `contrib/build-linux-wallet.sh`. - If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG: brew install librsvg diff --git a/doc/build-unix.md b/doc/build-unix.md index a6664137..26a566f2 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -97,7 +97,7 @@ FEDORA Build tools: - sudo dnf install which gcc-c++ libtool make autoconf automake compat-openssl10-devel libevent-devel boost-devel libdb4-devel libdb4-cxx-devel gmp-devel python3 + sudo dnf install which gcc-c++ libtool make autoconf automake openssl-devel libevent-devel boost-devel libdb4-devel libdb4-cxx-devel gmp-devel python3 Optional: diff --git a/doc/build-wallets.md b/doc/build-wallets.md index 460de51c..7f67a908 100644 --- a/doc/build-wallets.md +++ b/doc/build-wallets.md @@ -38,8 +38,7 @@ For the native Ubuntu wallet: For the Windows wallet: sudo apt-get install -y \ - mingw-w64 g++-mingw-w64-x86-64 g++-mingw-w64-x86-64-posix \ - qttools5-dev-tools + mingw-w64 g++-mingw-w64-x86-64 g++-mingw-w64-x86-64-posix Then select POSIX Mingw-w64 threading: diff --git a/doc/build-windows.md b/doc/build-windows.md index fc4babf7..4d2005fb 100644 --- a/doc/build-windows.md +++ b/doc/build-windows.md @@ -77,7 +77,7 @@ GENERAL DEPENDENCIES sudo apt update sudo apt install -y build-essential libtool autotools-dev \ automake pkg-config bsdmainutils curl git make tar patch \ - qttools5-dev-tools + cmake ninja-build python3 A host toolchain (build-essential) is required because some dependencies (e.g., protobuf) build host utilities during the process. @@ -148,9 +148,12 @@ Manual equivalent: --disable-maintainer-mode \ --disable-tests \ --disable-bench \ - --with-gui=qt5 \ + --with-gui=qt6 \ --with-qt-incdir=$PWD/depends/x86_64-w64-mingw32/include \ - --with-qt-libdir=$PWD/depends/x86_64-w64-mingw32/lib + --with-qt-libdir=$PWD/depends/x86_64-w64-mingw32/lib \ + --with-qt-plugindir=$PWD/depends/x86_64-w64-mingw32/plugins \ + --with-qt-translationdir=$PWD/depends/x86_64-w64-mingw32/translations \ + --with-qt-bindir=$PWD/depends/x86_64-w64-mingw32/native/bin make ============================================================ @@ -161,7 +164,7 @@ Install toolchain: sudo apt install g++-mingw-w64-i686 mingw-w64-i686-dev -Ubuntu 18.04: +If multiple MinGW thread models are installed: sudo update-alternatives --config i686-w64-mingw32-g++ @@ -227,9 +230,9 @@ builds and stages a matching native `protoc` when needed. QT NOTE ============================================================ -The Windows cross-build helper targets the Qt6 depends path. Keep the helper's -Qt host tools (`moc`, `uic`, `rcc`) staged from the matching depends build to -avoid mixing host Qt tools with target Qt libraries. +The Windows cross-build helper targets the Qt 6.8 LTS depends path. Keep the +helper's Qt host tools (`moc`, `uic`, `rcc`) staged from the matching depends +build to avoid mixing host Qt tools with target Qt libraries. ============================================================ END OF DOCUMENT diff --git a/doc/dependencies.md b/doc/dependencies.md index 3d5b1732..bc4010a7 100644 --- a/doc/dependencies.md +++ b/doc/dependencies.md @@ -1,9 +1,12 @@ Dependencies ============ -These are the dependencies currently used by Agrarian Core. You can find instructions for installing them in the `build-*.md` file for your platform. +These are the dependencies currently used by the Agrarian 2.0 modernization +branch. You can find instructions for installing or building them in the +`build-*.md` file for your platform. The preferred path is the deterministic +`depends/` tree, not mixed system libraries. -| Dependency | Version used | Minimum required | CVEs | Shared | [Bundled Qt library](https://doc.qt.io/qt-5/configure-options.html#third-party-libraries) | +| Dependency | Version used | Minimum required | CVEs | Shared | Bundled Qt library | | --- | --- | --- | --- | --- | --- | | Berkeley DB | [4.8.30](https://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html) | 4.8.x | No | | | | Boost | [1.91.0](https://www.boost.org/users/download/) | [1.47.0](https://github.com/bitcoin/bitcoin/pull/8920) | No | | | @@ -31,6 +34,15 @@ These are the dependencies currently used by Agrarian Core. You can find instruc | ZeroMQ | [4.3.1](https://github.com/zeromq/libzmq/releases) | 4.0.0 | No | | | | zlib | [1.2.11](https://zlib.net/) | | | | No | +Modernization notes +------------------- + +* Qt builds target Qt 6.8 LTS through the deterministic depends path. +* OpenSSL builds target OpenSSL 3.5 LTS through the deterministic depends path. +* Boost builds target Boost 1.91.0 through the deterministic depends path. +* Berkeley DB remains 4.8.30 in depends for legacy wallet portability. Wallets + built against other BDB major versions may not be portable. + Controlling dependencies ------------------------ Some dependencies are not needed in all configurations. The following are some factors that affect the dependency list. diff --git a/doc/modernization.md b/doc/modernization.md new file mode 100644 index 00000000..97eb85b3 --- /dev/null +++ b/doc/modernization.md @@ -0,0 +1,73 @@ +Agrarian 2.0 Modernization Status +================================= + +This branch is the modernization line for Agrarian. The goal is to preserve +network behavior while making the codebase build repeatably on current systems. + +Verified Build Baseline +----------------------- + +Use Ubuntu 24.04 as the primary build host. + +The current deterministic `depends/` baseline is: + +- Qt 6.8.3 LTS +- OpenSSL 3.5.6 LTS +- Boost 1.91.0 +- Berkeley DB 4.8.30 for portable legacy wallet compatibility +- protobuf 2.6.1 for the existing Qt payment request sources +- libevent 2.1.8-stable +- GMP 6.1.2 +- ZeroMQ 4.3.1 when enabled + +The currently verified binaries are: + +- Ubuntu daemon and command-line tools +- Ubuntu Qt desktop wallet +- Windows x86_64 Qt desktop wallet and command-line tools cross-compiled from + Ubuntu + +Recommended Commands +-------------------- + +Native Ubuntu daemon: + + JOBS=1 ./contrib/build-linux.sh + +Native Ubuntu desktop wallet: + + JOBS=1 ./contrib/build-linux-wallet.sh + +Windows x86_64 desktop wallet: + + JOBS=1 ./contrib/build-win64-wallet.sh + +Use higher `JOBS` values only on hosts with enough memory. On an 8-core, 16 GB +host, `JOBS=8` is reasonable. + +Verification +------------ + +After a native Ubuntu build, run: + + ./contrib/smoke-test-daemon.sh + ./contrib/smoke-test-wallet.sh + ./contrib/smoke-test-qt.sh + +After a Windows cross build, confirm the expected PE binaries: + + file src/qt/agrarian-qt.exe src/agrariand.exe src/agrarian-cli.exe src/agrarian-tx.exe + +Documentation Status +-------------------- + +The preferred docs are: + +- `doc/build-ubuntu-24.md` +- `doc/build-wallets.md` +- `doc/build-windows.md` +- `doc/dependencies.md` + +Older macOS, RPM, Gitian, and Travis documents remain in the tree as historical +reference. They are not part of the verified 2.0 modernization path unless a +document explicitly says otherwise. diff --git a/doc/release-notes.md b/doc/release-notes.md index 38e0b9f8..a2fe043b 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -1,3 +1,7 @@ +Status: historical release notes. This file documents the older Agrarian Core +3.3.0 release and is not the current Agrarian 2.0 modernization release plan. +For the current build and dependency baseline, see `doc/modernization.md`. + Agrarian Core version *3.3.0* is now available from: This is a new major version release, including various bug fixes and performance improvements, as well as updated translations. @@ -21,9 +25,9 @@ If you are running an older version, shut it down. Wait until it has completely Compatibility ============== -Agrarian Core is extensively tested on multiple operating systems using the Linux kernel, macOS 10.10+, and Windows 7 and later. - -Microsoft ended support for Windows XP on [April 8th, 2014](https://www.microsoft.com/en-us/WindowsForBusiness/end-of-xp-support), No attempt is made to prevent installing or running the software on Windows XP, you can still do so at your own risk but be aware that there are known instabilities and issues. Please do not report issues about Windows XP to the issue tracker. +For the current 2.0 modernization branch, the verified build targets are Ubuntu +24.04 and Windows x86_64 cross-compiled from Ubuntu. Older platform statements +below belong to the historical 3.3.0 release context. Apple released it's last Mountain Lion update August 13, 2015, and officially ended support on [December 14, 2015](http://news.fnal.gov/2015/10/mac-os-x-mountain-lion-10-8-end-of-life-december-14/). Agrarian Core software starting with v3.2.0 will no longer run on MacOS versions prior to Yosemite (10.10). Please do not report issues about MacOS versions prior to Yosemite to the issue tracker. diff --git a/doc/travis-ci.txt b/doc/travis-ci.txt index 38085cec..c3a76b2e 100644 --- a/doc/travis-ci.txt +++ b/doc/travis-ci.txt @@ -1,6 +1,10 @@ Travis CI ========= +Status: legacy documentation. Travis CI is not part of the verified Agrarian +2.0 modernization path. Keep this file only as historical context until a +current CI workflow is added. + Support for using travis-ci has been added in order to automate pull-testing. See [travis-ci.org](https://travis-ci.org/) for more info diff --git a/docs/installer.md b/docs/installer.md index 92e7b29b..59d3a865 100644 --- a/docs/installer.md +++ b/docs/installer.md @@ -1,6 +1,8 @@ # Ubuntu Installer -`installer/agrarian-installer.sh` provides a Ubuntu-only CLI for common build actions. +`installer/agrarian-installer.sh` provides a Ubuntu-only CLI for common build +actions. The current modernization baseline is Ubuntu 24.04 with deterministic +`depends/`; see `doc/modernization.md` for the verified dependency set. ## Usage diff --git a/test/README.md b/test/README.md index d0a22516..9391f36e 100644 --- a/test/README.md +++ b/test/README.md @@ -11,9 +11,9 @@ interfaces. - [util](/test/util) which tests the agrarian utilities, currently only agrarian-tx. -The util tests are run as part of `make check` target. The functional -tests are run by the travis continuous build process whenever a pull -request is opened. Both sets of tests can also be run locally. +The util tests are run as part of the `make check` target. Functional tests can +be run locally with the test runner. Travis CI references in this tree are +legacy and are not part of the current Agrarian 2.0 verification path. # Running tests locally