andreas/mac_os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated documentation to ASCII Doc format

Browse Source 
Provides enhanced capabilities and customization beyond what Markdown
provides.
This commit is contained in:
Brooke Kuhlmann
2020-03-21 10:26:22 -06:00
parent 9a37f06826
commit 97893843de
8 changed files with 469 additions and 477 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
CHANGES.adoc Normal file
View File

@@ -0,0 +1,161 @@
= Changes
== 8.0.1 (2020-01-01)
* Added Startup Security Utility to README.
* Updated README screencast.
* Updated to Ruby 2.7.0.
* Refactored caffeinate machine function to process grep.
== 8.0.0 (2019-10-12)
* Updated to Rake 13.0.0.
* Updated to Ruby 2.6.5.
* Updated to macOS Catalina.
== 7.2.1 (2019-09-01)
* Updated README screencast tutorial.
* Updated to Ruby 2.6.4.
== 7.2.0 (2019-08-01)
* Added file install function.
== 7.1.2 (2019-06-01)
* Updated contributing documentation.
* Updated to Git Cop 3.5.0.
== 7.1.1 (2019-05-01)
* Added project icon to README.
* Updated to Ruby 2.6.3.
== 7.1.0 (2019-04-01)
* Added XCode installer fix to troubleshooting section.
* Updated to Ruby 2.6.1.
* Updated to Ruby 2.6.2.
== 7.0.0 (2019-01-01)
* Fixed Circle CI cache for Ruby version.
* Fixed installation of apps with no extension.
* Fixed program installs.
* Added Circle CI Bundler cache.
* Added README boot disk documentation.
* Added README troubleshooting section.
* Updated to Git Cop 3.0.0.
* Updated to Ruby 2.6.0.
* Removed Java development tools from setup.
* Removed download file function.
== 6.1.0 (2018-11-01)
* Updated to Java SE Development Kit 11.
* Updated to Ruby 2.5.2.
* Updated to Ruby 2.5.3.
* Removed unnecessary source code comments.
== 6.0.0 (2018-10-01)
* Added XCode install tip.
* Updated boot disk creation to macOS Mojave.
* Updated to Contributor Covenant Code of Conduct 1.4.1.
* Updated to Java SE Development Kit 10.
== 5.0.0 (2018-08-01)
* Fixed Markdown ordered list numbering.
* Fixed verification of Homebrew formulas.
* Added App Store application verification.
* Added Homebrew cask application verifier.
* Updated Git checkout to silence detached head warnings.
* Updated README documentation.
* Updated Semantic Versioning links to be HTTPS.
* Updated boot disk format documentation.
* Updated project changes to use semantic versions.
* Removed Java install support.
* Removed restorer functions.
* Refactored function parameter documentation.
* Refactored library function order.
== 4.1.0 (2018-04-01)
* Updated README license information.
* Updated README screencast tutorial.
* Updated to Circle CI 2.0.0 configuration.
* Updated to Git Cop 2.2.0.
* Updated to Ruby 2.5.1.
* Removed Patreon badge from README.
== 4.0.0 (2018-01-01)
* Added Gemfile.lock to .gitignore.
* Updated to Apache 2.0 license.
* Updated to Ruby 2.4.3.
* Updated to Ruby 2.5.0.
== 3.1.0 (2017-11-26)
* Updated Gemfile.lock file.
* Updated boot disk documenation to mention APFS.
* Updated to Bundler 1.16.0.
* Updated to Git Cop 1.7.0.
* Updated to Rake 12.3.0.
* Updated to Rubocop 0.51.0.
== 3.0.0 (2017-10-01)
* Fixed table of contents.
* Updated boot disk creation to use macOS High Sierra.
* Updated gem dependencies.
* Updated to Git Cop 1.6.0.
* Updated to Ruby 2.4.2.
== 2.2.0 (2017-07-16)
* Added Git Cop support.
* Updated CONTRIBUTING documentation.
* Updated GitHub templates.
* Updated README headers.
* Updated gem dependencies.
== 2.1.0 (2017-04-29)
* Fixed Java SE Development Kit install.
* Fixed install-all command
== 2.0.0 (2017-04-09)
* Added Homebrew Casks install script.
* Updated README semantic versioning order.
* Updated contributing documentation.
* Refactored Homebrew software as Homebrew Formulas.
== 1.3.1 (2017-01-08)
* Fixed install of zip app downloads with sub-directories.
== 1.3.0 (2017-01-01)
* Updated README versioning documentation.
* Removed CHANGELOG.md (use CHANGES.md instead).
== 1.2.0 (2016-10-12)
* Fixed reinstaller path issues with application and extension scripts.
* Added screencast to README.
== 1.1.0 (2016-10-11)
* Fixed Bash script header to dynamically load correct environment.
* Fixed verification of Homebrew application installs.
* Added script hook for App Store software install.
* Added script hooks for unfinished custom configurations.
* Updated and clarified README documentation.
== 1.0.0 (2016-10-05)
* Initial version.

