Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/e-sites/natrium
A pre-build (Swift) script to alter your Xcode project at pre-build-time per environment, build configuration and target.
https://github.com/e-sites/natrium
carthage cli cli-app cocoapods environment environment-variables ios ribbon scheme swift swift-package-manager swift5 swiftpm xcode xcodegen xcodeproj yml
Last synced: 3 days ago
JSON representation
A pre-build (Swift) script to alter your Xcode project at pre-build-time per environment, build configuration and target.
- Host: GitHub
- URL: https://github.com/e-sites/natrium
- Owner: e-sites
- License: mit
- Created: 2016-05-11T13:13:04.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-04-04T12:37:14.000Z (6 months ago)
- Last Synced: 2024-04-14T06:15:23.511Z (6 months ago)
- Topics: carthage, cli, cli-app, cocoapods, environment, environment-variables, ios, ribbon, scheme, swift, swift-package-manager, swift5, swiftpm, xcode, xcodegen, xcodeproj, yml
- Language: Swift
- Homepage: https://www.e-sites.nl
- Size: 371 MB
- Stars: 144
- Watchers: 8
- Forks: 15
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Natrium is part of the **[E-sites iOS Suite](https://github.com/e-sites/iOS-Suite)**.
---
A pre-build (Swift) script to alter your Xcode project at build-time per environment and build configuration.
[](http://forthebadge.com) [](http://forthebadge.com)
[](https://cocoapods.org/pods/Natrium)
[](https://cocoapods.org/pods/Natrium)
[](https://github.com/Carthage/Carthage)
[](https://travis-ci.com/e-sites/Natrium)
# TL;DR
With Natrium you can change this:
```swift
#if ENVIRONMENT_STAGING
let apiHost = "mynice.staging-api.com"
#elseif ENVIRONMENT_DEVELOPMENT
let apiHost = "mynice.dev-api.com"
#else
let apiHost = "mynice.api.com"
#endif
Alamofire.request("https://\(apiHost)/items").responseJSON { response in
// ...
}
```
Into this:
```swift
let apiHost = Natrium.Config.apiHost
Alamofire.request("https://\(apiHost)/items").responseJSON { response in
// ...
}
```
### 🧙♂️ With the magic of pre-action run scripts. 😱
```shell
"${PROJECT_DIR}/Pods/Natrium/Natrium/natrium" Production
```
# Migration
### To v8.x
- The location of the binary is changed from (for instance in Cocoapods) `Pods/Natrium/bin/natrium` to `Pods/Natrium/Natrium/natrium`
- The location of the generated **Natrium.swift** is changed to (for instance in Cocoapods): `Pods/Natrium/Natrium/Natrium.swift`
### To v7.x
- `natrium install` is removed
- Both `.natrium-env` and `.env` files can be used for environment variables
- CLI no longer needs `--project` argument
- No longer supports Objective-c, use v6.4.0 if you still need it.
### To v6.x
For Natrium v6.x you need to manually import the `Natrium.swift` file to your project to make it work in the new xcode build system. Read the [Installation](#installation) guide.
### From v5.x
Natrium v5.x doesn't need a build phase script anymore.
Open your `Build Phases` from your target settings and remove the `[Natrium] check` step.
Else your build will fail during the script steps
# Roadmap
- [x] Swift 4.2 compatible
- [x] Use swift instead of ruby
- [x] Remove ImageMagick dependency
- [x] Unit tests
- [x] Different installation options (apart from CocoaPods)
- [x] Better error handling / reporting
# Installation
- Swift Package Manager → [Read the instructions here](docs/INSTALL_SWIFTPM.md).
- CocoaPods → [Read the instructions here](docs/INSTALL_COCOAPODS.md).
- Carthage → [Read the instructions here](docs/INSTALL_CARTHAGE.md).
- Manually → [Read the instructions here](docs/INSTALL_MANUALLY.md).
- [XcodeGen](https://github.com/yonaskolb/XcodeGen) → [Read the instructions here](docs/INSTALL_XCODEGEN.md).
# Implementation
## Swift
Just add `Natrium.swift` (from the designated location, see installation guide) to your project's target (do not copy).
# Configuration
Configuration documentation can be found [here](docs/CONFIGURATION.md).
# Usage
The example `.natrium.yml` as shown above, will result in the following Config.swift file:
```swift
import Foundation
/// Natrium.swift
/// Autogenerated by natrium
///
/// - see: https://github.com/e-sites/Natrium
enum Natrium {
enum Environment: String {
case staging = "Staging"
case production = "Production"
}
enum Configuration: String {
case debug = "Debug"
case release = "Release"
case adhoc = "Adhoc"
}
enum Config {
static let environment: Natrium.Environment = .staging
static let configuration: Natrium.Configuration = .debug
static let testVariableDouble: Double = 1.0
static let testVariableString: String = "debugString"
static let testVariableBoolean: Bool = false
static let testVariableInteger: Int = 125
static let testArray: [String] = [ "StagingFoo", "StagingBar" ]
}
}
```
It can be used like so:
```swift
class MainViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
print("bundle identifier: \(Bundle.main.bundleIdentifier!)")
print("environment: \(Natrium.Config.environment)")
}
}
```
**Result:**
```
bundle identifier: com.esites.app.staging
environment: Staging
```
# Development
Run
```
make xcodeproj
```
and open `Natrium.xcodeproj`
# Advanced
## Logging
In the `Pods/Natrium/bin/` folder you can find `natrium.log` with the logs of the previous build. It might help you with debugging.
## Environment variables
If you place `.env` in the root of your project. Natrium will use that fill to add environment variables to your already existing environment variables.
The `.env` file should have to following format:
```
KEY=VALUE
```
for instance:
```
PRODUCTION_SECRET_API_TOKEN=3489uierhjkfbnvcx
STAGING_SECRET_API_TOKEN=iujk9qijs41
```
This way you can use `#env(PRODUCTION_SECRET_API_TOKEN)` in your `.natrium.yml` file.
For CI/CD pipelines you can simply add those environment variables to your build pipeline (in travis or buddybuild for instance).
But if you want to use it for local (debug) builds, this file can be helpful.
⚠️ Don't forget to add `.env` to your `.gitignore`