250 lines
9.9 KiB
Plaintext
250 lines
9.9 KiB
Plaintext
: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_os]
|
||
image::https://www.alchemists.io/images/screencasts/mac_os/cover.svg[Screencast,600,240,role=focal_point]
|
||
|
||
== Requirements
|
||
|
||
. link:https://www.apple.com/macos/big-sur[macOS Big Sur]
|
||
. link:https://developer.apple.com/xcode[Xcode]
|
||
|
||
== Setup
|
||
|
||
To install, run:
|
||
|
||
[source,bash]
|
||
----
|
||
git clone https://github.com/bkuhlmann/mac_os.git
|
||
cd mac_os
|
||
git checkout 11.0.0
|
||
----
|
||
|
||
== 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.
|
||
|
||
== Development
|
||
|
||
To contribute, run:
|
||
|
||
[source,bash]
|
||
----
|
||
git clone https://github.com/bkuhlmann/mac_os.git
|
||
cd mac_os
|
||
----
|
||
|
||
== 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[Brooke Kuhlmann].
|