testing/mozbase/mozinfo/README.md
author Adam <adam@sigterm.info>
Fri, 02 Mar 2012 18:28:29 -0600
changeset 91433 6d139ebc0f43b3bba6daccfb91db8cbc2c378823
parent 82602 b10b930500f1df703e4c1b11a1ec395a9c4c89b9
child 98529 f4157e8c410708d76703f19e4dfb61859bfe32d8
permissions -rw-r--r--
Make "let" a reserved word for Web scripts. Bug 730139, r=jorendorff.

Throughout [mozmill](https://developer.mozilla.org/en/Mozmill)
and other Mozilla python code, checking the underlying
platform is done in many different ways.  The various checks needed
lead to a lot of copy+pasting, leaving the reader to wonder....is this
specific check necessary for (e.g.) an operating system?  Because
information is not consolidated, checks are not done consistently, nor
is it defined what we are checking for.

[MozInfo](https://github.com/mozilla/mozbase/tree/master/mozinfo)
proposes to solve this problem.  MozInfo is a bridge interface,
making the underlying (complex) plethora of OS and architecture
combinations conform to a subset of values of relavence to 
Mozilla software. The current implementation exposes relavent key,
values: `os`, `version`, `bits`, and `processor`.  Additionally, the
service pack in use is available on the windows platform.


# API Usage

MozInfo is a python package.  Downloading the software and running
`python setup.py develop` will allow you to do `import mozinfo`
from python.  
[mozinfo.py](https://github.com/mozilla/mozbase/blob/master/mozinfo/mozinfo.py)
is the only file contained is this package,
so if you need a single-file solution, you can just download or call
this file through the web.

The top level attributes (`os`, `version`, `bits`, `processor`) are
available as module globals:

    if mozinfo.os == 'win': ...

In addition, mozinfo exports a dictionary, `mozinfo.info`, that
contain these values.  mozinfo also exports:

- `choices`: a dictionary of possible values for os, bits, and
  processor
- `main`: the console_script entry point for mozinfo
- `unknown`: a singleton denoting a value that cannot be determined

`unknown` has the string representation `"UNKNOWN"`. unknown will evaluate
as `False` in python:

    if not mozinfo.os: ... # unknown!


# Command Line Usage

MozInfo comes with a command line, `mozinfo` which may be used to
diagnose one's current system.

Example output:

    os: linux
    version: Ubuntu 10.10
    bits: 32
    processor: x86

Three of these fields, os, bits, and processor, have a finite set of
choices.  You may display the value of these choices using 
`mozinfo --os`, `mozinfo --bits`, and `mozinfo --processor`. 
`mozinfo --help` documents command-line usage.