First doc draft

README.rst

@@ -1,4 +1,255 @@
 PlatformIO
 ==========
 
-An easy way to build code with different development platforms
+**Platformio** is a console tool to build code with different development
+platforms.
+
+You do not need to install any *IDE* or to compile any toolchains. *Platformio*
+has pre-built different development platforms for your favorite *OS* that
+including: compiler, debugger, flasher (for embedded) and many others useful
+tools.
+
+**Platformio** allows developer to compile single sources with different
+platforms with only one command ``platformio run``. This is due to
+``platformio.ini`` project's file where you can setup different environments
+with specific settings (platform, compiler or firmware uploading options,
+include pre-built framework and many more)
+
+Each platform consists of packages that are located in own repository.
+Due to ``platformio update`` command you will have up-to-date development
+instruments.
+
+**Platformio** is well suited for **embedded development**. It can:
+
+* Compile frameworks and libraries sources to static libraries
+* Build *ELF* (executable and linkable firmware)
+* Convert *ELF* to *HEX* or *BIN* file
+* Extract *EEPROM* data
+* Upload firmware to your device
+
+It has support for many popular embedded platforms like these:
+
+* ``atmelavr`` `Atmel AVR <http://en.wikipedia.org/wiki/Atmel_AVR>`_
+  (including `Arduino <http://www.arduino.cc>`_ based boards)
+* ``timsp430`` `TI MSP430 <http://www.ti.com/lsds/ti/microcontroller/16-bit_msp430/overview.page>`_
+  (including `MSP430 LaunchPads <http://www.ti.com/ww/en/launchpad/launchpads-msp430.html>`_)
+* ``titiva`` `TI TIVA C <http://www.ti.com/lsds/ti/microcontroller/tiva_arm_cortex/c_series/overview.page>`_
+  (including `TIVA C Series LaunchPads <http://www.ti.com/ww/en/launchpad/launchpads-connected.html>`_)
+
+
+See project `examples <https://github.com/ivankravets/platformio/tree/develop/examples>`_
+
+
+Python & OS Support
+-------------------
+
+**Platformio** written in `Python <https://www.python.org>`_ and works with
+versions 2.6 and 2.7 on Unix/Linux, OS X, and Windows.
+
+
+Quickstart
+----------
+
+.. code-block:: bash
+
+    # Install platformio
+    $ pip install platformio && pip install --egg scons
+
+    # Print availalbe development platforms for installing
+    $ platformio search
+
+    # Install new development platform
+    $ platformio install SomePlatform
+
+    # Initialize new platformio based project
+    $ cd /path/to/empty/directory
+    $ platformio init
+
+    # Process the project's environments
+    $ platformio run
+
+For more detailed information please follow to "Installation" and "User Guide"
+sections.
+
+
+Installation
+------------
+
+All commands below should be executed in
+`Command-line <http://en.wikipedia.org/wiki/Command-line_interface>`_
+application in your OS:
+
+* *Unix/Linux/OS X* this is *Terminal* application.
+* *Windows* this is
+  `Command Prompt <http://en.wikipedia.org/wiki/Command_Prompt>`_ (``cmd.exe``)
+  application.
+
+2. Check a ``python`` version:
+
+.. code-block:: bash
+
+    $ python --version
+
+Windows OS Users only:
+
+    * `Download Python <https://www.python.org/downloads/>`_ and install it.
+    * Add to PATH system variable ``;C:\Python27;C:\Python27\Scripts;`` and
+       reopen *Command Prompt* (``cmd.exe``) application. Please read this
+       article `How to set the path and environment variables in Windows
+       <http://www.computerhope.com/issues/ch000549.htm>`_.
+
+
+2. Check a ``pip`` tool for installing and managing Python packages:
+
+.. code-block:: bash
+
+    $ pip search platformio
+
+You should see short information about ``platformio`` package.
+
+If your computer does not recognize ``pip`` command, try to install it first
+using `these instructions <http://www.pip-installer.org/en/latest/installing.html>`_.
+
+3. Install a ``platformio`` and related packages:
+
+.. code-block:: bash
+
+    $ pip install platformio && pip install --egg scons
+
+For upgrading the ``platformio`` to new version please use this command:
+
+.. code-block:: bash
+
+    $ pip install -U platformio
+
+
+User Guide
+----------
+
+To print all available commands and options:
+
+.. code-block:: bash
+
+    $ platformio --help
+    $ platformio COMMAND --help
+
+
+``platformio search``
+~~~~~~~~~~~~~~~~~~~~~
+
+Search for available development platforms:
+
+.. code-block:: bash
+
+    $ platformio search "Query"
+
+You can leave search "Query" as empty. In this case ``platformio`` will print
+all available platforms.
+
+
+``platformio install``
+~~~~~~~~~~~~~~~~~~~~~~
+
+*Platformio* has pre-built development platforms with related packages. You
+can install one of them:
+
+.. code-block:: bash
+
+    $ platformio install SomePlatform
+    $ platformio install SomePlatform --with-package=PackageName
+    $ platformio install SomePlatform --without-package=PackageName
+
+
+``platformio list``
+~~~~~~~~~~~~~~~~~~~
+
+To list installed platforms:
+
+.. code-block:: bash
+
+    $ platformio list
+
+
+``platformio show``
+~~~~~~~~~~~~~~~~~~~
+
+To show details about an installed platform:
+
+.. code-block:: bash
+
+    $ platformio show SomePlatform
+
+
+``platformio uninstall``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To uninstall platform:
+
+.. code-block:: bash
+
+    $ platformio uninstall SomePlatform
+
+
+``platformio init``
+~~~~~~~~~~~~~~~~~~~
+
+Initialize new platformio based project.
+
+.. code-block:: bash
+
+    # Change directory to future project
+    $ cd /path/to/empty/directory
+    $ platformio init
+
+After this command ``platformio`` will create:
+
+* ``.pioenvs`` - a temporary working directory.
+* ``libs`` - a directory for project specific libraries. Platformio will
+  compile their to static libraries and link to executable file
+* ``src`` - a source directory. Put code here.
+* ``platformio.ini`` - a configuration file for project
+
+
+``platformio run``
+~~~~~~~~~~~~~~~~~~
+
+Process the project's environments defined in ``platformio.ini`` file:
+
+.. code-block:: bash
+
+    $ platformio run
+
+Process specific environments:
+
+.. code-block:: bash
+
+    $ platformio run -e myenv1 -e myenv2
+
+Process specific target:
+
+.. code-block:: bash
+
+    $ platformio run -t clean
+    $ platformio run -t upload
+
+Mix environments and targets:
+
+.. code-block:: bash
+
+    $ platformio run -e myembeddeddevice -t upload
+
+
+Questions & Bugs
+----------------
+
+Please use the
+`issue tracker <https://github.com/ivankravets/platformio/issues>`_
+to ask questions or report bugs.
+
+
+Licence
+-------
+
+Copyright (C) 2014 Ivan Kravets
+
+Licenced under the MIT Licence.