159
CHANGES.md
View File

@@ -1,159 +0,0 @@
# 8.0.1 (2020-01-01)
- Added Startup Security Utility to README.
- Updated README screencast.
- Updated to Ruby 2.7.0.
- Refactored caffeinate machine function to process grep.
# 8.0.0 (2019-10-12)
- Updated to Rake 13.0.0.
- Updated to Ruby 2.6.5.
- Updated to macOS Catalina.
# 7.2.1 (2019-09-01)
- Updated README screencast tutorial.
- Updated to Ruby 2.6.4.
# 7.2.0 (2019-08-01)
- Added file install function.
# 7.1.2 (2019-06-01)
- Updated contributing documentation.
- Updated to Git Cop 3.5.0.
# 7.1.1 (2019-05-01)
- Added project icon to README.
- Updated to Ruby 2.6.3.
# 7.1.0 (2019-04-01)
- Added XCode installer fix to troubleshooting section.
- Updated to Ruby 2.6.1.
- Updated to Ruby 2.6.2.
# 7.0.0 (2019-01-01)
- Fixed Circle CI cache for Ruby version.
- Fixed installation of apps with no extension.
- Fixed program installs.
- Added Circle CI Bundler cache.
- Added README boot disk documentation.
- Added README troubleshooting section.
- Updated to Git Cop 3.0.0.
- Updated to Ruby 2.6.0.
- Removed Java development tools from setup.
- Removed download file function.
# 6.1.0 (2018-11-01)
- Updated to Java SE Development Kit 11.
- Updated to Ruby 2.5.2.
- Updated to Ruby 2.5.3.
- Removed unnecessary source code comments.
# 6.0.0 (2018-10-01)
- Added XCode install tip.
- Updated boot disk creation to macOS Mojave.
- Updated to Contributor Covenant Code of Conduct 1.4.1.
- Updated to Java SE Development Kit 10.
# 5.0.0 (2018-08-01)
- Fixed Markdown ordered list numbering.
- Fixed verification of Homebrew formulas.
- Added App Store application verification.
- Added Homebrew cask application verifier.
- Updated Git checkout to silence detached head warnings.
- Updated README documentation.
- Updated Semantic Versioning links to be HTTPS.
- Updated boot disk format documentation.
- Updated project changes to use semantic versions.
- Removed Java install support.
- Removed restorer functions.
- Refactored function parameter documentation.
- Refactored library function order.
# 4.1.0 (2018-04-01)
- Updated README license information.
- Updated README screencast tutorial.
- Updated to Circle CI 2.0.0 configuration.
- Updated to Git Cop 2.2.0.
- Updated to Ruby 2.5.1.
- Removed Patreon badge from README.
# 4.0.0 (2018-01-01)
- Added Gemfile.lock to .gitignore.
- Updated to Apache 2.0 license.
- Updated to Ruby 2.4.3.
- Updated to Ruby 2.5.0.
# 3.1.0 (2017-11-26)
- Updated Gemfile.lock file.
- Updated boot disk documenation to mention APFS.
- Updated to Bundler 1.16.0.
- Updated to Git Cop 1.7.0.
- Updated to Rake 12.3.0.
- Updated to Rubocop 0.51.0.
# 3.0.0 (2017-10-01)
- Fixed table of contents.
- Updated boot disk creation to use macOS High Sierra.
- Updated gem dependencies.
- Updated to Git Cop 1.6.0.
- Updated to Ruby 2.4.2.
# 2.2.0 (2017-07-16)
- Added Git Cop support.
- Updated CONTRIBUTING documentation.
- Updated GitHub templates.
- Updated README headers.
- Updated gem dependencies.
# 2.1.0 (2017-04-29)
- Fixed Java SE Development Kit install.
- Fixed install-all command
# 2.0.0 (2017-04-09)
- Added Homebrew Casks install script.
- Updated README semantic versioning order.
- Updated contributing documentation.
- Refactored Homebrew software as Homebrew Formulas.
# 1.3.1 (2017-01-08)
- Fixed install of zip app downloads with sub-directories.
# 1.3.0 (2017-01-01)
- Updated README versioning documentation.
- Removed CHANGELOG.md (use CHANGES.md instead).
# 1.2.0 (2016-10-12)
- Fixed reinstaller path issues with application and extension scripts.
- Added screencast to README.
# 1.1.0 (2016-10-11)
- Fixed Bash script header to dynamically load correct environment.
- Fixed verification of Homebrew application installs.
- Added script hook for App Store software install.
- Added script hooks for unfinished custom configurations.
- Updated and clarified README documentation.
# 1.0.0 (2016-10-05)
- Initial version.

