This article is an extension of the AdAT project and a foundation for subsequent Xcode building exercises. The purpose of this article is to give the readers of this series a common understanding of the concepts when they read a chapter. If you feel a little vague about the basic consensus, please read it carefully. If you already have it, take a second look at it and you may be pleasantly surprised.


An overview of the content

  • Command line usage documentation
  • Command execution manual
  • How to write a command using documentation
  • What exactly are Target, Configuration, and Scheme?
  • What is a Project or Workspace?
  • Xcodebuild base command
  • Good forecast


Command line usage documentation

The word “Usage” here comes from the English word “Usage”, which is a short form of Usage. Getting a “usage document” for a command depends on the command itself, so there is no set way to write it. Experience tells us that there are several common ways to write it (note the space after the < command >) :

  • < command > -h
  • < command > help
  • < command > –help
  • < command > -usage

If the command fails, the correct usage is displayed along with the error information. If no error occurs, the command uses default parameters or no parameters are required. You can read the user manual to obtain the default parameters. If you still can’t find it, finally seek help from the official website.

For an example, look at the git command usage documentation:

$ git --help
Copy the code

After the command is executed, the brief usage is displayed on the current screen:

$ git --help usage: git [--version] [--help] [-C <path>] [-c <name>=<value>] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]  [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare] [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] <command> [<args>] ... See 'git help git' for an overview of the system.Copy the code

Usage documentation is useful for quickly viewing command usage. For example, if you suddenly forget some options in your work, or if some options are combination words that are too long, you are not sure whether the input is correct, you can take a quick look and continue working.


Command execution manual

The “user Manual” is taken from the English “Manual”, which is a more detailed form of documentation. MacOS uses BSD General Commands Manual, which contains common sections such as NAME, SYNOPSIS, DESCRIPTION, EXAMPLES, SEE ALSO, etc.

Period of meaning describe
NAME The name One sentence describes the name of the command
SYNOPSIS The profile This section lists the command lines corresponding to common functions in the command line syntax format
DESCRIPTION describe Command description lists the name, abbreviation, meaning, combination usage, and precautions of each parameter, including option, flag, and value
EXAMPLES The sample An example of a concrete way to implement a feature
SEE ALSO see Associated with other commands

Usage:

Man < command >Copy the code

For example, view the manual of the echo command:

$ man echo
Copy the code

After the command is executed, it will automatically switch to vim command mode and output document details:

