From 47edf0a5d5e2e5fb1b758ec801d094cb9e23f9b9 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Thu, 12 Jun 2014 21:18:11 +0300 Subject: [PATCH] First doc draft --- README.rst | 253 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 252 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index a7b72c52..476fd9c6 100644 --- a/README.rst +++ b/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 `_ + (including `Arduino `_ based boards) +* ``timsp430`` `TI MSP430 `_ + (including `MSP430 LaunchPads `_) +* ``titiva`` `TI TIVA C `_ + (including `TIVA C Series LaunchPads `_) + + +See project `examples `_ + + +Python & OS Support +------------------- + +**Platformio** written in `Python `_ 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 `_ +application in your OS: + +* *Unix/Linux/OS X* this is *Terminal* application. +* *Windows* this is + `Command Prompt `_ (``cmd.exe``) + application. + +2. Check a ``python`` version: + +.. code-block:: bash + + $ python --version + +Windows OS Users only: + + * `Download Python `_ 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 + `_. + + +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 `_. + +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 `_ +to ask questions or report bugs. + + +Licence +------- + +Copyright (C) 2014 Ivan Kravets + +Licenced under the MIT Licence.