11
CODE_OF_CONDUCT.adoc
View File

@@ -100,12 +100,13 @@ disparagement of classes of individuals.
== Attribution
This Code of Conduct is adapted from the Contributor Covenant, version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
This Code of Conduct is adapted from the
link:https://www.contributor-covenant.org/version/2/0/code_of_conduct.html[Contributor Covenant,
version 2.0].
Community Impact Guidelines were inspired by link:https://github.com/mozilla/diversity[Mozilla's
code of conduct enforcement ladder].
For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.
For answers to common questions about this code of conduct, see the
link:https://www.contributor-covenant.org/faq[FAQ]. Translations are available
link:https://www.contributor-covenant.org/translations[here].

22
CONTRIBUTING.adoc Normal file
View File

@@ -0,0 +1,22 @@
= Contributing
Thanks for taking an interest in this open source project. Your support and involvement is greatly
appreciated. The following details what you need to know in order to contribute.
== Code
. Read the project link:README.adoc[README] before starting.
. Fork and clone the `master` branch of this repository locally.
. Ensure there are no setup, usage, and/or test issues.
. Add tests for new functionality and ensure they pass.
. Submit a pull request, follow the instructions provided, and ensure the build passes.
== Issues
Submit an issue via the GitHub Issues tab (assuming one does not already exist) and follow the
instructions provided.
== Feedback
* Expect a response within one to three business days.
* Changes, alternatives, and/or improvements may be suggested upon review.

22
CONTRIBUTING.md
View File

@@ -1,22 +0,0 @@
# Contributing
Thanks for taking an interest in this open source project. Your support and involvement is greatly
appreciated. The following details what you need to know in order to contribute.
## Code
1. Read the project README before starting.
1. Fork and clone the `master` branch of this repository locally.
1. Ensure there are no local setup, usage, and/or test issues.
1. Add tests for new functionality and ensure they pass.
1. Submit a pull request, follow the instructions provided, and ensure the build passes.
## Issues
- Submit an issue via the GitHub Issues tab (assuming one does not already exist) and follow the
instructions provided.
## Feedback
- Expect a response within one to three business days.
- Changes, alternatives, and/or improvements may be suggested upon review.

59
LICENSE.md → LICENSE.adoc
View File