ECHO(1) BSD General Commands Manual ECHO(1) NAME echo -- write arguments to the standard output SYNOPSIS echo [-n] [string ...]  DESCRIPTION The echo utility writes any specified operands, separated by single blank (` ') characters and followed by a newline (`\n') character, to the standard output. The following option is available: -n Do not print the trailing newline character. This may also be achieved by appending `\c' to the end of the string, as is done by iBCS2 compatible systems. ... SEE ALSO builtin(1), csh(1), printf(1), sh(1) ... BSD April 12, 2003 BSD (END)Copy the code

Enter q in the command mode to exit the command mode and exit the user manual. Notice The letter Q exits immediately after it is entered successfully.

Git –help: git –help: git –help: git –help: git –help: git –help

The manual is suitable for the stage of learning or researching a command. Because it is very detailed, often several pages, such as man Git, man XcodeBuild, is not convenient to quickly view, but is very helpful for in-depth research, especially the DESCRIPTION, EXAMPLES section.


How to write a command using documentation

The first step is to understand the content of the document, but many symbols in the document become dyslexia, which needs to be solved first.


Command line symbol

A command is also a program that must be able to recognize parameters and adjust functionality based on them. The command line documentation identifies parameters, describes and qualifies the use of the command line using the conventions of notation and order. Here are some common symbols:

symbol meaning describe
[] optional An option, tag, or parameter may not be specified. Multiple options can be used in combination to achieve completely different functions
| The mutex Use | link multiple options, can only choose one to use
. repeat Options, tags, parameters, or a combination of them can appear multiple times on the command line
< > Will choose You must specify that the < > and internal text as a whole are replaced with concrete values when used
unsigned Do not modify the How is it written in the document, as is





Example command line symbol usage

Execute in Terminal:

$ xcodebuild -help
Copy the code

Extract a line from the output:

xcodebuild -list [[-project <projectname>]|[-workspace <workspacename>]] [-json]
Copy the code

According to this description, combined with the meaning of the symbol, we know:

  • xcodebuildIs the order,-listAre options, which are undecorated and therefore must appear on the command line.
  • -project <projectname>and-workspace <workspacename>In order to|Connection, which is mutually exclusive, can only be one of two. The two were respectively[]Package means optional, so you can leave it all out. Both are separated by a large[]Package, which means the whole thing can be completely ignored.<projectname>and<workspacename>were< >Package: must be specified. The whole meaning is: either specify-project, followed by the project path, or specified-workspace, followed by the workspace path, or ignore it altogether.
  • -jsonIs an optional function switch specified on the command line-jsonThe output is in JSON format. If this parameter is not specified, the output is as is.

The number of ways to write the above three are: 1,3,2, and there are a total of 6 ways to write them (the order adjustment is not counted in the number of ways to write them). Here are a few possible ways to write it:

  • xcodebuild -list
  • xcodebuild -list -project /Users/username/Networking.xcodeproj
  • xcodebuild -list -workspace /Users/username/A.xcworkspace -json

At this point, we have a basic understanding of the command line. Memorize symbols, practice them, and you’ll be less afraid of unfamiliar commands. There are also some unlisted command-line symbols that you can explore if you are interested, such as {}, ().

If you like to search the web for a command line for a particular function, then copy, paste, run, success, never mind. Now is the time to think about why it was written that way, whether there are pitfalls, and whether there is room for improvement.


What exactly are Target, Configuration, and Scheme?

Target, Configuration, and Scheme determine the final product, which is described below.


Target

Using Xcode 13.1 as an example, creating an App project automatically creates one Target, and if Include Tests is checked, two more targets are automatically created: unit test targets and UI test targets. In addition, Xcode -> File -> New -> Target can create Target manually. In fact, the Target describes the shape of the end product, be it App, Framework, Bundle, or Extension, So Target’s end product could be xxx.app, XXx. framework, xxx.bundle, and xxx.appex.

Xcode -> Targets list (Target), you will find that each Target has its own Build Settings, Build Phases, and Build Rules. Other targets (except configuration items affected by association) are not affected. For example, we are very familiar with Build SettingsOther Linker FlagsBuild the PhasesRun Script. In fact, Target does define Build Settings, Build Phases, and Build Rules, and just like its own properties, modifying them will affect Target’s end product. For example, modify the Build Settings of a Framework TargetMach-O TypeCan determine whether a static or dynamic library is generated.

FBSDKCoreKit a large Project often has multiple targets, from Github clone facebook-ios-SDK Project, check out the tag v12.0.2, you can see FBSDKCoreKit Project, there are 7 targets:

To check the product, we can compile the whole project by ourselves, or download the product compiled by the official from the Release section of the Facebook-ios-SDK project:As you can see, a single file does contain the artifacts of multiple platforms and architectures.

Ignoring the wrap of the XCFramework for now, it’s just a form of distribution, and virtually every artifact inside is contributed by each Target. Prior to Facebook SDK v12.0.0, FBSDKCoreKit was the FAT Framework for platform differentiation.

A follow-up article will cover the FAT Framework and how to generate the XCFramework.


Configuration

Configuration is a variant of Target’s Build Settings in Xcode. Each variant has its own Configuration. These configurations affect the end product. Create a new App project and by default create two variants: Debug and Release.

Variants can be modified independently. For example, a Debug symbol file is generated in the Release variant to analyze crashes reported in production, while this configuration is disabled in the Debug variant to reduce build time during development:

Manage variants in Xcode -> Project: Change variants name, add variants, set command line build defaults, set variants profile:

Variant profiles can override the Build Settings configuration in Xcode, facilitating unified environment configuration and version management, and providing good support for team collaboration on large projects. The variant configuration file suffix is. Xcconfig and the file content format is: Key=Value. Key comes from Build Settings and Value can inherit the default Value or be overridden. Other variant profiles can also be referenced within the file.

For example, here is the contents of fbsdkCoreKit-dynamic.xcconfig:

. #include "Shared/Platform/iOS.xcconfig" #include "Shared/Target/DynamicFramework.xcconfig" #include "Shared/Version.xcconfig" PRODUCT_NAME = FBSDKCoreKit PRODUCT_BUNDLE_IDENTIFIER = com.facebook.sdk.FBSDKCoreKit CURRENT_PROJECT_VERSION = $(FBSDK_PROJECT_VERSION) INFOPLIST_FILE = $(SRCROOT)/FBSDKCoreKit/Info.plist MODULEMAP_FILE = $(SRCROOT)/FBSDKCoreKit/FBSDKCoreKit.modulemapCopy the code


Scheme

Target and Configuration only define products, but do not generate products. Scheme only drives the generation of products. Scheme binds Target with a series of operations and a Configuration for each operation:

When Xcode -> Product executes the Build, Run, Test, Profile, Analyze, and Archive operations, the corresponding operations in the current Scheme are actually performed. When different operations are performed, the same Target and Configuration produce different products. For example, the result of Run is Run on the device, and the result of Archive is Archive.

Scheme is a list of operations, each of which corresponds to a build path:

Scheme Action Target Configuration Product
App Build App Debug App.app
Run App Debug Run to device
Test AppTests, AppUITests Debug Run the test case
Profile App Release A dynamic analysis
Analyze App Debug Static analysis
Archive App Release App.xcarchive





What is a Project or Workspace?

Project and Workspace are two ways of organizing Xcode projects, described below.


Project

A Project is a direct container that directly manages all the code files, resources, scripts, dependency libraries, as well as Target, Configuration, and Scheme in the Project. The entry file suffix for projects organized as Project is.xcodeproj.

A Project can reference other projects as its dependencies, in the same way as a Workspace does.


Workspace

Workspace is an indirect container that makes sense only after it references Project. Of course, you can also create code files, add resources, and so on within the Workspace, but if these files are not used by any Project, they are just a bunch of normal files and do nothing. The entry file suffix for projects organized as Workspace is.xcworkspace.

For example, Workspace A references App (an App Project) and Networking (A Framework Project). Locate the.xcworkspace file for the Project and right-click to display the package contents. Look at the contents of the contents.xcworkspaceData file:

<? The XML version = "1.0" encoding = "utf-8"? > < Workspace version = "1.0" > < FileRef location = "group: Networking/Networking. Xcodeproj" > < / FileRef > < FileRef location = "group:App/App.xcodeproj"> </FileRef> </Workspace>Copy the code

As you can see, Workspace organizes multiple projects together and does nothing special.

Organizing projects through a Workspace makes it very easy to establish dependencies between projects. For example, App Project relies on the product of Framework Project, Networking. Framework. And add the product, Networking. Framework, in the same way as adding system libraries:

Xcode -> File -> Workspace Settings:

In a build system, workspace must be used with Scheme.

The concepts of Target, Configuration, Scheme, Project and Workspace are very important in modularization. The implementation of iOS modularization will be introduced in the following articles.

Point attention, first time access: Virusbee – author of this article


Xcodebuild base command

Before executing the xcodebuild command, switch to the directory containing the.xcodeproj or.xcworkspace file, or specify -project or -workspace in the command. If there are multiple. Xcodeproj files in the directory, the first one is used by default.


Viewing SDK Information
xcodebuild -version -sdk
Copy the code

Example:

$xcodebuild-version-sdk iPhoneOS15.0. Sdk-ios 15.0 (iPhoneOS15.0) SDKVersion: 15.0 Path: / Applications/Xcode. App/Contents/Developer/Platforms/iPhoneOS platform/Developer/SDKs/iPhoneOS15.0 SDK PlatformVersion: PlatformPath: 15.0 / Applications/Xcode. App/Contents/Developer/Platforms/iPhoneOS platform BuildID: 84856584-0587-11EC-B99C-6807972BB3D4 ProductBuildVersion: 19A339 ProductCopyright: 1983-2021 Apple Inc. ProductName: IPhone OS ProductVersion: 15.0... Xcode 13.0 Build version 13A233Copy the code

Output Xcode version and all SDK information: iOS, iOS Simulator, DriverKit, macOS, tvOS, TV Simulator, watchOS, Watch Simulator. If -json is appended to the command, the information will be output in JSON format.

This command does not specify Project or Workspace because it gets information about the build system, not the Project.


View Project information
xcodebuild -list -project App/App.xcodeproj
Copy the code

Example, output App Project information in JSON format:

$ xcodebuild -list -project App/App.xcodeproj -json
{
  "project" : {
    "configurations" : [
      "Debug",
      "Release"
    ],
    "name" : "App",
    "schemes" : [
      "App"
    ],
    "targets" : [
      "App"
    ]
  }
}
Copy the code

It outputs the Target, Configuration and Scheme of App Project, which is very important and has been analyzed above.


View Build Settings information
xcodebuild -project App/App.xcodeproj -showBuildSettings -destination "generic/platform=iOS"
Copy the code

Example:

$ xcodebuild -project App/App.xcodeproj -showBuildSettings -destination "generic/platform=iOS" Command line invocation: /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild -project App/App.xcodeproj -showBuildSettings -destination  generic/platform=iOS User defaults from command line: IDEPackageSupportUseBuiltinSCM = YES Build settings for action build and target App: ACTION = build ... ARCHS = arm64 ... BUILD_DIR = /Users/username/Library/Developer/Xcode/DerivedData/App-ejgzkwsxgbtdqdefiyltxpffjdbg/Build/Products ... CODE_SIGN_STYLE = Automatic ...Copy the code

Outputs Build Settings information for executing Build operations on Project from the command line.


Clean the App Project
xcodebuild -project App.xcodeproj -scheme App -destination "generic/platform=iOS" clean
Copy the code

For a detailed explanation of destinations, see the first article of the ADAT project: TN2339: Common Problems with Building with the Xcode command line

Output:

$ xcodebuild -project App/App.xcodeproj -scheme App -destination "generic/platform=iOS" clean
Command line invocation:
    /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild -project App/App.xcodeproj -scheme App -destination generic/platform=iOS clean

User defaults from command line:
    IDEPackageSupportUseBuiltinSCM = YES

note: Using new build system
note: Build preparation complete

** CLEAN SUCCEEDED **
Copy the code

The command executed flawlessly, without warning, and the Build directory was removed.

The Clean operation can specify -destination iOS or iOS Simulator, either of which can delete the Build directory. -destination “generic/platform=iOS Simulator”


Good forecast

There are many concepts in this article. If you haven’t thoroughly understood them before, you may need some time to digest them. However, it does not matter, the follow-up article is also closely linked, I believe that in continuous reading and practice, you will be able to understand thoroughly.

Here are the plans for subsequent articles (titles and order may change, depending on the actual release) :

  • Explore Xcode command line usage two: Unit testing and UI testing
  • Explore Xcode command line usage three: XcodeBuild package
  • Explore Xcode command line usage 4: CoDesign signatures
  • Explore Xcode command line usage 5: upload and distribute
  • Explore Xcode command line usage 6: Jenkins keeps building

Follow me, wonderful miss: Virusbee – author of this article