Update docs for os.platform() to enumerate the return values and conditions

[tomprogers]

The entry for os.arch() lists all the possible return values, and it's clear under what conditions each applies.

Please do the same thing for os.platform(). It's not convenient to execute an exploratory console.log(os.platform()) on each OS a developer wishes to support.

Perhaps something like this is appropriate (note: data invented for illustration purposes -- this list is a wild guess!):

OS	return
Windows XP	"win32"
Windows 7/8 32-bit	"win32" [sic]
Windows 7/8 64-bit	"win32" [sic]
MacOS	"darwin"
Ubuntu, Gentoo, RedHat	"linux"

Even a more general enumeration would be very helpful, if it's completely accurate (again, I don't know if any of the details are true):

All supported Windows versions (up to and including Windows 7 SP1) return "win32"; all supported MacOS versions (up to 10.10) return "darwin"; any identifiably *nix-like platform returns "linux"; anything not recognized returns null.

I think there is interest in this information. See e.g. this Stack Overflow question, and note how many upvotes comments have received for providing just one of the needed datapoints.

I think it's reasonable for the project to maintain documentation for these values, assuming the project also maintains the nodejs implementation of os.platform() on each of the platforms.

[hertzg]

I kind of memorised it long ago but yes i agree it should be documented 👍

[jasnell]

PR? :-)

[tomprogers]

@jasnell If you're asking me why I haven't submitted a PR, the answer is: I don't have the information. As I suggest in the ticket, in order for the documentation to be useful it has to be completely accurate. I don't have the skills necessary to maintain the nodejs apps, let alone on the various platforms, and therefore I don't have the skills necessary to enumerate the possible values or discern what are the conditions under which each will be returned.

You'll have to find someone else to do the work.

[joshgav]

os.platform() comes directly from process.platform(), that's as far as I've gotten so far. I'll try to drill in further and see where that comes from.

[tomprogers]

I will update the ticket with accurate information if @joshgav and others post their findings in these comments.

[hertzg]

os.platform() is a function alias (something like a getter) for process.platform property as @joshgav said.

process.platform has the value of PLATFORM constant which in turn is gyps OS constant, except for these cases

OS	PLATFORM
win	win32
mac	darwin
solaris	sunos

_Note_ from gyps docs:

• OS: The name of the operating system that the generator produces output for. Common values for values for OS are:
  • 'linux'
  • 'mac'
  • 'win'

_But other values may be encountered and this list should not be considered exhaustive_. The gypd (debug) generator module does not provide a predefined value for OS. When invoking GYP with the gypd module, if a value for OS is needed, it must be provided on the command line, such as gyp -f gypd -DOS=mac.

GYP generators also provide defaults for these variables. They may be expressed in terms of variables used by the build system that they generate for, often in $(VARIABLE) format. For example, the GYP PRODUCT_DIR variable maps to the Xcode BUILT_PRODUCTS_DIR variable, so PRODUCT_DIR is defined by the Xcode generator as $(BUILT_PRODUCTS_DIR).

/cc @tomprogers

[tomprogers]

@hertzg Thanks!

Is solaris the only exception to the "*nix == 'linux'" rule? Is there a fallback value, in case node can't identify the OS?

[hertzg]

I've updated my comment

@tomprogers The default value for PLATFORM is the value of OS

[joshgav]

So os.platform() == process.platform() == PLATFORM
and PLATFORM == OS unless PLATFORM == /mac|win|solaris/, in which case see @hertzg's chart.

Only question remaining is where gyp gets the OS value from and if there are potential values other than /mac|win|linux|solaris/.

At the very least our docs could match gyp's and say "Common values for platform() are darwin, win32, sunos, and linux."

[hertzg]

So os.platform() == process.platform() == PLATFORM
and PLATFORM == OS unless PLATFORM == /mac|win|solaris/, in which case see @hertzg's chart.

@joshgav process.platform is not a function

[hertzg]

Digging deeper showed some more information

gyp uses pythons sys.platform to auto detect system flavour,

def GetFlavor(params):
  """Returns |params.flavor| if it's set, the system's default flavor else."""
  flavors = {
    'cygwin': 'win',
    'win32': 'win',
    'darwin': 'mac',
  }
  if 'flavor' in params:
    return params['flavor']
  if sys.platform in flavors:
    return flavors[sys.platform]
  if sys.platform.startswith('sunos'):
    return 'solaris'
  if sys.platform.startswith('freebsd'):
    return 'freebsd'
  if sys.platform.startswith('openbsd'):
    return 'openbsd'
  if sys.platform.startswith('aix'):
    return 'aix'
  return 'linux'

Pythons documentation of sys.platform

To sum it all up os.platform() probably can only return these values.

System	os.platform()
Android	android
Windows/Cygwin	win32
Mac OS X	darwin
FreeBSD	freebsd
OpenBSD	openbsd
IBM AIX	aix
Solaris	sunos
Linux & Others	linux

/cc @jasnell

_UPDATE_:
https://github.com/joyent/node/blob/v0.12/configure#L42-L46
https://github.com/joyent/node/blob/v0.12/configure#L511-L513
https://github.com/joyent/node/blob/v0.12/configure#L982-L987

parser.add_option('--dest-os',
    action='store',
    dest='dest_os',
    help='operating system to build for. Valid values are: '
         'win, mac, solaris, freebsd, openbsd, linux, android')

# ....

def configure_node(o):
  if options.dest_os == 'android':
    o['variables']['OS'] = 'android'

# ....

# determine the "flavor" (operating system) we're building for,
# leveraging gyp's GetFlavor function
flavor_params = {}
if (options.dest_os):
  flavor_params['flavor'] = options.dest_os
flavor = GetFlavor(flavor_params)

[jasnell]

@hertzg ... excellent detail and very helpful. /cc @misterdjules