From fc46247836be0303bf714ad3736b2f21956bcdb9 Mon Sep 17 00:00:00 2001 From: Logan Wright Date: Tue, 2 Aug 2016 13:16:24 -0400 Subject: [PATCH 1/4] adding xcode page --- couscous.yml | 6 ++++++ getting-started/xcode.md | 45 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) create mode 100644 getting-started/xcode.md diff --git a/couscous.yml b/couscous.yml index c840f026..b03a1647 100644 --- a/couscous.yml +++ b/couscous.yml @@ -20,12 +20,18 @@ menu: getting-started-install-swift-3: text: Install Swift 3 relativeUrl: getting-started/install-swift-3.html + getting-started-quickstart: + text: Manual QuickStart + relativeUrl: getting-started/quickstart.html getting-started-install-toolbox: text: Install Toolbox relativeUrl: getting-started/install-toolbox.html getting-started-hello-world: text: Hello, World relativeUrl: getting-started/hello-world.html + getting-started-xcode: + text: Xcode + relativeUrl: getting-started/xcode.html guide: name: Guide items: diff --git a/getting-started/xcode.md b/getting-started/xcode.md new file mode 100644 index 00000000..2fae9596 --- /dev/null +++ b/getting-started/xcode.md @@ -0,0 +1,45 @@ +--- +currentMenu: getting-started-xcode +--- + +# Xcode + +The first thing you'll probably notice about Vapor and SwiftPM projects in general is that we don't include an Xcode project. In fact, when SwiftPM generates packages, the `.xcodeproj` file is gitignored by default. + +This means we don't have to worry about pbxproj conflicts, and it's easy for different platforms to utilize their own editors. + +# Generate Project + +### Vapor Toolbox + +To generate a new Xcode project for a project, use: + +```bash +vapor xcode +``` + +> If you'd like to automatically open the Xcode project, use `vapor xcode -y` + +### Manual + +To generate a new Xcode project manually. + +```bash +swift package generate-xcodeproj +``` + +Open the project and continue normally. + +## Flags + +For many packages with underlying c-dependencies, users will need to pass linker flags during **build** AND **project generation**. Make sure to consult the guides associated with those dependencies. For example: + +``` +vapor xcode --mysql +``` + +or + +``` +swift package generate-xcodeproj -Xswiftc -I/usr/local/include/mysql -Xlinker -L/usr/local/lib +``` From f625854b568ce1fe4e50e2574952287a137cab36 Mon Sep 17 00:00:00 2001 From: Logan Wright Date: Tue, 2 Aug 2016 15:56:31 -0400 Subject: [PATCH 2/4] tweak title --- getting-started/xcode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/xcode.md b/getting-started/xcode.md index 2fae9596..3a54d4fa 100644 --- a/getting-started/xcode.md +++ b/getting-started/xcode.md @@ -8,7 +8,7 @@ The first thing you'll probably notice about Vapor and SwiftPM projects in gener This means we don't have to worry about pbxproj conflicts, and it's easy for different platforms to utilize their own editors. -# Generate Project +## Generate Project ### Vapor Toolbox From 46c21327e2dc0fc56415f46152e1a576d90f83e4 Mon Sep 17 00:00:00 2001 From: Logan Wright Date: Tue, 2 Aug 2016 15:29:06 -0400 Subject: [PATCH 3/4] config docs --- couscous.yml | 3 + guide/config.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 188 insertions(+) create mode 100644 guide/config.md diff --git a/couscous.yml b/couscous.yml index b03a1647..e8c82b7f 100644 --- a/couscous.yml +++ b/couscous.yml @@ -44,3 +44,6 @@ menu: guide-routing: text: Routing relativeUrl: guide/routing.html + guide-config: + text: Config + relativeUrl: guide/config.html diff --git a/guide/config.md b/guide/config.md new file mode 100644 index 00000000..236c55cf --- /dev/null +++ b/guide/config.md @@ -0,0 +1,185 @@ +--- +currentMenu: guide-config +--- + +# Config + +An application's configuration settings. Cloud applications generally require complex configurations that can adjust based on their environment. Vapor intends to provide a flexible configuration interaction that can be customized for a given user. + +## QuickStart + +For Vapor applications, configuration files are expected to be nested under a top level folder named `Config`. Here's an example of a basic config featuring a single `servers` configuration. + +```bash +./ +├── Config/ +│ ├── server.json +``` + +And an example of how this might look: + +```JSON +{ + "http": { + "host": "0.0.0.0", + "port": 8080 + } +} +``` + +What that's saying, is that our application should start a single server named 'default' serving port `8080` on host `0.0.0.0`. This represents the following url: `http://localhost:8080`. + +### Custom Keys + +Let's add a custom key to the `servers.json` file: + +```JSON +{ + "http": { + "host": "0.0.0.0", + "port": 8080, + "custom-key": "custom value" + } +} +``` + +This can be accessed from your application's config using the following. + +```Swift +let customValue = app.config["server", "http", "custom-key"].string +``` + +That's it, feel free to add and utilize keys as necessary to make your application configuration easier. + +## Config Syntax + +You can access your config directory with the following syntax. `app.config[<#file-name#>, <#path#>, <#to#>, <#file#>]`. For example, let's hypothesize that in addition to the `servers.json` file we mentioned earlier, there is also a `keys.json` that looks like this: + +```JSON +{ + "test-names": [ + "joe", + "jane", + "sara" + ], + "mongo": { + "url" : "www.customMongoUrl.com" + } +} +``` + +We can access this file by making sure the first argument in our subscript is keys. To get the first name in our list: + +```Swift +let name = app.config["keys", "test-names", 0].string +``` + +Or our mongo url: + +```Swift +let mongoUrl = app.config["keys", "mongo", "url"].string +``` + +## Advanced Configurations + +Having the default servers.json is great, but what about more complex scenarios. For example, what if we want a different host in production and in development? These complex scenarios can be achieved by adding additional folder structure to our Config/ directory. Here's an example of a folder structure that's setup for production and development environments. + +```bash +WorkingDirectory/ +├── Config/ +│ ├── servers.json +│ ├── production/ +│ │ └── servers.json +│ ├── development/ +│ │ └── servers.json +│ └── secrets/ +│ └── servers.json +``` + +> You can specify the environment through the command line by using --env=. Custom environments are also available, a few are provided by default: production, development, and testing. + +```bash +vapor run --env=production +``` + +### PRIORITY + +Config files will be accessed in the following priority. + +1. CLI (see below) +2. Config/secrets/ +3. Config/name-of-environment/ +4. Config/ + +What this means is that if a user calls `app.config["servers", "host"]`, the key will be searched in the cli first, then the secrets directory, then the top level default configs. + +> `secrets/` directory should very likely be added to the gitignore. + +### EXAMPLE + +Let's start with the following JSON files. + +#### servers.json + +```JSON +{ + "http": { + "host": "0.0.0.0", + "port": 9000 + } +} +``` + +#### `production/servers.json` + +```JSON +{ + "http": { + "host": "127.0.0.1", + "port": "$PORT" + } +} +``` + +> The `"$NAME"` syntax is available for all values to access environment variables. + +Please notice that servers.json, and production/servers.json both declare the same keys. host, and port. In our application, we'll call: + +```Swift +// will load 0.0.0.0 or 127.0.0.1 based on above config +let host = app.config["servers", "http", "host"].string +// will load 9000, or environment variable port. +let port = app.config["servers", "http", "port"].int +``` + +## COMMAND LINE + +In addition to json files nested within the Config/ directory, we can also use the command line to pass arguments into our config. By default, these values will be set as the "cli" file, but more complex options are also available. + +#### 1. `--KEY=VALUE` + +Arguments set through the command line can be accessed through config's cli file. For example, the following CLI command: + +```bash +--mongo-password=$MONGO_PASSWORD +``` + +would be accessible within your application by using the following: + +```Swift +let mongoPassword = app.config["cli", "mongo-password"].string +``` + +#### 2. --CONFIG:FILE-NAME.KEY=CUSTOM-VALUE + +If you want command line arguments set to a file besides "cli", you can use this more advanced specification. For example, the following CLI command: + +```bash +--config:keys.analytics=124ZH61F +``` + +would be accessible within your application by using the following: + +```Swift +let analyticsKey = app.config["keys", "analytics"].string +``` From 5042ddc03f8a0b8be4a73c9f0ed8dcdf6b1478f8 Mon Sep 17 00:00:00 2001 From: Logan Wright Date: Tue, 2 Aug 2016 15:58:09 -0400 Subject: [PATCH 4/4] tweak swift code formatting --- getting-started/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/quickstart.md b/getting-started/quickstart.md index 0c20ae7d..3dd9aeb1 100644 --- a/getting-started/quickstart.md +++ b/getting-started/quickstart.md @@ -48,7 +48,7 @@ And add Vapor as a dependency. Here's how your file will look. #### Package.swift -```Swift +```swift import PackageDescription let package = Package(