What does and should go into /opt/ and what should/does go into /usr/? My understanding is that /usr/ used to be for user home directories, but since they exist in /Users/ - what is the purpose now?
Is there a manual or guide to what all of the built-in directories should be used for? Like what is /home/, or /net/?
Is there a manual or guide to what all of the built-in directories should be used for? Like what is /home/, or /net/?
Take a look at the File System Programming Guide for the most up-to-date information and at man hier in Terminal, which provides a "historical sketch" of the filesystem hierarchy (it's included at the end of this answer for reference).
A comment to your question mentions the Filesystem Hierarchy Standard. You will probably come to the conclusion, after perusing File System Programming Guide and man hier, that macOS doesn't follow the FHS, that's more of a Linux thing. Of course, there are similarities between the FHS and the filesystem layout in macOS because of the common UNIX origin, but the differences are striking. macOS doesn't use any of these:
/boot folder -> macOS uses /System/Library/Kernels instead (in older versions of macOS, the folder containing the kernel was /)/home folder -> macOS uses /Users instead/root folder -> macOS uses /var/root insteadand /opt isn't mentioned not one time in any document (more on /opt below.)
A further distiction between macOS and a FHS-compliant OS is the use of /private, for example /etc is a symlink to /private/etc.
About /net: It is an automounter map (listed in /etc/auto_master), see Wikipedia for more information.
What does and should go into /opt/ and what should/does go into /usr/? My understanding is that /usr/ used to be for user home directories, but since that exists in /Users/ - what is the purpose now?
Although /usr was used in the past to place the home directories of the users, that's no longer the case.
Nowadays, /usr contains user commands (in /usr/bin for normal users and /usr/sbin for administrative users, like root), shared libraries (/usr/lib), man pages (/usr/share/man), executables that shouldn't be run directly by users (/usr/libexec) and other stuff.
It also offers a subdirectory, /usr/local, to place programs, libraries and other files that don't come with the base OS.
/opt has a very similar role to /usr/local and they seem interchangeable. However, from my experience working with other Linux/UNIX sysadmins, there seems to be a preference for /usr/local in BSD-based UNIX OSs.
So this is my take on it: macOS is BSD-based and consequently I'd use /usr/local. Note that you can create a program directory and then symlink commands to /usr/local/bin, etc, for example:
/usr/local/mysql
/usr/local/mysql/bin/mysqladmin
/usr/local/mysql/lib/libmysqlclient.so
/usr/local/bin/mysqladmin -> ../mysql/bin/mysqladmin
/usr/local/lib/libmysqlclient.so -> ../mysql/lib/libmysqlclient.so
This used to be usual practice in Linux and UNIX too, but the FHS explicitely forbids it: if you wish to install third party packages in their own directory hierarchy you should use/opt/<package> instead. Note that FHS-compliance requires to put configuration files in /etc/opt/<package> and variable files in /var/opt/<package>.
So, in macOS, I'd recommend that you stick to /usr/local as described above.
I'm aware of add-on software like Cisco VPN and XQuartz that install in /opt, so the above distinctions start to blur.
man hier
As mentioned above this is man hier:
A historical sketch of the filesystem hierarchy. The modern macOS filesystem is documented in the
``File System Programming Guide'' available on Apple Developer.
/ root directory of the filesystem
/bin/ user utilities fundamental to both single-user and multi-user environments
/dev/ block and character device files
fd/ file descriptor files; see fd(4)
/etc/ system configuration files and scripts
/mach_kernel kernel executable (the operating system loaded into memory at boot time).
/sbin/ system programs and administration utilities fundamental to both single-user and multi-
user environments
/tmp/ temporary files
/usr/ contains the majority of user utilities and applications
bin/ common utilities, programming tools, and applications
include/ standard C include files
arpa/ C include files for Internet service protocols
hfs/ C include files for HFS
machine/ machine specific C include files
net/ misc network C include files
netinet/ C include files for Internet standard protocols; see inet(4)
nfs/ C include files for NFS (Network File System)
objc/ C include files for Objective-C
protocols/ C include files for Berkeley service protocols
sys/ system C include files (kernel data structures)
ufs/ C include files for UFS
lib/ archive libraries
libexec/ system daemons & system utilities (executed by other programs)
local/ executables, libraries, etc. not included by the basic operating system
sbin/ system daemons & system utilities (executed by users)
share/ architecture-independent data files
calendar/ a variety of pre-fab calendar files; see calendar(1)
dict/ word lists; see look(1)
web2 words from Webster's 2nd International
words common words
man/ manual pages
misc/ misc system-wide ascii text files
mk/ templates for make; see make(1)
skel/ example . (dot) files for new accounts
tabset/ tab description files for a variety of terminals; used in the term-
cap file; see termcap(5)
zoneinfo/ timezone configuration information; see tzfile(5)
/var/ multi-purpose log, temporary, transient, and spool files
at/ timed command scheduling files; see at(1)
backups/ misc. backup files
db/ misc. automatically generated system-specific database files
log/ misc. system log files
mail/ user mailbox files
run/ system information files describing various info about system since it was
booted
utmpx database of current users; see utmpx(5)
rwho/ rwho data files; see rwhod(8), rwho(1), and ruptime(1)
spool/ misc. printer and mail system spooling directories
mqueue/ undelivered mail queue; see sendmail(8)
tmp/ temporary files that are kept between system reboots
folders/ per-user temporary files and caches
/usr/X11 has always been the standard location for X11 in many UNIX and Linux distributions, including OS X. It has been used in the past by Apple itself, on 10.5.8 there was a package called com.apple.pkg.X11User that provided X11 in exactly that path. My MacBook Pro still has a X11 package named com.apple.pkg.X11redirect installed in /usr/X11, I guess from "Lion" or "Mountain Lion", since X11 is no longer included with OS X (http://support.apple.com/kb/HT5293).
– jaume
Jan 30 '14 at 19:35
man hier): Apple's Mac OS X manual page for hier(7)
– Graham Perrin
Mar 14 '16 at 06:34
/Applications and /opt/X11. The "7" in parentheses in Graham Perrin's answer is the section in which the man page for hier is located. For more information on man sections, see https://unix.stackexchange.com/questions/3586/what-do-the-numbers-in-a-man-page-mean#3587.
– jaume
Nov 02 '17 at 08:01
mach_kernel no longer seems to be in the root directory, at least when I checked on my machine. Granted, this could have something to do with OS X v10.11.x's introduction of System Integrity Protection, but that's only an unchecked guess on my part.
– RandomDSdevel
Jul 16 '18 at 17:25
When I read of /opt (often associated with /opt/local for MacPorts) and of 'standard' uses of paths, I think also of Fink, which has been around since at least 2001. Fink popularlised use of the following path:
/sw
Virex 7.2, free to all .Mac members, infamously overwrote Fink libraries:
This is very bad. Fink users, don't install this …
/Volumes/Virex 7.2.dmg/Virex 7.2.pkg 328 % lsbom Contents/Resources/Virex\ 7.2.bom | grep sw
./sw 40775 0/80
./sw/lib 40775 0/80
./sw/lib/libcrypto.0.9.6.dylib 100644 0/80 945416 3192711062
./sw/lib/libcurl.2.0.2.dylib 100644 0/80 634480 510417796
./sw/lib/libcurl.2.dylib 100644 0/80 634480 510417796
./sw/lib/libdl.0.dylib 100644 0/80 15124 4193639260
./sw/lib/libssl.0.9.6.dylib 100644 0/80 261776 3001832603
Other discussions of the incident, including respect for licensing, included:
A Fink news item:
Virex problem resolved
McAfee has released Virex 7.2.1, which no longer overwrites the main Fink directory
/sw. Fink users should continue to avoid Virex 7.2.Early reports indicate that upgrading Virex from 7.2 to 7.2.1 still leaves some problems however. If you upgrade Virex with Fink not installed, and subsequently wish to install Fink, you will need to delete the
/swdirectory by hand before installing. And if you upgrade Virex with Fink already installed, you should immediately run fink reinstall openssl-shlibs dlcompat-shlibs curl-ssl-shlibs to restore files which the Virex upgrade may have deleted.
Release Notes for McAfee Virex Version 7.2.1 made no mention of the problems caused to users of Fink.
As a side note …
Observations that Virex 7.5 was no longer available to .Mac members.
… OS X … My understanding is that
/usr/used to be for user home directories …
That's still true for operating systems such as FreeBSD and PC-BSD.
Whilst /usr/home/ is not explicit at https://www.freebsd.org/cgi/man.cgi?query=hier&sektion=7&manpath=FreeBSD+10.2-RELEASE the path is exemplified in documents such as:
