|
| 1 | +# Building mobile libraries |
| 2 | + |
| 3 | +## Prerequisites |
| 4 | + |
| 5 | +To build for iOS, you need to run macOS with either |
| 6 | +[Command Line Tools](https://developer.apple.com/download/all/?q=command%20line%20tools) |
| 7 | +or [Xcode](https://apps.apple.com/app/xcode/id497799835) installed. |
| 8 | + |
| 9 | +To build for Android, you need either |
| 10 | +[Android Studio](https://developer.android.com/studio) or |
| 11 | +[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/). |
| 12 | + |
| 13 | + |
| 14 | +### Go and Go mobile |
| 15 | + |
| 16 | +First, follow the instructions to [install Go](https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md#building-a-development-version-from-source). |
| 17 | + |
| 18 | +Then, install [Go mobile](https://github.com/golang/go/wiki/Mobile) and |
| 19 | +initialize it: |
| 20 | + |
| 21 | +```shell |
| 22 | +⛰ go install golang.org/x/mobile/cmd/gomobile@latest |
| 23 | +⛰ go mod download golang.org/x/mobile |
| 24 | +⛰ gomobile init |
| 25 | +``` |
| 26 | + |
| 27 | +### Docker |
| 28 | + |
| 29 | +Install and run [Docker](https://www.docker.com/products/docker-desktop). |
| 30 | + |
| 31 | +### Make |
| 32 | + |
| 33 | +Check that `make` is available by running the following command without errors: |
| 34 | + |
| 35 | +```shell |
| 36 | +⛰ make --version |
| 37 | +``` |
| 38 | + |
| 39 | +## Building the libraries |
| 40 | + |
| 41 | +Note that `gomobile` only supports building projects from `$GOPATH` at this |
| 42 | +point. However, with the introduction of Go modules, the source code files are |
| 43 | +no longer installed there by default. |
| 44 | + |
| 45 | +To be able to do so, we must turn off module and using the now deprecated |
| 46 | +`go get` command before turning modules back on again. |
| 47 | + |
| 48 | +```shell |
| 49 | +⛰ go env -w GO111MODULE="off" |
| 50 | +⛰ go get github.com/lightninglabs/lightning-terminal |
| 51 | +⛰ go get golang.org/x/mobile/bind |
| 52 | +⛰ go env -w GO111MODULE="on" |
| 53 | +``` |
| 54 | + |
| 55 | +Finally, let’s change directory to the newly created lightning-terminal folder inside `$GOPATH`: |
| 56 | + |
| 57 | +```shell |
| 58 | +⛰ cd $GOPATH/src/github.com/lightninglabs/lightning-terminal |
| 59 | +``` |
| 60 | + |
| 61 | +It is not recommended building from the master branch for mainnet. To checkout |
| 62 | +the latest tagged release of Lightning Terminal, run |
| 63 | + |
| 64 | +```shell |
| 65 | +⛰ git checkout $(git describe --match "v[0-9]*" --abbrev=0) |
| 66 | +``` |
| 67 | + |
| 68 | +### iOS |
| 69 | + |
| 70 | +```shell |
| 71 | +⛰ make ios |
| 72 | +``` |
| 73 | + |
| 74 | +The Xcode framework file will be found in `mobile/build/ios/Litdmobile.xcframework`. |
| 75 | + |
| 76 | +### Android |
| 77 | + |
| 78 | +```shell |
| 79 | +⛰ make android |
| 80 | +``` |
| 81 | + |
| 82 | +The AAR library file will be found in `mobile/build/android/Litdmobile.aar`. |
| 83 | + |
| 84 | +--- |
| 85 | +Tip: `make mobile` will build both iOS and Android libraries. |
| 86 | + |
| 87 | +--- |
| 88 | + |
| 89 | +## Generating proto definitions |
| 90 | + |
| 91 | +In order to call the methods in the generated library, the serialized proto for |
| 92 | +the given RPC call must be provided. Similarly, the response will be a |
| 93 | +serialized proto. |
| 94 | + |
| 95 | +### iOS |
| 96 | + |
| 97 | +In order to generate protobuf definitions for iOS, add `--swift_out=.` to the |
| 98 | +first `protoc` invocation found in [ `gen_protos.sh` ](../lnrpc/gen_protos.sh). |
| 99 | + |
| 100 | +Then, some changes to [Dockerfile](../lnrpc/Dockerfile) need to be done in |
| 101 | +order to use the [Swift protobuf](https://github.com/apple/swift-protobuf) |
| 102 | +plugin with protoc: |
| 103 | + |
| 104 | +1. Replace the base image with `FROM swift:focal` so that Swift can be used. |
| 105 | +2. `clang-format='1:7.0*'` is unavailable in Ubuntu Focal. Change that to |
| 106 | +`clang-format='1:10.0*'`. |
| 107 | +3. On the next line, install Go and set the environment variables by adding the |
| 108 | +following commands: |
| 109 | + |
| 110 | +``` |
| 111 | +RUN apt-get install -y wget \ |
| 112 | + && wget -c https://golang.org/dl/go1.17.6.linux-amd64.tar.gz -O - \ |
| 113 | + | tar -xz -C /usr/local |
| 114 | +ENV GOPATH=/go |
| 115 | +ENV PATH=$PATH:/usr/local/go/bin:/go/bin |
| 116 | +``` |
| 117 | + |
| 118 | +4. At the end of the file, just above `CMD`, add the following `RUN` command. |
| 119 | +This will download and compile the latest tagged release of Swift protobuf. |
| 120 | + |
| 121 | +``` |
| 122 | +RUN git clone https://github.com/apple/swift-protobuf.git \ |
| 123 | +&& cd swift-protobuf \ |
| 124 | +&& git checkout $(git describe --tags --abbrev=0) \ |
| 125 | +&& swift build -c release \ |
| 126 | +&& mv .build/release/protoc-gen-swift /bin |
| 127 | +``` |
| 128 | + |
| 129 | +Finally, run `make rpc`. |
| 130 | + |
| 131 | +Tip: The generated Swift files will be found in various folders. If you’d like |
| 132 | +to move them to the same folder as the framework file, run |
| 133 | + |
| 134 | +```shell |
| 135 | +⛰ find . -name "*.swift" -print0 | xargs -0 -I {} mv {} mobile/build/ios |
| 136 | +``` |
| 137 | + |
| 138 | +`Litdmobile.xcframework` and all Swift files should now be added to your Xcode |
| 139 | +project. You will also need to add [Swift Protobuf](https://github.com/apple/swift-protobuf) |
| 140 | +to your project to support the generated code. |
| 141 | + |
| 142 | +### Android |
| 143 | + |
| 144 | +#### First option: |
| 145 | + |
| 146 | +In order to generate protobuf definitions for Android, add `--java_out=.` |
| 147 | + |
| 148 | +to the first `protoc` invocation found in |
| 149 | +[ `gen_protos.sh` ](../lnrpc/gen_protos.sh). Then, run `make rpc`. |
| 150 | + |
| 151 | + |
| 152 | +#### Second option (preferable): |
| 153 | + |
| 154 | +- You have to install the profobuf plugin to your Android application. |
| 155 | +Please, follow this link https://github.com/google/protobuf-gradle-plugin. |
| 156 | +- Add this line to your `app build.gradle` file. |
| 157 | +```shell |
| 158 | +classpath "com.google.protobuf:protobuf-gradle-plugin:0.8.17" |
| 159 | +``` |
| 160 | +- Create a `proto` folder under the `main` folder. |
| 161 | + |
| 162 | + |
| 163 | + |
| 164 | +- Add `aar` file to libs folder. |
| 165 | + |
| 166 | +- After that add these lines to your `module's` `build.gradle` file: |
| 167 | + |
| 168 | +```shell |
| 169 | +plugins { |
| 170 | + id "com.google.protobuf" |
| 171 | +} |
| 172 | + |
| 173 | +android { |
| 174 | + sourceSets { |
| 175 | + main { |
| 176 | + proto { |
| 177 | + |
| 178 | + } |
| 179 | + } |
| 180 | + } |
| 181 | +} |
| 182 | + |
| 183 | +dependencies { |
| 184 | + implementation fileTree(dir: "libs", include: ["*.jar"]) |
| 185 | + implementation "com.google.protobuf:protobuf-javalite:${rootProject.ext.javalite_version}" |
| 186 | +} |
| 187 | + |
| 188 | +protobuf { |
| 189 | + protoc { |
| 190 | + artifact = "com.google.protobuf:protoc:${rootProject.ext.protoc_version}" |
| 191 | + } |
| 192 | + generateProtoTasks { |
| 193 | + all().each { task -> |
| 194 | + task.builtins { |
| 195 | + java { |
| 196 | + option "lite" |
| 197 | + } |
| 198 | + } |
| 199 | + } |
| 200 | + } |
| 201 | +} |
| 202 | +``` |
| 203 | +- Then, copy all the proto files from `lnd/lnrpc` to your `proto` folder, saving the structure. |
| 204 | +- Build the project and wait until you see the generated Java proto files in the `build` folder. |
| 205 | + |
| 206 | + |
| 207 | +--- |
| 208 | +*Note:* |
| 209 | + |
| 210 | +If Android Studio tells you that the `aar` file cannot be included into the `app-bundle`, this is a workaround: |
| 211 | + |
| 212 | +1. Create a separate gradle module |
| 213 | +2. Remove everything from there and leave only `aar` and `build.gradle`. |
| 214 | + |
| 215 | + |
| 216 | + |
| 217 | +3. Gradle file should contain only these lines: |
| 218 | + |
| 219 | +```shell |
| 220 | +configurations.maybeCreate("default") |
| 221 | +artifacts.add("default", file('Litdmobile.aar')) |
| 222 | +``` |
| 223 | + |
| 224 | +4. In `dependencies` add this line instead of depending on `libs` folder: |
| 225 | +```shell |
| 226 | +implementation project(":litdmobile", { "default" }) |
| 227 | +``` |
| 228 | +--- |
| 229 | +
|
| 230 | +## Calling the API |
| 231 | +
|
| 232 | +In LND v0.15+ all API methods have prefixed the generated methods with the subserver name. This is required to support subservers with name conflicts. |
| 233 | +
|
| 234 | +eg. `QueryScores` is now `AutopilotQueryScores`. `GetBlockHeader` is now `NeutrinoKitGetBlockHeader`. |
| 235 | +
|
| 236 | +## API docs |
| 237 | +
|
| 238 | +- [LND gRPC API Reference](https://api.lightning.community) |
| 239 | +- [LND Builder’s Guide](https://docs.lightning.engineering) |
0 commit comments