From 40dec957a63fed1edc2d7cf59229e8d60f357b12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20Pi=C3=B1era=20Buend=C3=ADa?= Date: Sat, 21 Jul 2018 18:54:29 -0400 Subject: [PATCH] Move documentation to this repository (#70) --- docs/README.md | 12 +++++++ docs/advanced/modules.md | 1 + docs/basic/buildtest.md | 1 + docs/basic/ci.md | 1 + docs/basic/dependencies.md | 1 + docs/basic/examples.md | 1 + docs/basic/init.md | 73 ++++++++++++++++++++++++++++++++++++++ docs/basic/install.md | 23 ++++++++++++ 8 files changed, 113 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/advanced/modules.md create mode 100644 docs/basic/buildtest.md create mode 100644 docs/basic/ci.md create mode 100644 docs/basic/dependencies.md create mode 100644 docs/basic/examples.md create mode 100644 docs/basic/init.md create mode 100644 docs/basic/install.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..0811b3020 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,12 @@ +# Documentation + +The documentation is still WIP ⚠️. Some of the content might be outdated. + +## Basic + +- [Install](basic/install) +- [Initialize your project](basic/init) +- [Target dependencies](basic/dependencies) +- [Building and testing](basic/buildtest) +- [Continuous integration](basic/ci) +- [Examples](basic/examples) diff --git a/docs/advanced/modules.md b/docs/advanced/modules.md new file mode 100644 index 000000000..016d43441 --- /dev/null +++ b/docs/advanced/modules.md @@ -0,0 +1 @@ +# Modules \ No newline at end of file diff --git a/docs/basic/buildtest.md b/docs/basic/buildtest.md new file mode 100644 index 000000000..45d6f18a7 --- /dev/null +++ b/docs/basic/buildtest.md @@ -0,0 +1 @@ +# Building and testing \ No newline at end of file diff --git a/docs/basic/ci.md b/docs/basic/ci.md new file mode 100644 index 000000000..297668f0b --- /dev/null +++ b/docs/basic/ci.md @@ -0,0 +1 @@ +# Continuous Integration \ No newline at end of file diff --git a/docs/basic/dependencies.md b/docs/basic/dependencies.md new file mode 100644 index 000000000..8a7eabf63 --- /dev/null +++ b/docs/basic/dependencies.md @@ -0,0 +1 @@ +# Target dependencies \ No newline at end of file diff --git a/docs/basic/examples.md b/docs/basic/examples.md new file mode 100644 index 000000000..1b976a9b7 --- /dev/null +++ b/docs/basic/examples.md @@ -0,0 +1 @@ +# Examples \ No newline at end of file diff --git a/docs/basic/init.md b/docs/basic/init.md new file mode 100644 index 000000000..bbb1b61cc --- /dev/null +++ b/docs/basic/init.md @@ -0,0 +1,73 @@ +# Initialize your project + +After installing *xpm* the first step is creating a project. *xpm* comes with a very useful `init` command that helps you bootstrap a new project: + +```bash +xpm init +``` + +You can specify the platform and the type of project you'd like to create. + +The command generates a `Project.swift` and some files that are required for your project to compile, like an `Info.plist` file. The `Project.swift` file, also known as "manifest", is the file where you define the structure of your project. If you have used the Swift Package Manager before, it's the equivalent to the Swift Package Manager, but it contains the definition of a project instead: + +```swift +import ProjectDescription + +let project = Project(name: "MyProject", + schemes: [ + /* Project schemes are defined here */ + Scheme(name: "documentation", + shared: true, + buildAction: BuildAction(targets: ["documentation"])), + ], + settings: Settings(base: [:]), + targets: [ + Target(name: "MyProject", + platform: .iOS, + product: .app, + bundleId: "com.xcodepm.MyProject", + infoPlist: "Info.plist", + dependencies: [ + /* Target dependencies can be defined here */ + /* .framework(path: "framework") */ + ], + settings: nil, + buildPhases: [ + + .sources([.sources("./Sources/*")]), + /* Other build phases can be added here */ + /* .resources([.include(["./Resources/**/*"])]) */ + ]), + ]) +``` + +The `Project` model has a structure similar to the Xcode's. Let's analyze each of the properties: +- **Schemes:** It contains your project schemes. Each scheme has a name, whether it's shared, and some actions. +- **Settings:** It defines the project settings. The `Settings` model supports passing the settings as a dictionary and also as references to `.xcconfig` files. +- **Targets:** They represent the targets of your project. + +### Target +A Target represents a Xcode project target so its attributes are also similar: + +- **Name:** The target name. +- **Platform:** The platform your target product is for. *xpm* automatically configures the target build settings with the right SDK root path, and supported platform. +- **Bundle Identifier:** The target bundle identifier. +- **Info Plist:** A reference to the target info.plist. All references to files in your project definition need to be relative. We discourage using absolute paths. +- **Build phases:** Contain the build target build phases. You'll find the same types of build phases with exception of the frameworks linking. We'll talk more about why, and how *xpm* in the [dependencies section](/basic/dependencies). + +### Generating the Xcode project + +The next step after initializing the project manfiest is generating the Xcode project to start working on our app. Run the following command in your terminal: + +``` +xpm generate +``` + +It'll generate a Xcode workspace and project in the same directory. The name of the project and workspace matches the name specified in the `Project.swift`. If your project doesn't have dependencies you can open the Xcode project. However, most of the times you'll have dependencies defined with projects in other folders. In those cases you should use the workspace instead, because it includes the other projects your project depends on. + +If you open the workspace, there should be two targets: + +- The target that was defined in the `Project.swift`. +- A target named `MyProjectDescription`. + +The latter, is a target that includes the `Project.swift`. Here's one of the great things of using Swift as the language for defining Xcode projects, you can safely define your projects using Xcode. If you make a typo or you don't know the project structure Xcode will complain and tell you how to fix it. diff --git a/docs/basic/install.md b/docs/basic/install.md new file mode 100644 index 000000000..30ac6d2e8 --- /dev/null +++ b/docs/basic/install.md @@ -0,0 +1,23 @@ +# Install + +First of all you need to install *xpm* in your computer. We made the the process very easy for you. Open a terminal, and execute the following command: + +```bash +/usr/bin/ruby -e "$(curl -fsSL https://goo.gl/4cbZoL)" +``` + +It'll pull the latest version of *xpm*, install it, and add an alias to your shell path. Once the process is completed, you should be able to run `xpm` in your terminal. It'll print the list of commands that are available. + + +> If you are curious about how the install process works, you can check out this [Ruby script](https://github.com/xcode-project-manager/xpm/blob/master/scripts/install) that gets executed when you run the command above. + + +### Updating xpm + +Since we are continuously adding improvements and new features to *xpm* it's important that you can update the app easily as well. *xpm* comes with an `update` command that you can call at any time. It'll check if there's any update for the tool, and if there is, it'll update verything for you: + +```bash +xpm update +``` + +> The auto-update process is provided by the awesome framework [Sparkle](https://sparkle-project.org/) which is extensively used in many macOS applications. \ No newline at end of file