Can anyone explain (or more likely, point to a good article that explains) what the various directories should be used for. (I assume the structure is very similar on all Unix based machines, though maybe I'm wrong about this).
Having just made the switch from windows to OSX for my dev machine I'm a bit overwhelmed by the directory structure so, for example when PHP Pyrus setup asks me to choose a directory to store PEAR packages in, I haven't a clue what is a sensible choice.
OS X has both a user-friendly directory structure (with top-level folders named /Applications, /System, /Users, /Library), as well as a standard Unix directory hierarchy that is hidden in Finder (/bin, /etc, /var, /usr, ...) — those folders are documented in man hier.
Additionally, there are differences between the Unix directories (at least as used in OS X), and those you'd find in Linux: For example, the latter has /srv.
The best explanation is probably in the developer documentation by Apple, which is too long to be quoted here. Note that at the moment, the linked article is both for iOS (at the top) and OS X (further down).
Where to place files also depends on the realm the application comes from: It makes sense to place Unix libraries in /usr/local/lib or similar directories, while OS X libraries would be e.g. in /Libraryor similar. Some tools (Perl, Python, Ruby) were configured to work with the latter file system structure.
This article explains the top level file hierarchy: http://osxdaily.com/2007/03/30/mac-os-x-directory-structure-explained
Apple's BSD layer under, /usr is inline with the Filesystem Hierarchy Standard
