Managing Projects

After a project has been created it will appear in the Projects list section of the Index window. In this list you can organize your projects by reordering the list and creating project groups. This is all accomplished through drag and drop and through the right-click context menu for the project items. The contextual menu will also permit you to remove projects from the list. Note that Perfect Assistant will not delete any project item files or directories, it will merely remove them from the list and forget that they exist. Removed projects can be re-added to Perfect Assistant through the "Import Existing Package" template or by simply dragging the project directory from the Finder into the Index list area.

Project Editor Window

Most of the day to day project interaction in Perfect Assistant is accomplished through the Project Editor window. The project name, location, dependencies, and deployment options can be modified in this view.

Many changes to the project involve rewriting the project's Package.swift file. In cases where Perfect Assistant cannot reliably rewrite the Package.swift file, such as cases where the file contains new or unhandled options, Perfect Assistant will show a notification that the project is read-only. This means that the project name and dependencies are not editable through Perfect Assistant, however, all of the build and deployment functions will still be available. Projects which contain multiple targets or platform specific #if directives will trigger this read-only state. In these cases, the Project Editor will display the project information read from the package for the macOS platform, but the related information will not be editable within Perfect Assistant.

When modifications are made to a project which require that the Package.swift file be rewritten, Perfect Assistant will make a backup of the file called "Package.swift.orig". It's important to note that Perfect Assistant will only make this backup file if one does not already exist.

Project Editor Layout

The Project Editor consists several sections. Each section lets you inspect or edit the various properties of the project, perform build operations, or configure deployment options.

Toolbar

The project editor window toolbar provides quick access back to the Index as well as access to the various build or deployment commands. These commands are grouped into four different categories. Click and hold on the main buttons to bring up a menu with further options. Alternatively you can choose the standard macOS "Configure Toolbar…" context menu item to drag out and rearrange the individual command buttons however you prefer.

The command groups and individual commands are as follows:

Open
Each of these commands relates to opening some aspect of the project on macOS.
Open Directory	Opens the Finder window for the project directory.
Open Terminal	Opens a new Terminal window with the working directory set to the project directory.
Open Project	Opens the corresponding Xcode project if it exists.
Build
Each of these commands relates to project building, either locally or on Linux.
Build Local	Performs a local macOS debug project build.
Build Linux	Performs a Linux debug project build via Docker.
Build Deployment Image	Performs a Linux release build via Docker, then builds and tags a Docker image containing the produced binaries.
Deploy Project	Performs a Linux release build via Docker, then builds and tags a Docker image containing the produced binaries. This command then goes on to deploy the binaries to each deployment configuration associated with the project.
Clean Project	Simultaneously removes all build artifacts for both macOS and Linux.
Run
Each of these commands relates to project execution, either locally or on Linux.
Run Local Tests	Runs the project's unit tests locally on macOS.
Run Local Exe	Performs a local debug build and opens a terminal window in which the project executable is run.
Run Linux Tests	Runs the project's unit tests on Linux via Docker.
Run Linux Exe	Performs a Linux debug build and opens a terminal window in which the project executable is run via Docker.
Xcode
Each of these commands relates to Xcode project generation through SPM.
Regenerate Project	Regenerates the project's Xcode project file. This regenerated project will not contain Linux integration regardless of the "Integrate Linux Builds with Xcode Project" checkbox.
Integrate Project	Regenerates the project's Xcode project and integrates with the Linux build script. This regenerated project will contain Linux integration regardless of the "Integrate Linux Builds with Xcode Project" checkbox.

Project Settings

Project settings, in this context, consists of the project name, project folder location, Swift toolchain version, and Xcode project integration options.
Editing any of these options will mark the project as modified, but the changes will not be committed until you save the project.

To change the project name, click the "Set" button located to the right of the project name. This will enable the text edit field which will let you enter a new name. Pressing the enter key will provisionally commit the change. The change will not be written to the Package.swift file until you choose to save the edit.

The project location "Locate" button let's you update a project to a new directory. You may want to do this if the project directory was manually moved or renamed. After selecting the new directory location the project editor will reload and update the project information.

The Swift Toolchain popup menu lists all of the toolchains which have been verified as working with Perfect Assistant. Changing this option will adjust which toolchain is used during Perfect Assistant local macOS builds and will also change which Docker image is utilized for Linux builds. When deploying to non-container based systems, such as EC2, it's important to select a toolchain which matches the base Linux version on the destination server.

