Before building, make sure that your enviroment has the variable `ZCASH_NETWORK_ENVIRONMENT` set to `MAINNET` or `TESTNET`.
### Custom build phases warning
When running `pod install` you will see this warning upon sucess:
```` bash
[!] ZcashLightClientKit has added 2 script phases. Please inspect before executing a build.
See `https://guides.cocoapods.org/syntax/podspec.html#script_phases` for more information.
````
Integrating Rust code with Swift code and delivering it in a consistent and (build) reproducible way, is hard. We've taken the lead to get that burden off your shoulders as much as possible by leveraging the `prepare_command` and `script_phases` features from Cocoapods to carefully generate the `TESTNET` and `MAINNET` builds as simple and less error prone as we could think it could be. Which started as some simple vanilla scripts, ended up being some kind of "Build System" on its own. Nothing is written on stone, and we accept collaborations and improvements in this matter too.
## Build system
This section explains the 'Build System' that integrates the rust code and creates the corresponding environment
### Overview
There are some basic steps to build ZcashLightClientKit. Even though they are 'basic' they can be cumbersome. So we automated them in scripts.
**1. Pod install and `prepare_command`**
ZcashLightClientKit needs files to be present at pod installation time, but that can't be defined properly yet and depend on librustzcash building properly and for an environment to be set up at build time. For know we just need to let Cocoapods that these files exist:
-`${ZCASH_POD_SRCROOT}/zcashlc/libzcashlc.a` this is the librustzcash build .a file itself
-`lib/libzcashlc.a` (as vendored library that will be added as an asset by xcodeproj)
-`ZcashSDK.generated.swift` which contains sensitive values for the SDK that change depending on the network environment we are building for
-`WalletBirthday+saplingtree.generated.swift` helper functions to import existing wallets.
**2. Build Phase**
The build Phase scripts executes withing the Xcode Build Step and has all the known variables of a traditional build at hand.
```` ruby
s.script_phase = {
:name => 'Build generate constants and build librustzcash',
:script => 'sh ${PODS_TARGET_SRCROOT}/Scripts/generate_zcashsdk_constants.sh && sh ${PODS_TARGET_SRCROOT}/Scripts/build_librustzcash_xcode.sh',
This step will generate files needed on the next steps and build the librustzcash with Xcode but *not using cargo's built-in xcode integration*
**a. Generating ZcashSDK constants**
To run this you need `Sourcery`. We use `Stencil` templates to create this files based on the `ZCASH_NETWORK_ENVIRONMENT` value of your choice. You can either integrate sourcery with cocoapods or as part of your environment.
All generated files will be located in the Pods source root within the `Generated` folder. `ZCASH_SDK_GENERATED_SOURCES_FOLDER` represents that path in the build system
**b. Building librust zcash and integrating it to the pod structure.**
Where the magic happens. Here we will make sure that everything is set up properly to start building librustzcash. When on mainnet, the build will append a parameter to include mainnet features.
**Safeguards points**:
if it appears that you are about to build something smelly, we will let you know. Combining testnet and mainnet values and artifacts and viceversa leads to unstable builds and may cause lost of funds if ran on production.
echo "build mismatch. You previously build a Different network environment. It appears that your build could be inconsistent if proceeding. Please clean your Pods/ folder and clean your build before running your next build."
When performing a clean, we will clean the rust build folders.
### Scripts
On the Scripts folder you will find the following files:
````
| Scripts
|-/prepare_zcash_sdk.sh
|-/generate_test_constants.sh
|-/build_librustzcash_xcode.sh
|-/build_librustzcash.sh
|-/generate_zcashsdk_constants.sh
|-/script_commons.sh
````
#### prepare_zcash_sdk.sh
This script is run by the Cocoapods 'preapare_command'.
```` Ruby
s.prepare_command = <<-CMD
sh Scripts/prepare_zcash_sdk.sh
CMD
````
It basically creates empty files that cocoapods needs to pick up on it's pod structure but that are still not present in the file system and that will be generated in later build phases.
NOTE: pod install will only run this phase when no Pods/ folder is present or if your pod hash has changed or is not present on manifest.lock. When in doubt, just clean the Pods/ folder and start over. That usually gets rid of weirdness caused by Xcode caching a lot of stuff you are not aware of.
#### script_commons.sh
A lot of important environment variables and helper functions live in the `script_commons.sh`.
This project follows [semantic versioning](https://semver.org/) with pre-release versions. An example of a valid version number is `1.0.4-alpha11` denoting the `11th` iteration of the `alpha` pre-release of version `1.0.4`. Stable releases, such as `1.0.4` will not contain any pre-release identifiers. Pre-releases include the following, in order of stability: `alpha`, `beta`, `rc`. Version codes offer a numeric representation of the build name that always increases. The first six significant digits represent the major, minor and patch number (two digits each) and the last 3 significant digits represent the pre-release identifier. The first digit of the identifier signals the build type. Lastly, each new build has a higher version code than all previous builds. The following table breaks this down:
#### Build Types
| Type | Purpose | Stability | Audience | Identifier | Example Version |
| **alpha** | **Sandbox.** For developers to verify behavior and try features. Things seen here might never go to production. Most bugs here can be ignored.| Unstable: Expect bugs | Internal developers | 0XX | 1.2.3-alpha04 (10203004) |
| **beta** | **Hand-off.** For developers to present finished features. Bugs found here should be reported and immediately addressed, if they relate to recent changes. | Unstable: Report bugs | Internal stakeholders | 2XX | 1.2.3-beta04 (10203204) |
| **release candidate** | **Hardening.** Final testing for an app release that we believe is ready to go live. The focus here is regression testing to ensure that new changes have not introduced instability in areas that were previously working. | Stable: Hunt for bugs | External testers | 4XX | 1.2.3-rc04 (10203404) |
| **production** | **Dellivery.** Deliver new features to end users. Any bugs found here need to be prioritized. Some will require immediate attention but most can be worked into a future release. | Stable: Prioritize bugs | Public | 8XX | 1.2.3 (10203800) |
## Examples
This repo contains demos of isolated functionality that this SDK provides. They can be found in the examples folder
Examples can be found in the [Demo App](/Example/ZcashLightClientSample)