testing/mozbase/docs/mozinfo.rst

   1 :mod:`mozinfo` --- Get system information
   2 =========================================
   3
   4 Throughout `mozmill <https://developer.mozilla.org/en/Mozmill>`_
   5 and other Mozilla python code, checking the underlying
   6 platform is done in many different ways.  The various checks needed
   7 lead to a lot of copy+pasting, leaving the reader to wonder....is this
   8 specific check necessary for (e.g.) an operating system?  Because
   9 information is not consolidated, checks are not done consistently, nor
  10 is it defined what we are checking for.
  11
  12 `mozinfo <https://github.com/mozilla/mozbase/tree/master/mozinfo>`_
  13 proposes to solve this problem.  mozinfo is a bridge interface,
  14 making the underlying (complex) plethora of OS and architecture
  15 combinations conform to a subset of values of relevance to
  16 Mozilla software. The current implementation exposes relevant keys and
  17 values such as: ``os``, ``version``, ``bits``, and ``processor``.  Additionally, the
  18 service pack in use is available on the windows platform.
  19
  20
  21 API Usage
  22 ---------
  23
  24 mozinfo is a python package.  Downloading the software and running
  25 ``python setup.py develop`` will allow you to do ``import mozinfo``
  26 from python.
  27 `mozinfo.py <https://raw.github.com/mozilla/mozbase/master/mozinfo/mozinfo/mozinfo.py>`_
  28 is the only file contained is this package,
  29 so if you need a single-file solution, you can just download or call
  30 this file through the web.
  31
  32 The top level attributes (``os``, ``version``, ``bits``, ``processor``) are
  33 available as module globals::
  34
  35     if mozinfo.os == 'win': ...
  36
  37 In addition, mozinfo exports a dictionary, ``mozinfo.info``, that
  38 contain these values.  mozinfo also exports:
  39
  40 - ``choices``: a dictionary of possible values for os, bits, and
  41   processor
  42 - ``main``: the console_script entry point for mozinfo
  43 - ``unknown``: a singleton denoting a value that cannot be determined
  44
  45 ``unknown`` has the string representation ``"UNKNOWN"``.
  46 ``unknown`` will evaluate as ``False`` in python::
  47
  48     if not mozinfo.os: ... # unknown!
  49
  50
  51 Command Line Usage
  52 ------------------
  53
  54 mozinfo comes with a command line program, ``mozinfo`` which may be used to
  55 diagnose one's current system.
  56
  57 Example output::
  58
  59     os: linux
  60     version: Ubuntu 10.10
  61     bits: 32
  62     processor: x86
  63
  64 Three of these fields, os, bits, and processor, have a finite set of
  65 choices.  You may display the value of these choices using
  66 ``mozinfo --os``, ``mozinfo --bits``, and ``mozinfo --processor``.
  67 ``mozinfo --help`` documents command-line usage.
  68
  69
  70 .. automodule:: mozinfo
  71    :members: