tiamak/monero_c
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial work on docs (#69)

Browse Source 
* initial work on docs
* fix DOCKER_VERSION
* update location
* add the path **properly**
* Update docs workflow
This commit is contained in:
cyan
2024-10-17 10:50:22 +02:00
committed by GitHub
parent 939040032f
commit d04dcf67ec
20 changed files with 623 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/.idea/.gitignore generated vendored Normal file
View File

@@ -0,0 +1,3 @@
# Default ignored files
/shelf/
/workspace.xml

8
docs/.idea/docs.iml generated Normal file
View File

@@ -0,0 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<module type="EMPTY_MODULE" version="4">
<component name="NewModuleRootManager">
<content url="file://$MODULE_DIR$" />
<orderEntry type="inheritedJdk" />
<orderEntry type="sourceFolder" forTests="false" />
</component>
</module>

8
docs/.idea/modules.xml generated Normal file
View File

@@ -0,0 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="ProjectModuleManager">
<modules>
<module fileurl="file://$PROJECT_DIR$/.idea/docs.iml" filepath="$PROJECT_DIR$/.idea/docs.iml" />
</modules>
</component>
</project>

6
docs/.idea/vcs.xml generated Normal file
View File

@@ -0,0 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="VcsDirectoryMappings">
<mapping directory="$PROJECT_DIR$/.." vcs="Git" />
</component>
</project>

BIN
docs/Writerside/assets/onefetch.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 297 KiB

6
docs/Writerside/c.list Normal file
View File

@@ -0,0 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE categories
SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
<categories>
<category id="wrs" name="Writerside documentation" order="1"/>
</categories>

13
docs/Writerside/cfg/buildprofiles.xml Normal file
View File

@@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE buildprofiles SYSTEM "https://resources.jetbrains.com/writerside/1.0/build-profiles.dtd">
<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<variables></variables>
<build-profile instance="in">
<variables>
<noindex-content>true</noindex-content>
</variables>
</build-profile>
</buildprofiles>

7
docs/Writerside/cfg/glossary.xml Normal file
View File

@@ -0,0 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE terms SYSTEM "https://resources.jetbrains.com/writerside/1.0/glossary.dtd">
<terms>
<term name="foo">
Description of what "foo" is.
</term>
</terms>

17
docs/Writerside/in.tree Normal file
View File

@@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE instance-profile
SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
<instance-profile id="in"
name="monero_c docs"
start-page="about.md">
<toc-element topic="about.md"/>
<toc-element topic="Building.md">
<toc-element topic="Using-prebuilds.md"/>
<toc-element topic="Linux.md"/>
<toc-element topic="Android.md"/>
<toc-element topic="Windows.md"/>
<toc-element topic="macOS.md"/>
</toc-element>
</instance-profile>

52
docs/Writerside/topics/Android.md Normal file
View File

@@ -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
<tabs>
<tab title="x86_64">
<code-block>
$ ./build_single.sh monero x86_64-linux-android -j$(nproc)
</code-block>
</tab>
<tab title="aarch64">
<code-block>
$ ./build_single.sh monero aarch64-linux-android -j$(nproc)
</code-block>
</tab>
<tab title="armv7a">
<code-block>
$ ./build_single.sh monero armv7a-linux-androideabi -j$(nproc)
</code-block>
</tab>
</tabs>
## Known issues
None. Open an issue if you find something not working.

99
docs/Writerside/topics/Building.md Normal file
View File

@@ -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`

71
docs/Writerside/topics/Linux.md Normal file
View File

@@ -0,0 +1,71 @@
# Linux
Building on linux has been tested on
- `debian:bullseye` (docker tag)
## Install dependencies
<tabs>
<tab title="x86_64">
<code-block>
$ apt update
$ apt install -y build-essential pkg-config autoconf libtool \
ccache make cmake gcc g++ git curl lbzip2 libtinfo5 gperf
</code-block>
</tab>
<tab title="aarch64">
<code-block>
$ 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
</code-block>
</tab>
<tab title="i686">
<code-block>
$ 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
</code-block>
</tab>
</tabs>
## 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
<tabs>
<tab title="x86_64">
<code-block>
$ ./build_single.sh monero x86_64-linux-gnu -j$(nproc)
</code-block>
</tab>
<tab title="aarch64">
<code-block>
$ ./build_single.sh monero aarch64-linux-gnu -j$(nproc)
</code-block>
</tab>
<tab title="i686">
<code-block>
$ ./build_single.sh monero i686-linux-gnu -j$(nproc)
</code-block>
</tab>
</tabs>
## Known issues
None. Open an issue if you find something not working.

48
docs/Writerside/topics/Using-prebuilds.md Normal file
View File

@@ -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)

63
docs/Writerside/topics/Windows.md Normal file
View File

@@ -0,0 +1,63 @@
# Windows
Building on windows has been tested on
- `debian:bullseye` (docker tag)
- `Ubuntu 22.04 WSL`
## Install dependencies
<tabs>
<tab title="x86_64">
<code-block>
$ 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
</code-block>
</tab>
<tab title="i686">
<code-block>
$ 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
</code-block>
</tab>
</tabs>
## 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
<tabs>
<tab title="x86_64">
<code-block>
$ ./build_single.sh monero x86_64-w64-mingw32 -j$(nproc)
</code-block>
</tab>
<tab title="i686">
<code-block>
$ ./build_single.sh monero i686-w64-mingw32 -j$(nproc)
</code-block>
</tab>
</tabs>
## 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.

59
docs/Writerside/topics/about.md Normal file
View File

@@ -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.

86
docs/Writerside/topics/macOS.md Normal file
View File

@@ -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
<tabs>
<tab title="Native">
<code-block>
$ # install xcode 15.4 (or current latest)
$ brew install ccache unbound boost@1.76 zmq autoconf automake libtool
$ brew link boost@1.76
</code-block>
</tab>
<tab title="Native (Rosetta2)">
<code-block>
$ # 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
</code-block>
</tab>
<tab title="Linux">
<code-block>
$ apt update
$ apt install -y build-essential pkg-config autoconf libtool \
ccache make cmake gcc g++ git curl lbzip2 libtinfo5 gperf \
python-is-python3
</code-block>
</tab>
</tabs>
## 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
<tabs>
<tab title="Native for x86_64 macOS">
<code-block>
$ ./build_single.sh monero x86_64-host-apple-darwin -j$(nproc)
</code-block>
</tab>
<tab title="Native for aarch64 macOS">
<code-block>
$ ./build_single.sh monero aarch64-host-apple-darwin -j$(nproc)
</code-block>
</tab>
<tab title="Native for x86_64 macOS (Rosseta2)">
<code-block>
$ arch -x86_64 ./build_single.sh monero x86_64-host-apple-darwin -j$(nproc)
</code-block>
</tab>
<tab title="Linux for x86_64 macOS">
<code-block>
$ ./build_single.sh monero x86_64-apple-darwin11 -j$(nproc)
</code-block>
</tab>
<tab title="Linux for aarch64 macOS">
<code-block>
$ ./build_single.sh monero aarch64-apple-darwin-11 -j$(nproc)
</code-block>
</tab>
</tabs>
## Known issues
### Creating fat library
[Check cake_wallet solution](https://github.com/cake-tech/cake_wallet/blob/main/scripts/macos/build_monero_all.sh)

11
docs/Writerside/writerside.cfg Normal file
View File

@@ -0,0 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/writerside/1.0/ihp.dtd">
<ihp version="2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/writerside-cfg.xsd">
<topics dir="topics"/>
<images dir="images" web-path="images"/>
<categories src="c.list"/>
<vars src="v.list"/>
<instance src="in.tree"/>
</ihp>

14
docs/update_screenshot.sh Executable file
View File

@@ -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