The "Automatically Integrate Xcode Project" checkbox controls whether Perfect Assistant will add the Linux build script automatically when project dependencies change. If you wish to have your corresponding Xcode project perform automatic on-going Linux builds at the same time that you build your project for macOS, select this option. If this is selected then a custom build script step will automatically be added to Xcode projects whenever Perfect Assistant (re)generates the project files due to dependency changes. Note that enabling this will lengthen your Xcode build times but will provide you with active notifications for any Linux-side build errors or warnings as you develop your project in Xcode. This option is only respected when automatic Xcode project regenerations are performed due to project dependency changes; choosing the "Regenerate Xcode Project" or "Integrate Xcode Project" commands from the project editor will bypass this option letting you perform temporarily integrated or un-integrated project generations.

Project Dependencies

The Project Dependencies section in the project editor shows all of the active dependencies which the project utilizes. Dependencies can be removed by selecting a dependency and pressing the delete key. Any changes to the dependency list must be committed by saving project. Removing dependencies requires rewriting the Package.swift file and so removing dependencies is disabled for read-only projects.

Each dependency item in the list also maintains a version popup. The version popup will list the highest major version, highest major.minor version, as well as the last five point releases for the package.

For example, a package at version 2.5.19 will list "2.x.x", "2.5.x" and then the last five most recent point releases in order. When a new dependency is added the default will be to set it explicitly to the most recent major version with the minor and point versions being set to the most recent implicit version, i.e. 2.x.x. This will provide the most flexibility for a project to utilize the most recent version while not being too picky about minor and point releases. This popup is an NSComboBox, which means that one may manually enter the desired version even if it is not present in the list. It is important to note that Perfect Assistant does not at this time support version ranges in this dependency version selector.

Due to how the Package.swift file is read by Perfect Assistant, this list shows only the dependencies which are active for macOS. In the majority of cases this is the same list as would be used for Linux. In cases where the Package.swift file contains #if directives to alter the dependencies between macOS and Linux, this list may not be congruent. However, the actual dependencies used for macOS and Linux builds will be accurate.

To add a new dependency to your project, drag it from the "Available Dependencies" list (documented below) into this area. A new "unknown" dependency can be added by clicking the "+" icon located to the right of the view's title. This will bring up a sheet which will let you enter the package repository's url and optionally select a category for the package. Adding a new dependency in this manner will add it to your project and will also make it permanently available in the "Available Dependencies" list (documented below).

No dependency changes will be committed to your project until you save your changes. Any attempt to close the window or perform any build operations will prompt you to commit or discard any changes.

Available Dependencies

By default, the Available Dependencies section contains a list of categorized and curated SPM dependencies which are known to work on both macOS and Linux. To add one of these dependencies to your project, drag it from the list into your project's "Project Dependencies" view.

New custom dependencies added through the "Project Dependencies" view will appear in this list given the category which was selected when adding the item.

Each dependency in this collection is grouped by category. For example you may see "Session Management", "Authentication" and "Database Connector" categories. Each of these sections may be expanded to reveal its contents. This view also features a filter search box to let you narrow down your selections. The master list of dependencies is updated from a Github repository when Perfect Assistant is first launched. Once a local dependency is added it is persistent and is available to any project.

Project Deployments

The Perfect Assistant main Index window shows all existing projects and deployment configurations. Individual deployment configurations are shown and editable as separate entities but they can be individually associated with one or more projects. A project editor's "Project Deployments" section in the project editor shows which deployment configurations have been associated with the project. This view permits existing configurations to be associated with the project and new deployment configurations to be created and automatically associated with the project.

The "+" icon located to the right of this view's title will present a menu containing a list of available existing configurations as well as a list of new configurations which may be created.

Selecting an existing deployment configuration from the menu will instantly associate it with the project. Selecting to create a new deployment configuration will open a new deployment configuration editor within which the new deployment can be constructed (deployment configuration options for each supported platform are documented separately).

To delete a configuration, select it and press the delete key. Once a deployment configuration is added or deleted from the project the project must be saved to retain the changes.

When deploying a project, all associated deployment configurations are executed. A project can be associated with multiple configurations even if they are from disparate services. For example, a project may be simultaneously deployed to one or more EC2 configurations and one or more Google App Engine configurations once those configurations as associated with the project.

Task Status

The final section of the Project Editor is the tasks view. This view will alter based on any ongoing or previously executed tasks. If no project related tasks have been executed then this view will remain minimized at the bottom of the window. Once a build, deployment or project generation task begins to execute, this view will expand itself and show the output.

The main content of this view is a text area which shows the console output from whichever task is currently executing. Controls on the upper right side permit scrolling to the top or bottom of the output as well as canceling any current task or clearing text from any successful or erred task. A popup menu on the left side will permit the selection of any ongoing or previously executed task.