@@ -1,4 +1,4 @@
# Apache License
= Apache License
Version 2.0, January 2004
@@ -6,7 +6,7 @@ http://www.apache.org/licenses
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
## 1. Definitions
== 1. Definitions
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by
Sections 1 through 9 of this document.
@@ -54,14 +54,14 @@ Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a
Contribution has been received by Licensor and subsequently incorporated within the Work.
## 2. Grant of Copyright License
== 2. Grant of Copyright License
Subject to the terms and conditions of this License, each Contributor hereby grants to You a
perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to
reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and
distribute the Work and such Derivative Works in Source or Object form.
## 3. Grant of Patent License
== 3. Grant of Patent License
Subject to the terms and conditions of this License, each Contributor hereby grants to You a
perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
@@ -74,39 +74,38 @@ a Contribution incorporated within the Work constitutes direct or contributory p
then any patent licenses granted to You under this License for that Work shall terminate as of the
date such litigation is filed.
## 4. Redistribution
== 4. Redistribution
You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with
or without modifications, and in Source or Object form, provided that You meet the following
conditions:
1. You must give any other recipients of the Work or Derivative Works a copy of this License; and
. You must give any other recipients of the Work or Derivative Works a copy of this License; and
2. You must cause any modified files to carry prominent notices stating that You changed the
files; and
. You must cause any modified files to carry prominent notices stating that You changed the files;
and
3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright,
patent, trademark, and attribution notices from the Source form of the Work, excluding those
notices that do not pertain to any part of the Derivative Works; and
. You must retain, in the Source form of any Derivative Works that You distribute, all copyright,
patent, trademark, and attribution notices from the Source form of the Work, excluding those
notices that do not pertain to any part of the Derivative Works; and
4. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative
Works that You distribute must include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not pertain to any part of the
Derivative Works, in at least one of the following places: within a NOTICE text file
distributed as part of the Derivative Works; within the Source form or documentation, if
provided along with the Derivative Works; or, within a display generated by the Derivative
Works, if and wherever such third-party notices normally appear. The contents of the NOTICE
file are for informational purposes only and do not modify the License. You may add Your own
attribution notices within Derivative Works that You distribute, alongside or as an addendum to
the NOTICE text from the Work, provided that such additional attribution notices cannot be
construed as modifying the License.
. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works
that You distribute must include a readable copy of the attribution notices contained within such
NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in
at least one of the following places: within a NOTICE text file distributed as part of the
Derivative Works; within the Source form or documentation, if provided along with the Derivative
Works; or, within a display generated by the Derivative Works, if and wherever such third-party
notices normally appear. The contents of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution notices within Derivative Works that
You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such
additional attribution notices cannot be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or
different license terms and conditions for use, reproduction, or distribution of Your modifications,
or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of
the Work otherwise complies with the conditions stated in this License.
## 5. Submission of Contributions
== 5. Submission of Contributions
Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the
Work by You to the Licensor shall be under the terms and conditions of this License, without any
@@ -114,13 +113,13 @@ additional terms or conditions. Notwithstanding the above, nothing herein shall
the terms of any separate license agreement you may have executed with Licensor regarding such
Contributions.
## 6. Trademarks
== 6. Trademarks
This License does not grant permission to use the trade names, trademarks, service marks, or product
names of the Licensor, except as required for reasonable and customary use in describing the origin
of the Work and reproducing the content of the NOTICE file.
## 7. Disclaimer of Warranty
== 7. Disclaimer of Warranty
Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -129,7 +128,7 @@ TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. Y
responsible for determining the appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
## 8. Limitation of Liability
== 8. Limitation of Liability
In no event and under no legal theory, whether in tort (including negligence), contract, or
otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or
@@ -139,7 +138,7 @@ License or out of the use or inability to use the Work (including but not limite
loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial
damages or losses), even if such Contributor has been advised of the possibility of such damages.
## 9. Accepting Warranty or Additional Liability
== 9. Accepting Warranty or Additional Liability
While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee
for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights
@@ -151,11 +150,11 @@ additional liability.
END OF TERMS AND CONDITIONS
Copyright 2016 [Alchemists](https://www.alchemists.io).
Copyright link:https://www.alchemists.io[Alchemists].
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
compliance with the License. You may obtain a [copy](http://www.apache.org/licenses/LICENSE-2.0) of
the License.
compliance with the License. You may obtain a link:https://www.apache.org/licenses/LICENSE-2.0[copy]
of the License.
Unless required by applicable law or agreed to in writing, software distributed under the License is
distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or

251
README.adoc Normal file
View File

@@ -0,0 +1,251 @@
:toc: macro
:toclevels: 5
:figure-caption!:
= macOS
[link=https://circleci.com/gh/bkuhlmann/mac_os]
image::https://circleci.com/gh/bkuhlmann/mac_os.svg?style=svg[Circle CI Status]
Shell scripts for automated macOS machine setup.
This project is a framework for automating the setup of a macOS machine. In order to illustrate the
potential of what this project can do, please see the companion
link:https://www.alchemists.io/projects/mac_os-config[macOS Config] project for details. The _macOS
Config_ project is an opinionated configuration which meets the needs of my development environment
but is also meant to serve as an example and guide for building your own personalized setup. Here is
how the two projects are meant to be used:
* *macOS* (this project) - The foundation framework for building customizated macOS machine setups.
* *link:https://www.alchemists.io/projects/mac_os-config[macOS Configuration]* - The layer on top of
this _macOS_ project which defines a custom machine setup and base implementation. The project is
meant to be forked for as many custom machine setups as needed.
toc::[]
== Features
* Provides a command line interface, written in Bash, with no additional dependencies for
installation and management of a macOS machine.
* Supports macOS boot disk creation for fresh install of operating system.
* Downloads and installs link:https://developer.apple.com/xcode[Xcode Command Line Tools].
* Downloads, installs, and configures link:http://brew.sh[Homebrew Formulas].
* Downloads, installs, and configures link:https://caskroom.github.io[Homebrew Casks].
* Downloads, installs, and configures link:http://www.apple.com/macosx/whats-new/app-store.html[App
Store] software.
* Downloads, installs, and configures non-App Store software applications.
* Downloads, installs, and configures software application extensions.
* Applies basic and default software settings.
* Sets up and configures installed software for use.
* Supports restoration of machine backups.
== Screencast
[link=https://www.alchemists.io/screencasts/mac_o_s.html]
image::https://www.alchemists.io/images/screencasts/mac_o_s.png[Screencast]
== Requirements
. https://www.apple.com/macos/catalina[macOS Catalina] (with latest software updates applied)
. https://developer.apple.com/xcode[Xcode] (with accepted license agreement)
== Setup
=== Production
To install, run:
[source,bash]
----
git clone https://github.com/bkuhlmann/mac_os.git
cd mac_os
git checkout 8.0.1
----
=== Development
To contribute, run:
[source,bash]
----
git clone https://github.com/bkuhlmann/mac_os.git
cd mac_os
----
== Usage
Run the following:
[source,bash]
----
bin/run
----
You will be presented with the following options (listed in order of
use):
....
Boot:
B: Create boot disk.
Install:
b: Apply basic settings.
t: Install development tools.
hf: Install Homebrew Formulas.
hc: Install Homebrew Casks.
m: Install Mac App Store software.
a: Install application software.
x: Install application software extensions.
d: Apply default settings.
s: Setup installed software.
i: Install everything (i.e. executes all install options).
Restore:
R: Restore settings from backup.
Manage:
c: Check status of managed software.
C: Caffeinate machine.
ua: Uninstall application software.
ux: Uninstall application software extension.
ra: Reinstall application software.
rx: Reinstall application software extension.
w: Clean work (temp) directory.
q: Quit/Exit.
....
Choose option `i` to run a full install or select a specific option to run a single action. Each
option is designed to be re-run if necessary. This can also be handy for performing upgrades,
re-running a missing/failed install, etc.
The option prompt can be skipped by passing the desired option directly to the `bin/run` script. For
example, executing `bin/run i` will execute the full install process.
The machine should be rebooted after all install tasks have completed to ensure all settings have
been loaded.
It is recommended that the `mac_os` project directory not be deleted and kept on the local machine
in order to manage installed software and benefit from future upgrades.
=== Boot Disk
When attempting to create a boot disk via `bin/run B`, you’ll be presented with the following
documentation (provided here for reference):
....
macOS Boot Disk Tips
- Use a USB drive (8GB or higher).
- Use Disk Utility to format the USB drive as "Mac OS Extended (Journaled)".
- Use Disk Utility to label the USB drive as "Untitled".
macOS Boot Disk Usage:
1. Insert the USB boot disk into the machine to be upgraded.
2. Reboot the machine.
3. Hold down the OPTION key before the Apple logo appears.
4. Select the USB boot disk from the menu.
5. Use Disk Utility to format the machine's drive as "APFS (Encrypted)".
6. Install the new operating system.
macOS Reinstall:
1. Click the Apple icon from the operating system main menu.
2. Select the "Restart..." menu option.
3. Hold down the COMMAND+R keys before the Apple logo appears.
4. Wait for the macOS installer to load from the recovery partition.
5. Use the dialog options to launch Disk Utility, reinstall the system, etc.
....
Depending on your security settings, you might need to use the Startup
Security Utility before using the Boot Disk (see below).
=== https://support.apple.com/en-us/HT208198[Startup Security Utility]
With newer hardware, you should be running with the Apple T2 Security Chip (found via  → About This
Mac → Overview → System Report → Controller). In order to boot your machine using the Boot Disk,
you’ll need to _temporarily_ disable the default security settings as follows:
* Turn on or restart your Mac, then press and hold `COMMAND + R` immediately after seeing the Apple
logo.
* Select Utilities → Startup Security Utility from the main menu.
* Click _Turn Off Firmware Password_.
* Select _Secure Boot: No Security_.
* Select _External Boot: Allow booting from external media_.
* Quit the utility and restart the machine.
You’ll now be able to boot your system with the Boot Disk (see above).
After the new operating system has been installed via the Boot Disk, _ensure you return to the
Startup Security Utility and re-enable the following settings_:
* Click _Turn On Firmware Password_.
* Select _Secure Boot: Full Security_.
* Select _External Boot: Disallow booting from external or removable media_.
=== Customization
All executable scripts can be found in the `bin` folder:
* `bin/apply_basic_settings`: Applies basic, initial, settings for setting up a machine. _Can be
customized._
* `bin/apply_default_settings`: Applies useful system and application defaults. _Can be customized._
* `bin/create_boot_disk`: Creates macOS boot disk.
* `bin/install_app_store`: Installs macOS, GUI-based, App Store applications. _Can be customized._
* `bin/install_applications`: Installs macOS, GUI-based, non-App Store applications. _Can be
customized._
* `bin/install_dev_tools`: Installs macOS development tools required by Homebrew.
* `bin/install_extensions`: Installs macOS application extensions and add-ons. _Can be customized._
* `bin/install_homebrew_casks`: Installs Homebrew Formulas. _Can be customized._
* `bin/install_homebrew_formulas`: Installs Homebrew Casks. _Can be customized._
* `bin/restore_backup`: Restores system/application settings from backup image. _Can be customized._
* `bin/run`: The main script and interface for macOS setup.
* `bin/setup_software`: Configures and launches (if necessary) installed software. _Can be
customized._
The `lib` folder provides the base framework for installing, re-installing, and uninstalling
software. Everything provided via the link:https://www.alchemists.io/projects/mac_os-config[macOS
Config] project is built upon the functions found in the `lib` folder. See the
link:https://www.alchemists.io/projects/mac_os-config[macOS Config] project for further details.
* `lib/settings.sh`: Defines global settings for software applications, extensions, etc.
== Troubleshooting
* When using the boot disk, you might experience a situation where you see a black screen with a
white circle and diagonal line running through it. This means macOS lost or can’t find the boot
disk for some reason. To correct this, shut down and boot up the system again while holding down
the `OPTION+COMMAND+R+P` keys simultaneously. You might want to wait for the system boot sound to
happen a few times before releasing the keys. This will clear the system NVRAM/PRAM. At this point
you can shut down and restart the system following the boot disk instructions (the boot disk will
be recognized now).
* Sometimes, when installing XCode development tools (i.e. the `t` option), not all of the macOS
headers will be installed. This can cause issues with compiling and building native packages. For
example: `fatal error: 'stdio.h' file not found`. This can happen due to an intermittent bug with
the XCode installer. To fix this, you’ll need to install this package:
`/Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg`. Depending on
your system, the version might differ, so look for a `*.pkg` in the
`/Library/Developer/CommandLineTools/Packages` folder.
== Versioning
Read link:https://semver.org[Semantic Versioning] for details. Briefly, it means:
* Major (X.y.z) - Incremented for any backwards incompatible public API changes.
* Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
* Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.
== Code of Conduct
Please note that this project is released with a link:CODE_OF_CONDUCT.adoc[CODE OF CONDUCT]. By
participating in this project you agree to abide by its terms.
== Contributions
Read link:CONTRIBUTING.adoc[CONTRIBUTING] for details.
== License
Read link:LICENSE.adoc[LICENSE] for details.
== History
Read link:CHANGES.adoc[CHANGES] for details.
== Credits
Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann.html[Brooke Kuhlmann].

261
README.md
View File

@@ -1,261 +0,0 @@
<p align="center">
<img src="https://www.alchemists.io/images/projects/mac_os/icon.png" alt="MacOS Icon"/>
</p>
# macOS
[![Circle CI Status](https://circleci.com/gh/bkuhlmann/mac_os.svg?style=svg)](https://circleci.com/gh/bkuhlmann/mac_os)
Shell scripts for automated macOS machine setup.
This project is a framework for automating the setup of a macOS machine. In order to illustrate the
potential of what this project can do, please see the companion
[macOS Config](https://github.com/bkuhlmann/mac_os-config) project for details. The *macOS Config*
project is an opinionated configuration which meets the needs of my development environment but is
also meant to serve as an example and guide for building your own personalized setup. Here is how
the two projects are meant to be used:
- **macOS** (this project) - The foundation framework for building customizated macOS machine
setups.
- **[macOS Configuration](https://github.com/bkuhlmann/mac_os-config)** - The layer on top of this
*macOS* project which defines a custom machine setup and base implementation. The project is meant
to be forked for as many custom machine setups as needed.
<!-- Tocer[start]: Auto-generated, don't remove. -->
## Table of Contents
- [Features](#features)
- [Screencast](#screencast)
- [Requirements](#requirements)
- [Setup](#setup)
- [Production](#production)
- [Development](#development)
- [Usage](#usage)
- [Boot Disk](#boot-disk)
- [Startup Security Utility](#startup-security-utility)
- [Customization](#customization)
- [Troubleshooting](#troubleshooting)
- [Versioning](#versioning)
- [Code of Conduct](#code-of-conduct)
- [Contributions](#contributions)
- [License](#license)
- [History](#history)
- [Credits](#credits)
<!-- Tocer[finish]: Auto-generated, don't remove. -->
## Features
- Provides a command line interface, written in Bash, with no additional dependencies for
installation and management of a macOS machine.
- Supports macOS boot disk creation for fresh install of operating system.
- Downloads and installs [Xcode Command Line Tools](https://developer.apple.com/xcode).
- Downloads, installs, and configures [Homebrew Formulas](http://brew.sh).
- Downloads, installs, and configures [Homebrew Casks](https://caskroom.github.io).
- Downloads, installs, and configures
[App Store](http://www.apple.com/macosx/whats-new/app-store.html) software.
- Downloads, installs, and configures non-App Store software applications.
- Downloads, installs, and configures software application extensions.
- Applies basic and default software settings.
- Sets up and configures installed software for use.
- Supports restoration of machine backups.
## Screencast
[![asciicast](https://asciinema.org/a/278158.svg)](https://asciinema.org/a/278158)
## Requirements
1. [macOS Catalina](https://www.apple.com/macos/catalina) (with latest software updates applied)
1. [Xcode](https://developer.apple.com/xcode) (with accepted license agreement)
## Setup
### Production
To install, run:
git clone https://github.com/bkuhlmann/mac_os.git
cd mac_os
git checkout 8.0.1
### Development
To contribute, run:
git clone https://github.com/bkuhlmann/mac_os.git
cd mac_os
## Usage
Run the following:
bin/run
You will be presented with the following options (listed in order of use):
Boot:
B: Create boot disk.
Install:
b: Apply basic settings.
t: Install development tools.
hf: Install Homebrew Formulas.
hc: Install Homebrew Casks.
m: Install Mac App Store software.
a: Install application software.
x: Install application software extensions.
d: Apply default settings.
s: Setup installed software.
i: Install everything (i.e. executes all install options).
Restore:
R: Restore settings from backup.
Manage:
c: Check status of managed software.
C: Caffeinate machine.
ua: Uninstall application software.
ux: Uninstall application software extension.
ra: Reinstall application software.
rx: Reinstall application software extension.
w: Clean work (temp) directory.
q: Quit/Exit.
Choose option `i` to run a full install or select a specific option to run a single action. Each
option is designed to be re-run if necessary. This can also be handy for performing upgrades,
re-running a missing/failed install, etc.
The option prompt can be skipped by passing the desired option directly to the `bin/run` script. For
example, executing `bin/run i` will execute the full install process.
The machine should be rebooted after all install tasks have completed to ensure all settings have
been loaded.
It is recommended that the `mac_os` project directory not be deleted and kept on the local machine
in order to manage installed software and benefit from future upgrades.
### Boot Disk
When attempting to create a boot disk via `bin/run B`, you'll be presented with the following
documentation (provided here for reference):
macOS Boot Disk Tips
- Use a USB drive (8GB or higher).
- Use Disk Utility to format the USB drive as "Mac OS Extended (Journaled)".
- Use Disk Utility to label the USB drive as "Untitled".
macOS Boot Disk Usage:
1. Insert the USB boot disk into the machine to be upgraded.
2. Reboot the machine.
3. Hold down the OPTION key before the Apple logo appears.
4. Select the USB boot disk from the menu.
5. Use Disk Utility to format the machine's drive as "APFS (Encrypted)".
6. Install the new operating system.
macOS Reinstall:
1. Click the Apple icon from the operating system main menu.
2. Select the "Restart..." menu option.
3. Hold down the COMMAND+R keys before the Apple logo appears.
4. Wait for the macOS installer to load from the recovery partition.
5. Use the dialog options to launch Disk Utility, reinstall the system, etc.
Depending on your security settings, you might need to use the Startup Security Utility before using
the Boot Disk (see below).
### [Startup Security Utility](https://support.apple.com/en-us/HT208198)
With newer hardware, you should be running with the Apple T2 Security Chip (found via  → About This
Mac → Overview → System Report → Controller). In order to boot your machine using the Boot Disk,
you'll need to *temporarily* disable the default security settings as follows:
- Turn on or restart your Mac, then press and hold `COMMAND + R` immediately after seeing the Apple
logo.
- Select Utilities → Startup Security Utility from the main menu.
- Click "Turn Off Firmware Password".
- Select "Secure Boot: No Security".
- Select "External Boot: Allow booting from external media".
- Quit the utility and restart the machine.
You'll now be able to boot your system with the Boot Disk (see above).
After the new operating system has been installed via the Boot Disk, *ensure you return to the
Startup Security Utility and re-enable the following settings*:
- Click "Turn On Firmware Password".
- Select "Secure Boot: Full Security".
- Select "External Boot: Disallow booting from external or removable media".
### Customization
All executable scripts can be found in the `bin` folder:
- `bin/apply_basic_settings`: Applies basic, initial, settings for setting up a machine. *Can be
customized.*
- `bin/apply_default_settings`: Applies useful system and application defaults. *Can be customized.*
- `bin/create_boot_disk`: Creates macOS boot disk.
- `bin/install_app_store`: Installs macOS, GUI-based, App Store applications. *Can be customized.*
- `bin/install_applications`: Installs macOS, GUI-based, non-App Store applications. *Can be
customized.*
- `bin/install_dev_tools`: Installs macOS development tools required by Homebrew.
- `bin/install_extensions`: Installs macOS application extensions and add-ons. *Can be customized.*
- `bin/install_homebrew_casks`: Installs Homebrew Formulas. *Can be customized.*
- `bin/install_homebrew_formulas`: Installs Homebrew Casks. *Can be customized.*
- `bin/restore_backup`: Restores system/application settings from backup image. *Can be customized.*
- `bin/run`: The main script and interface for macOS setup.
- `bin/setup_software`: Configures and launches (if necessary) installed software. *Can be
customized.*
The `lib` folder provides the base framework for installing, re-installing, and uninstalling
software. Everything provided via the [macOS Config](https://github.com/bkuhlmann/mac_os-config)
project is built upon the functions found in the `lib` folder. See the
[macOS Config](https://github.com/bkuhlmann/mac_os-config) project for further details.
- `lib/settings.sh`: Defines global settings for software applications, extensions, etc.
## Troubleshooting
- When using the boot disk, you might experience a situation where you see a black screen with a
white circle and diagonal line running through it. This means macOS lost or can't find the boot
disk for some reason. To correct this, shut down and boot up the system again while holding down
the `OPTION+COMMAND+R+P` keys simultaneously. You might want to wait for the system boot sound to
happen a few times before releasing the keys. This will clear the system NVRAM/PRAM. At this point
you can shut down and restart the system following the boot disk instructions (the boot disk will
be recognized now).
- Sometimes, when installing XCode development tools (i.e. the `t` option), not all of the macOS
headers will be installed. This can cause issues with compiling and building native packages. For
example: `fatal error: 'stdio.h' file not found`. This can happen due to an intermittent bug with
the XCode installer. To fix this, you'll need to install this package:
`/Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg`. Depending on
your system, the version might differ, so look for a `*.pkg` in the
`/Library/Developer/CommandLineTools/Packages` folder.
## Versioning
Read [Semantic Versioning](https://semver.org) for details. Briefly, it means:
- Major (X.y.z) - Incremented for any backwards incompatible public API changes.
- Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
- Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.
## Code of Conduct
Please note that this project is released with a [CODE OF CONDUCT](CODE_OF_CONDUCT.md). By
participating in this project you agree to abide by its terms.
## Contributions
Read [CONTRIBUTING](CONTRIBUTING.md) for details.
## License
Copyright 2016 [Alchemists](https://www.alchemists.io).
Read [LICENSE](LICENSE.md) for details.
## History
Read [CHANGES](CHANGES.md) for details.
Built with [Bashsmith](https://github.com/bkuhlmann/bashsmith).
## Credits
Developed by [Brooke Kuhlmann](https://www.alchemists.io) at
[Alchemists](https://www.alchemists.io).