diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..3a140635 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,47 @@ +name: Build documentation + +on: [push] + +env: + # Name of module and id separated by a slash + INSTANCE: docs/Writerside/in + # Replace HI with the ID of the instance in capital letters + ARTIFACT: webHelpIN2-all.zip + # Docker image version + DOCKER_VERSION: 242.21870 + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-go@v5 + with: + go-version: '^1.23.2' + - uses: hecrj/setup-rust-action@v2 + with: + rust-version: stable + - name: Update image + run: cd docs && ./update_screenshot.sh + - name: Build Writerside docs using Docker + uses: JetBrains/writerside-github-action@v4 + with: + instance: ${{ env.INSTANCE }} + artifact: ${{ env.ARTIFACT }} + docker-version: ${{ env.DOCKER_VERSION }} + + - name: Upload artifact + uses: actions/upload-artifact@v4 + with: + name: artifact + path: artifacts/${{ env.ARTIFACT }} + + - name: Release + uses: softprops/action-gh-release@v2 + if: startsWith(github.ref, 'refs/tags/') + with: + files: release/gh/* + token: ${{ secrets.CUSTOM_GITHUB_TOKEN }} \ No newline at end of file diff --git a/README.md b/README.md index 3a9b1a5b..63f3fce2 100644 --- a/README.md +++ b/README.md @@ -2,94 +2,15 @@ > Wrapper around wallet2_api.h that can be called using C api. -[![status-badge](https://ci.mrcyjanek.net/api/badges/5/status.svg?branch=rewrite-wip)](https://ci.mrcyjanek.net/repos/5/branches/rewrite-wip) - ## Building -to "clean" everything: +TL;DR: ```bash $ rm -rf monero wownero release $ git submodule update --init --recursive --force +$ for coin in monero wownero; do ./apply_patches $coin; done +$ ./build_single monero $(gcc -dumpmachine) -j$(nproc) ``` -fix ownership (if you build in docker but clone as a local user) - -```bash -$ sudo chown $(whoami) . -R -``` - -patch codebase - -```bash -$ ./apply_patches.sh monero -$ ./apply_patches.sh wownero -``` - -build monero_c - -```bash -$ ./build_single.sh monero x86_64-linux-gnu -j$(nproc) - wownero i686-linux-gnu - aarch64-linux-gnu - x86_64-linux-android - i686-linux-android - aarch64-linux-android - arm-linux-androideabi - i686-w64-mingw32 - x86_64-w64-mingw32 - host-apple-darwin - host-apple-ios -``` - -While building I aim to compile the code at oldest supported release of debian, using default toolchain to ensure that all linux distributions are able to run monero_c libraries, below I present a supported builders for given targets - -| x | builder | notes | -| ---------------------- | -------------------- | ----- | -| x86_64-linux-gnu | debian:buster | | -| i686-linux-gnu | debian:buster | | -| aarch64-linux-gnu | debian:buster | | -| x86_64-linux-android | debian:buster | | -| i686-linux-android | debian:buster | | -| aarch64-linux-android | debian:buster | | -| arm-linux-androideabi | debian:buster | | -| i686-w64-mingw32 | debian:buster | hardcoded DLL paths in build_single.sh | -| x86_64-w64-mingw32 | debian:buster | -"- | -| x86_64-apple-darwin11 | debian:bookworm | extra build step: `${HOST_ABI}-ranlib $PWD/$repo/contrib/depends/${HOST_ABI}/lib/libpolyseed.a` | -| aarch64-apple-darwin11 | debian:bookworm | -"- | -| host-apple-darwin | arm64-apple-darwin23 | dependencies: `brew install unbound boost@1.76 zmq cmake ccache autoconf automake libtool && brew link boost@1.76` | -| host-apple-ios | arm64-apple-darwin23 | | - -## Design - -Functions are as simple as reasonably possible as few steps should be performed to get from the exposed C api to actual wallet2 (or wallet3 in future) api calls. - -The only things passed in and out are: - -- void -- bool -- int -- uint64_t -- void* -- const char* - -All more complex structures are serialized into `const char*`, take look at MONERO_Wallet_createTransaction which uses `splitString(std::string(preferredInputs), std::string(separator));` to convert string into a std::set, so no implementation will need to worry about that. - -Is there more effective way to do that? Probably. Is there more universal way to pass that (JSON, or others?)? Most likely. That being said, I'm against doing that. You can easily join a string in any language, and I like to keep dependency count as low as possible. - -As for function naming `${COIN}_namespaceOrClass_functionName` is being used, currently these cryptocurrencies are supported - -- monero -- wownero - -both using wallet2 api, and both being patched with our secret ingredient(tm) (check patches directory). - -Since monero_c aims to be one-fits-all solution for monero wallets, there are some special things inside, like functions prefixed with `DEBUG_*`, these are not quarenteed to stay in the code, and can be changed, the only reason they are in is because I needed some testing early in the development when bringing support for variety of platforms. - -If you are a wallet developer and you **really** need this one function that doesn't exist, feel free to let me know I'll be happy to implement that. - -Currently there are enterprise resitents in our library: `${COIN}_cw_*` these functions are not guaranteed to stay stable, and are made for cake wallet to implement features that are not used in xmruw nor in stack_wallet (which I need to double-check later?). - -## Contributing - -To contribute you can visit git.mrcyjanek.net/mrcyjanek/monero_c and open a PR, alternatively use any other code mirror or send patches directly. \ No newline at end of file +Broken? Not working? Need help? https://moneroc.mrcyjanek.net/ diff --git a/docs/.idea/.gitignore b/docs/.idea/.gitignore new file mode 100644 index 00000000..26d33521 --- /dev/null +++ b/docs/.idea/.gitignore @@ -0,0 +1,3 @@ +# Default ignored files +/shelf/ +/workspace.xml diff --git a/docs/.idea/docs.iml b/docs/.idea/docs.iml new file mode 100644 index 00000000..61021940 --- /dev/null +++ b/docs/.idea/docs.iml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/.idea/modules.xml b/docs/.idea/modules.xml new file mode 100644 index 00000000..6049cfe0 --- /dev/null +++ b/docs/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/.idea/vcs.xml b/docs/.idea/vcs.xml new file mode 100644 index 00000000..6c0b8635 --- /dev/null +++ b/docs/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/docs/Writerside/assets/onefetch.png b/docs/Writerside/assets/onefetch.png new file mode 100644 index 00000000..4cf1288c Binary files /dev/null and b/docs/Writerside/assets/onefetch.png differ diff --git a/docs/Writerside/c.list b/docs/Writerside/c.list new file mode 100644 index 00000000..c4c77a29 --- /dev/null +++ b/docs/Writerside/c.list @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/docs/Writerside/cfg/buildprofiles.xml b/docs/Writerside/cfg/buildprofiles.xml new file mode 100644 index 00000000..332e47bb --- /dev/null +++ b/docs/Writerside/cfg/buildprofiles.xml @@ -0,0 +1,13 @@ + + + + + + + + true + + + + diff --git a/docs/Writerside/cfg/glossary.xml b/docs/Writerside/cfg/glossary.xml new file mode 100644 index 00000000..22bec6b4 --- /dev/null +++ b/docs/Writerside/cfg/glossary.xml @@ -0,0 +1,7 @@ + + + + + Description of what "foo" is. + + \ No newline at end of file diff --git a/docs/Writerside/in.tree b/docs/Writerside/in.tree new file mode 100644 index 00000000..b803dbb4 --- /dev/null +++ b/docs/Writerside/in.tree @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/Writerside/topics/Android.md b/docs/Writerside/topics/Android.md new file mode 100644 index 00000000..c02b14f9 --- /dev/null +++ b/docs/Writerside/topics/Android.md @@ -0,0 +1,52 @@ +# Android + +Building on linux has been tested on +- `ubuntu:22.04` (docker tag) + +## Install dependencies + +```bash +$ apt update +$ apt install -y build-essential pkg-config autoconf libtool \ + ccache make cmake gcc g++ git curl lbzip2 libtinfo5 gperf \ + unzip python-is-python3 +``` + +## Prepare source + +> If you are running in docker or have not configured git you may need to do the following: +> ```bash +> git config --global --add safe.directory '*' +> git config --global user.email "ci@mrcyjanek.net" +> git config --global user.name "CI mrcyjanek.net" +> ``` + +```bash +$ git clone https://github.com/mrcyjanek/monero_c --recursive +$ cd monero_c +$ ./apply_patches.sh monero +``` + +## Building + + + + +$ ./build_single.sh monero x86_64-linux-android -j$(nproc) + + + + +$ ./build_single.sh monero aarch64-linux-android -j$(nproc) + + + + +$ ./build_single.sh monero armv7a-linux-androideabi -j$(nproc) + + + + +## Known issues + +None. Open an issue if you find something not working. \ No newline at end of file diff --git a/docs/Writerside/topics/Building.md b/docs/Writerside/topics/Building.md new file mode 100644 index 00000000..f44f1f37 --- /dev/null +++ b/docs/Writerside/topics/Building.md @@ -0,0 +1,99 @@ +# Building + +Building monero_c comes down to these simple steps: +```bash +$ git clone https://github.com/mrcyjanek/monero_c --recursive +$ ./apply_patches.sh monero # patch the libraries +$ ./build_single x86_64-linux-gnu -j$(nproc) +``` + +To get detailed information about building please select your host platform (the one that you will use to build the +monero wallet) + +- [I'm scared. How can I use prebuilds?](Using-prebuilds.md) +- [Linux](#linux) +- [macOS](#macos) +- [Windows](#windows) + +## Supported systems + +| Target | Builder | Notes | +|------------------|-----------------------------|----------------------------------------------------------------------------------| +| Windows | Linux, Docker, WSL2 | msys2 builds are not supported, there are hardcoded DLL paths in build_single.sh | +| macOS | Native, Linux, Docker, WSL2 | Native builds are being widely used, but are not endorsed by me personally. | +| iOS | macOS | | +| Android | Linux, Docker, WSL2 | | +| Linux | Native, Docker, WSL2 | | +| Linux/SailfishOS | Native, Docker | Required meego toolchain. | + +All supported systems are built on CI, so for the most up-to-date list of all supported systems, together with proper +dependencies please take a look at [full_check.yml](https://github.com/MrCyjaneK/monero_c/blob/master/.github/workflows/full_check.yaml) +file. + +### Linux + +Linux builds should be built on as old of a distro as possible - targeting `debian:oldoldstable`, main reason for that +is GLIBC compatibility (or lack of it). For some reason software compiled with newer GLIBC won't work on devices with +older GLIBC, so the solution is to simply build on the oldest possible os (or abandon GLIBC and use musl). + +- x86-64-linux-gnu +- i686-linux-gnu - deprecated by monero +- aarch64-linux-gnu + +[More details](Linux.md) + +#### SailfishOS + +Fully supported (except for armv7l devices). + +- i686-meego-linux-gnu +- aarch64-meego-linux-gnu + +More details: TBD + +#### Alpine Linux + +Requires dependency removed by upstream - it is preserved in `external/alpine/libexecinfo`. It could easily +be brought back - but since nobody uses it and nobody complained about it missing it kind of never landed in monero_c +after rewrite fully. That being said it should mostly work. + +- ~~x86_64-alpine-linux-musl~~ +- ~~aarch64-alpine-linux-musl~~ + +More details: TBD + +### Android + +Includes bumped NDK version + +- x86_64-linux-android +- ~~i686-linux-android~~ - unsupported, fails to build +- aarch64-linux-android +- armv7a-linux-androideabi + +[More details](Android.md) + +### Windows + +Msys2 shell is not supported, docker or WSL2 is requried to build + +- i686-w64-mingw32 - deprecated by monero +- x86_64-w64-mingw32 +- aarch64-w64-unknown - unsupported. + Though - if somebody can grab and send me a decent CopilotPC I'll be happy to work on that. As for now using x86_64 + build should be fine (but slower in runtime) solution. + +[More details](Windows.md) + +### macOS + +- x86_64-apple-darwin11 +- aarch64-apple-darwin11 +- host-apple-darwin +- x86_64-host-apple-darwin - alias for host-apple-darwin +- aarch64-host-apple-darwin alias for host-apple-darwin + +[More details](macOS.md) + +### iOS +- host-apple-ios - probably will be renamed to `aarch64-apple-ios` \ No newline at end of file diff --git a/docs/Writerside/topics/Linux.md b/docs/Writerside/topics/Linux.md new file mode 100644 index 00000000..7d3a2f14 --- /dev/null +++ b/docs/Writerside/topics/Linux.md @@ -0,0 +1,71 @@ +# Linux + +Building on linux has been tested on +- `debian:bullseye` (docker tag) + +## Install dependencies + + + + +$ apt update +$ apt install -y build-essential pkg-config autoconf libtool \ + ccache make cmake gcc g++ git curl lbzip2 libtinfo5 gperf + + + + +$ apt update +$ apt install -y build-essential pkg-config autoconf libtool \ + ccache make cmake gcc g++ git curl lbzip2 libtinfo5 gperf \ + gcc-aarch64-linux-gnu g++-aarch64-linux-gnu + + + + +$ apt update +$ apt install -y build-essential pkg-config autoconf libtool \ + ccache make cmake gcc g++ git curl lbzip2 libtinfo5 gperf \ + gcc-i686-linux-gnu g++-i686-linux-gnu + + + + +## Prepare source + +> If you are running in docker or have not configured git you may need to do the following: +> ```bash +> git config --global --add safe.directory '*' +> git config --global user.email "ci@mrcyjanek.net" +> git config --global user.name "CI mrcyjanek.net" +> ``` + +```bash +$ git clone https://github.com/mrcyjanek/monero_c --recursive +$ cd monero_c +$ ./apply_patches.sh monero +``` + +## Building + + + + +$ ./build_single.sh monero x86_64-linux-gnu -j$(nproc) + + + + +$ ./build_single.sh monero aarch64-linux-gnu -j$(nproc) + + + + +$ ./build_single.sh monero i686-linux-gnu -j$(nproc) + + + + +## Known issues + +None. Open an issue if you find something not working. \ No newline at end of file diff --git a/docs/Writerside/topics/Using-prebuilds.md b/docs/Writerside/topics/Using-prebuilds.md new file mode 100644 index 00000000..f4ff35e1 --- /dev/null +++ b/docs/Writerside/topics/Using-prebuilds.md @@ -0,0 +1,48 @@ +# Using prebuilds + +Prebuilds are more convenient way of using monero_c in your code (although these builds should **NOT** be used in +production). There are several ways in which you can use prebuilds + +## The monero_c way + +1. Go to https://github.com/MrCyjaneK/monero_c/releases +2. Click on the release that you are interested in +3. Download release-bundle.zip +4. Unzip it in monero_c directory + +That zip file contains all builds that monero_c supports prepared in the exactly same way as you would prepare them if +building on your own. This is the easiest way to get started. + +> Keep in mind that release-bundle.zip contains .xz files inside, so if you want to actually use them you need to use +> them you need to unxz them first +> ```bash +> $ unxz -f -k release/*/*.xz +> ``` + +## The monero_c way (different) + +Alternatively you can go to releases tab and grab whatever you need, there are over 40 libraries. Surely one will fit +your use case. + +## The build_moneroc.sh way + +This method is used by [xmruw](https://github.com/mrcyjanek/unnamed_monero_wallet) and +[monero-tui](https://github.com/Im-Beast/monero-tui). + +It supports both building and downloading prebuilds and putting them in correct location, [have a look at the code +yourself](https://github.com/MrCyjaneK/unnamed_monero_wallet/blob/master-rewrite/build_moneroc.sh) + +```bash +$ ./build_moneroc.sh + --prebuild # allow downloads of prebuilds + --coin # monero/wownero + --tag v0.18.3.3-RC45 # which tag to build / download + --triplet x86_64-linux-android # which triplet to build / download + --location android/.../jniLibs/x86_64 # where to but the libraries +``` + +## The cake wallet way + +There is a simple script in cake_wallet written in `dart` that runs on all platform (including windows) which downloads +all required libraries for selected platforms in one go. +[You can take look at it here](https://github.com/cake-tech/cake_wallet/blob/main/tool/download_moneroc_prebuilds.dart) \ No newline at end of file diff --git a/docs/Writerside/topics/Windows.md b/docs/Writerside/topics/Windows.md new file mode 100644 index 00000000..1cb931c2 --- /dev/null +++ b/docs/Writerside/topics/Windows.md @@ -0,0 +1,63 @@ +# Windows + +Building on windows has been tested on +- `debian:bullseye` (docker tag) +- `Ubuntu 22.04 WSL` + +## Install dependencies + + + + +$ apt update +$ apt install -y build-essential pkg-config autoconf libtool \ + ccache make cmake gcc g++ git curl lbzip2 libtinfo5 gperf \ + gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64 + + + + +$ apt update +$ apt install -y build-essential pkg-config autoconf libtool \ + ccache make cmake gcc g++ git curl lbzip2 libtinfo5 gperf \ + gcc-mingw-w64-i686 g++-mingw-w64-i686 + + + + +## Prepare source + +> If you are running in docker or have not configured git you may need to do the following: +> ```bash +> git config --global --add safe.directory '*' +> git config --global user.email "ci@mrcyjanek.net" +> git config --global user.name "CI mrcyjanek.net" +> ``` + +```bash +$ git clone https://github.com/mrcyjanek/monero_c --recursive +$ cd monero_c +$ ./apply_patches.sh monero +``` + +## Building + + + + +$ ./build_single.sh monero x86_64-w64-mingw32 -j$(nproc) + + + + +$ ./build_single.sh monero i686-w64-mingw32 -j$(nproc) + + + + +## Known issues + +### Dynamically loaded dependencies + +There are some dynamically loaded dependencies which are copied over from the OS package repository. All of them are +available in `release/` directory. \ No newline at end of file diff --git a/docs/Writerside/topics/about.md b/docs/Writerside/topics/about.md new file mode 100644 index 00000000..448e70f2 --- /dev/null +++ b/docs/Writerside/topics/about.md @@ -0,0 +1,59 @@ +# About + +![monero_c onefetch](../assets/onefetch.png) + +## Goal + +The goal of monero_c is simple, at least on the surface +- Build monero for all platforms +- Access monero functions from all languages +- Bring in new features used by wallets but still not merged upstream + +To achieve these tasks some major changes had to happen to monero. + +## Building + +For the most part `contrib/depends` directory of `monero` was used, as it is in perfect shape (that being said it's +terrible to debug when something goes wrong). But it doesn't work with iOS, and it doesn't work on macOS, so some +dependencies had to be pulled as a submodules. But that being said, linux can be used to build for all platforms (except +for iOS - you need macOS for that, and you also need that 100EUR/year license to actually be able to do something with +said library). + +This is especially good because any device can run linux, on WSL2 or under docker. + +## Accessing monero functions + +Though just building the library is not enough, if you just `make wallet_api` in the upstream code you end up in a +place where you technically have the functions in a dynamic library, but you can only use C++ ABI to interact with it. +Which is not ideal. Of course, it is doable, if you want to deal with `__ZNK6Monero10WalletImpl7addressEjj` instead of +`MONERO_Wallet_address`, and make sure that the way you pass in variables is what C++ expects. +I went with the simplest and most standard way of doing that - C ABI (which is what monero should offer in the first +place). Now with any language that supports C interop you can just go ahead and use monero wallet. + +All functionality is simplified to use only the following types: + +- bool +- int +- uint64_t +- void* +- const char* +- void + +## Bring in new features + +There are some extra features inside of the code like +- Polyseed support +- Background sync +- Airgap functions +- Coin control +- UR support +- Ledger support (on android and iSO) +- many fixes + +These features land in the `patches` directory, and are applied to the upstream monero code. + +## Summary + +monero_c extends monero functionality and also simplifies it by a huge extent, if you want to use monero - monero_c is +probably the way to go. +Are you ready to start? Let's see how to build the binary. \ No newline at end of file diff --git a/docs/Writerside/topics/macOS.md b/docs/Writerside/topics/macOS.md new file mode 100644 index 00000000..367893b8 --- /dev/null +++ b/docs/Writerside/topics/macOS.md @@ -0,0 +1,86 @@ +# macOS + +Building on linux has been tested on +- `macos-14` (github runner) +- `MacOS 15.0.1 Sequoia` (Native) +- `debian:bookworm` (docker tag) + +## Install dependencies + + + + +$ # install xcode 15.4 (or current latest) +$ brew install ccache unbound boost@1.76 zmq autoconf automake libtool +$ brew link boost@1.76 + + + + +$ # install xcode 15.4 (or current latest) +$ brew install ccache unbound boost@1.76 zmq autoconf automake libtool +$ brew link boost@1.76 +$ arch -x86_64 brew install ccache unbound boost@1.76 zmq autoconf automake libtool +$ arch -x86_64 brew link boost@1.76 + + + + +$ apt update +$ apt install -y build-essential pkg-config autoconf libtool \ + ccache make cmake gcc g++ git curl lbzip2 libtinfo5 gperf \ + python-is-python3 + + + + +## Prepare source + +> If you are running in docker or have not configured git you may need to do the following: +> ```bash +> git config --global --add safe.directory '*' +> git config --global user.email "ci@mrcyjanek.net" +> git config --global user.name "CI mrcyjanek.net" +> ``` + +```bash +$ git clone https://github.com/mrcyjanek/monero_c --recursive +$ cd monero_c +$ ./apply_patches.sh monero +``` + +## Building + + + + +$ ./build_single.sh monero x86_64-host-apple-darwin -j$(nproc) + + + + +$ ./build_single.sh monero aarch64-host-apple-darwin -j$(nproc) + + + + +$ arch -x86_64 ./build_single.sh monero x86_64-host-apple-darwin -j$(nproc) + + + + +$ ./build_single.sh monero x86_64-apple-darwin11 -j$(nproc) + + + + +$ ./build_single.sh monero aarch64-apple-darwin-11 -j$(nproc) + + + + +## Known issues + +### Creating fat library + +[Check cake_wallet solution](https://github.com/cake-tech/cake_wallet/blob/main/scripts/macos/build_monero_all.sh) \ No newline at end of file diff --git a/docs/Writerside/writerside.cfg b/docs/Writerside/writerside.cfg new file mode 100644 index 00000000..98e14351 --- /dev/null +++ b/docs/Writerside/writerside.cfg @@ -0,0 +1,11 @@ + + + + + + + + + + \ No newline at end of file diff --git a/docs/update_screenshot.sh b/docs/update_screenshot.sh new file mode 100755 index 00000000..a404047f --- /dev/null +++ b/docs/update_screenshot.sh @@ -0,0 +1,14 @@ +#!/bin/bash +set -x -e +go install github.com/homeport/termshot/cmd/termshot@main +cargo install onefetch +COMMIT_COUNT=$(git log --pretty=format:'' | wc -l | xargs) +echo Commit count: $COMMIT_COUNT +if (( $COMMIT_COUNT % 69 == 0 )) +then + echo "easter egg, yay!" + termshot --show-cmd --filename Writerside/assets/onefetch.png -- "onefetch --number-of-authors 0 -a html | lolcat" +else + echo "normal. Yay." + termshot --show-cmd --filename Writerside/assets/onefetch.png -- "onefetch --number-of-authors 0 -a c++" +fi \ No newline at end of file