From 1f50320fe131f4fc5ab82ffd42250a537eb47ce7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20Schj=C3=B8nhaug?= Date: Sat, 22 Jan 2022 09:23:48 +0100 Subject: [PATCH] General improvements to mobile instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Using
and tags in the INSTALL.md to collapse the various platforms for installing, making the rendered page shorter and easier to read. * Simplyfying the instructions for creating LND mobile * Fixed bug in checkout of latest tagged release * Fixed bug in command for moving proto definitions to same folder as xcframework file * Use Go 1.17.6 for building the Swift proto definitions * Added link to LND Builder’s Guide --- docs/INSTALL.md | 152 ++++++++++++--------- docs/release-notes/release-notes-0.14.2.md | 4 + mobile/README.md | 114 +++++++--------- 3 files changed, 145 insertions(+), 125 deletions(-) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 41943ed75..c5ff749b5 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -4,7 +4,8 @@ - [Installing a binary release](#installing-a-binary-release) - [Building a tagged version with Docker](#building-a-tagged-version-with-docker) - [Building a development version from source](#building-a-development-version-from-source) - - [Preliminaries for installing from source](#preliminaries-for-installing-from-source) + - [Installing Go](#installing-go) + - [Go modules](#go-modules) - [Installing lnd from source](#installing-lnd-from-source) - [Available Backend Operating Modes](#available-backend-operating-modes) - [btcd Options](#btcd-options) @@ -87,84 +88,110 @@ recommended for mainnet. The `master` branch can at times be unstable and running your node off of it can prevent it to go back to a previous, stable version if there are database migrations present. -### Preliminaries for installing from source - In order to work with [`lnd`](https://github.com/lightningnetwork/lnd), the - following build dependencies are required: +In order to work with [`lnd`](https://github.com/lightningnetwork/lnd), the +following build dependencies are required: - * **Go:** `lnd` is written in Go. To install, run one of the following commands: +### Installing Go +`lnd` is written in Go, with a minimum version of 1.16. To install, run one of +the following commands for your OS: - **Note**: The minimum version of Go supported is Go 1.16. We recommend that - users use the latest version of Go, which at the time of writing is - [`1.17.1`](https://blog.golang.org/go1.17.1). +
+ Linux (x86-64) + + ``` + wget https://dl.google.com/go/go1.17.1.linux-amd64.tar.gz + sha256sum go1.17.1.linux-amd64.tar.gz | awk -F " " '{ print $1 }' + ``` + The final output of the command above should be + `dab7d9c34361dc21ec237d584590d72500652e7c909bf082758fb63064fca0ef`. If it + isn't, then the target REPO HAS BEEN MODIFIED, and you shouldn't install + this version of Go. If it matches, then proceed to install Go: + ``` + sudo tar -C /usr/local -xzf go1.17.1.linux-amd64.tar.gz + export PATH=$PATH:/usr/local/go/bin + ``` +
- On Linux: +
+ Linux (ARMv6) + + ``` + wget https://dl.google.com/go/go1.17.1.linux-armv6l.tar.gz + sha256sum go1.17.1.linux-armv6l.tar.gz | awk -F " " '{ print $1 }' + ``` - (x86-64) - ``` - wget https://dl.google.com/go/go1.17.1.linux-amd64.tar.gz - sha256sum go1.17.1.linux-amd64.tar.gz | awk -F " " '{ print $1 }' - ``` + The final output of the command above should be + `ed3e4dbc9b80353f6482c441d65b51808290e94ff1d15d56da5f4a7be7353758`. If it + isn't, then the target REPO HAS BEEN MODIFIED, and you shouldn't install + this version of Go. If it matches, then proceed to install Go: + ``` + tar -C /usr/local -xzf go1.17.1.linux-armv6l.tar.gz + export PATH=$PATH:/usr/local/go/bin + ``` + +
- The final output of the command above should be - `dab7d9c34361dc21ec237d584590d72500652e7c909bf082758fb63064fca0ef`. If it - isn't, then the target REPO HAS BEEN MODIFIED, and you shouldn't install - this version of Go. If it matches, then proceed to install Go: - ``` - sudo tar -C /usr/local -xzf go1.17.1.linux-amd64.tar.gz - export PATH=$PATH:/usr/local/go/bin - ``` +
+ macOS + + First, install [Homebrew](https://brew.sh) if you don‘t already have it. - (ARMv6) - ``` - wget https://dl.google.com/go/go1.17.1.linux-armv6l.tar.gz - sha256sum go1.17.1.linux-armv6l.tar.gz | awk -F " " '{ print $1 }' - ``` + Then - The final output of the command above should be - `ed3e4dbc9b80353f6482c441d65b51808290e94ff1d15d56da5f4a7be7353758`. If it - isn't, then the target REPO HAS BEEN MODIFIED, and you shouldn't install - this version of Go. If it matches, then proceed to install Go: - ``` - tar -C /usr/local -xzf go1.17.1.linux-armv6l.tar.gz - export PATH=$PATH:/usr/local/go/bin - ``` + ``` + brew install go + ``` - On Mac OS X: - ``` - brew install go@1.17.1 - ``` +
- On FreeBSD: - ``` - pkg install go - ``` +
+ FreeBSD + + ``` + pkg install go + ``` - Alternatively, one can download the pre-compiled binaries hosted on the - [Golang download page](https://golang.org/dl/). If one seeks to install - from source, then more detailed installation instructions can be found - [here](https://golang.org/doc/install). + Alternatively, one can download the pre-compiled binaries hosted on the + [Golang download page](https://golang.org/dl/). If one seeks to install + from source, then more detailed installation instructions can be found + [here](https://golang.org/doc/install). +
- At this point, you should set your `$GOPATH` environment variable, which - represents the path to your workspace. By default, `$GOPATH` is set to - `~/go`. You will also need to add `$GOPATH/bin` to your `PATH`. This ensures - that your shell will be able to detect the binaries you install. +***Important*** - ```shell - ⛰ export GOPATH=~/gocode - ⛰ export PATH=$PATH:$GOPATH/bin - ``` +At this point, you should set your `$GOPATH` environment variable, which +represents the path to your workspace. By default, `$GOPATH` is set to +`~/go`. You will also need to add `$GOPATH/bin` to your `PATH`. This ensures +that your shell will be able to detect the binaries you install. - We recommend placing the above in your .bashrc or in a setup script so that - you can avoid typing this every time you open a new terminal window. +```shell +⛰ export GOPATH=~/go +⛰ export PATH=$PATH:$GOPATH/bin +``` - * **Go modules:** This project uses [Go modules](https://github.com/golang/go/wiki/Modules) - to manage dependencies as well as to provide *reproducible builds*. +--- - Usage of Go modules (with Go 1.13) means that you no longer need to clone - `lnd` into your `$GOPATH` for development purposes. Instead, your `lnd` - repo can now live anywhere! +We recommend placing the above in your `.bashrc`, `.zshrc` or in a setup script +so that you can avoid typing this every time you open a new terminal window. + +### Go modules + +This project uses [Go modules](https://github.com/golang/go/wiki/Modules) +to manage dependencies as well as to provide *reproducible builds*. + +Usage of Go modules (with Go 1.13) means that you no longer need to clone +`lnd` into your `$GOPATH` for development purposes. Instead, your `lnd` +repo can now live anywhere! + +--- +Note: For mobile development, having the source code in `$GOPATH` is still +required due to a current limitation in +[Go mobile](https://pkg.go.dev/golang.org/x/mobile). Take a look at the +documentation for [building mobile libraries](../mobile) to learn more. + +--- ### Installing lnd from source @@ -189,7 +216,6 @@ a small modification to the above command: ⛰ make install ``` - **NOTE**: Our instructions still use the `$GOPATH` directory from prior versions of Go, but with Go 1.13, it's now possible for `lnd` to live _anywhere_ on your file system. diff --git a/docs/release-notes/release-notes-0.14.2.md b/docs/release-notes/release-notes-0.14.2.md index b473e5d17..7363af62e 100644 --- a/docs/release-notes/release-notes-0.14.2.md +++ b/docs/release-notes/release-notes-0.14.2.md @@ -99,10 +99,14 @@ Postgres](https://github.com/lightningnetwork/lnd/pull/6111) history](https://github.com/lightningnetwork/lnd/pull/6180) by adding the `force` flag to the `XImportMissionControl` RPC call. +## Documentation + +* [General improvements to the mobile documentation](https://github.com/lightningnetwork/lnd/pull/6181). # Contributors (Alphabetical Order) * Andras Banki-Horvath +* Andreas Schjønhaug * Bjarne Magnussen * Elle Mouton * Harsha Goli diff --git a/mobile/README.md b/mobile/README.md index 22bb80e89..19f050617 100644 --- a/mobile/README.md +++ b/mobile/README.md @@ -2,100 +2,89 @@ ## Prerequisites -### Go language +To build for iOS, you need to run macOS with either +[Command Line Tools](https://developer.apple.com/download/all/?q=command%20line%20tools) +or [Xcode](https://apps.apple.com/app/xcode/id497799835) installed. -- [Install](https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md#preliminaries-for-installing-from-source) `GO` language. -- Provide `$GOPATH` to `.zshrc` or `.bash_profile` files. +To build for Android, you need either +[Android Studio](https://developer.android.com/studio) or +[Command Line Tools](https://developer.android.com/studio#downloads) installed, which in turn must be used to install [Android NDK](https://developer.android.com/ndk/). + + +### Go and Go mobile + +First, follow the instructions to [install Go](https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md#building-a-development-version-from-source). + +Then, install [Go mobile](https://github.com/golang/go/wiki/Mobile) and +initialize it: ```shell -export GOPATH=$HOME/go -export PATH=$PATH:$GOPATH/bin +⛰ go install golang.org/x/mobile/cmd/gomobile@latest +⛰ go mod download golang.org/x/mobile +⛰ gomobile init ``` -Or any path you want it to be in. - ### Docker -- Install and run [Docker](https://www.docker.com/products/docker-desktop). +Install and run [Docker](https://www.docker.com/products/docker-desktop). ### Make -- Check that `make` is available by running the following command without errors: +Check that `make` is available by running the following command without errors: ```shell ⛰ make --version ``` -### Go mobile - -- Install [gomobile](https://github.com/golang/go/wiki/Mobile): - -```shell -⛰ go install golang.org/x/mobile/cmd/gomobile@latest -``` - -- Install `gobind` - -```shell -⛰ go install golang.org/x/mobile/cmd/gobind@latest -``` - ## Building the libraries -Note that `gomobile` only supports building projects from `GOPATH` at this point. So, before continuing, be sure to be in the `src` folder: +Note that `gomobile` only supports building projects from `$GOPATH` at this +point. However, with the introduction of Go modules, the source code files are +no longer installed there by default. + +To be able to do so, we must turn off module and using the now deprecated +`go get` command before turning modules back on again. + +```shell +⛰ go env -w GO111MODULE="off" +⛰ go get github.com/lightningnetwork/lnd +⛰ go get golang.org/x/mobile/bind +⛰ go env -w GO111MODULE="on" +``` + +Finally, let’s change directory to the newly created lnd folder inside `$GOPATH`: ```shell ⛰ cd $GOPATH/src/github.com/lightningnetwork/lnd ``` -To checkout the latest tagged release of lnd, run +It is not recommended building from the master branch for mainnet. To checkout +the latest tagged release of lnd, run ```shell -⛰ git checkout $(git describe --tags --abbrev=0) +⛰ git checkout $(git describe --match "v[0-9]*" --abbrev=0) ``` -Or, the second option: just clone the project and checkout to any branch/tag (pay attention to the dot in the end). - -```shell -⛰ git clone https://github.com/lightningnetwork/lnd . -``` - -#### For Android: - -Move to the folder or create one: - -```shell -⛰ cd $GOPATH/src/golang.org/x -``` - -After that clone the goland mobile repo - -```shell -⛰ git clone https://github.com/golang/mobile -``` - -### Building `lnd` for iOS +### iOS ```shell ⛰ make ios ``` -### Building `lnd` for Android +The Xcode framework file will be found in `mobile/build/ios/Lndmobile.xcframework`. -Go to `$GOPATH/src/github.com/lightningnetwork/lnd` and run the command below (make sure that the Docker engine is running): +### Android ```shell ⛰ make android ``` -`make mobile` will build both iOS and Android libraries. +The AAR library file will be found in `mobile/build/android/Lndmobile.aar`. -### Libraries +--- +Tip: `make mobile` will build both iOS and Android libraries. -After the build has succeeded, the libraries will be found in -`mobile/build/ios/Lndmobile.xcframework` and -`mobile/build/android/Lndmobile.aar`. Reference your platforms' SDK -documentation for how to add the library to your project. +--- ## Generating proto definitions @@ -120,7 +109,7 @@ following commands: ``` RUN apt-get install -y wget \ - && wget -c https://golang.org/dl/go1.17.3.linux-amd64.tar.gz -O - \ + && wget -c https://golang.org/dl/go1.17.6.linux-amd64.tar.gz -O - \ | tar -xz -C /usr/local ENV GOPATH=/go ENV PATH=$PATH:/usr/local/go/bin:/go/bin @@ -143,7 +132,7 @@ Tip: The generated Swift files will be found in various folders. If you’d like to move them to the same folder as the framework file, run ```shell -⛰ `find . -name "*.swift" -print0 | xargs -0 -I {} mv {} mobile/build/ios`. +⛰ `find . -name "*.swift" -print0 | xargs -0 -I {} mv {} mobile/build/ios` ``` `Lndmobile.xcframework` and all Swift files should now be added to your Xcode @@ -214,7 +203,9 @@ protobuf { - Then, copy all the proto files from `lnd/lnrpc` to your `proto` folder, saving the structure. - Build the project and wait until you see the generated Java proto files in the `build` folder. -#### Note: + +--- +*Note:* If Android Studio tells you that the `aar` file cannot be included into the `app-bundle`, this is a workaround: @@ -234,7 +225,7 @@ artifacts.add("default", file('Lndmobile.aar')) ```shell implementation project(":lndmobile", { "default" }) ``` - +--- ## Options @@ -252,6 +243,5 @@ To support subservers that have APIs with name conflicts, pass the "prefix" flag ## API docs -[LND gRPC API Reference](https://api.lightning.community) - -TODO(halseth) +- [LND gRPC API Reference](https://api.lightning.community) +- [LND Builder’s Guide](https://docs.lightning.engineering) \ No newline at end of file