=======================
Setup and running tests
=======================

If you plan on hacking on psutil this is what you're supposed to do first:

- clone the GIT repository::

  $ git clone git@github.com:giampaolo/psutil.git

- install system deps (see `install instructions <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`__).

- install development deps; these are useful for running tests (e.g. mock,
  unittest2), building doc (e.g. sphinx), running linters (flake8), etc. ::

  $ make setup-dev-env

- bear in mind that ``make`` (see `Makefile <https://github.com/giampaolo/psutil/blob/master/Makefile>`_)
  is the designated tool to run tests, build, install etc. and that it is also
  available on Windows
  (see `make.bat <https://github.com/giampaolo/psutil/blob/master/make.bat>`_).
- bear in mind that both psutil (``make install``) and any other lib
  (``make setup-dev-env``) is installed as a limited user
  (``pip install --user ...``), so develop as such (don't use root).
- (UNIX only) run ``make install-git-hooks``: this will reject your commits
  if python code is not PEP8 compliant.
- run ``make test`` to run tests.

============
Coding style
============

- python code strictly follows `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_
  styling guides and this is enforced by ``make install-git-hooks``.
- C code strictly follows `PEP 7 <https://www.python.org/dev/peps/pep-0007/>`_
  styling guides.

========
Makefile
========

Some useful make commands::

  $ make install        # install
  $ make setup-dev-env  # install useful dev libs (pyflakes, unittest2, etc.)
  $ make test           # run all tests
  $ make test-memleaks  # run memory leak tests
  $ make coverage       # run test coverage
  $ make flake8         # run PEP8 linter

====================
Adding a new feature
====================

Usually the files involved when adding a new functionality are:

.. code-block:: plain

    psutil/__init__.py                   # main psutil namespace
    psutil/_ps{platform}.py              # python platform wrapper
    psutil/_psutil_{platform}.c          # C platform extension
    psutil/_psutil_{platform}.h          # C header file
    psutil/tests/test_process|system.py  # main test suite
    psutil/tests/test_{platform}.py      # platform specific test suite

Typical process occurring when adding a new functionality (API):

- define the new function in ``psutil/__init__.py``.
- write the platform specific implementation in ``psutil/_ps{platform}.py``
  (e.g. ``psutil/_pslinux.py``).
- if the change requires C, write the C implementation in
  ``psutil/_psutil_{platform}.c`` (e.g. ``psutil/_psutil_linux.c``).
- write a generic test in ``psutil/tests/test_system.py`` or
  ``psutil/tests/test_process.py``.
- if possible, write a platform specific test in
  ``psutil/tests/test_{platform}.py`` (e.g. ``test_linux.py``).
  This usually means testing the return value of the new feature against
  a system CLI tool.
- update doc in ``doc/index.py``.
- update ``HISTORY.rst``.
- update ``README.rst`` (if necessary).
- make a pull request.

======================
Continuous integration
======================

All of the services listed below are automatically run on ``git push``.

Unit tests
----------

Tests are automatically run for every GIT push on **Linux**, **OSX** and
**Windows** by using:

- `Travis <https://travis-ci.org/giampaolo/psutil>`_ (Linux, OSX)
- `Appveyor <https://ci.appveyor.com/project/giampaolo/psutil>`_ (Windows)

Test files controlling these are
`.travis.yml <https://github.com/giampaolo/psutil/blob/master/.travis.yml>`_
and
`appveyor.yml <https://github.com/giampaolo/psutil/blob/master/appveyor.yml>`_.
Both services run psutil test suite against all supported python version
(2.6 - 3.5).
Two icons in the home page (README) always show the build status:

.. image:: https://api.travis-ci.org/giampaolo/psutil.png?branch=master
    :target: https://travis-ci.org/giampaolo/psutil
    :alt: Linux tests (Travis)

.. image:: https://ci.appveyor.com/api/projects/status/qdwvw7v1t915ywr5/branch/master?svg=true
    :target: https://ci.appveyor.com/project/giampaolo/psutil
    :alt: Windows tests (Appveyor)

OSX, FreeBSD and Solaris are currently tested manually (sigh!).

Test coverage
-------------

Test coverage is provided by `coveralls.io <https://coveralls.io/github/giampaolo/psutil>`_,
it is controlled via `.travis.yml <https://github.com/giampaolo/psutil/blob/master/.travis.yml>`_
and it is updated on every git push.
An icon in the home page (README) always shows the last coverage percentage:

.. image:: https://coveralls.io/repos/giampaolo/psutil/badge.svg?branch=master&service=github
    :target: https://coveralls.io/github/giampaolo/psutil?branch=master
    :alt: Test coverage (coverall.io)

=============
Documentation
=============

- doc source code is written in a single file: `/docs/index.rst <https://raw.githubusercontent.com/giampaolo/psutil/master/docs/index.rst>`_.
- it uses `RsT syntax <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
  and it's built with `sphinx <http://sphinx-doc.org/>`_.
- doc can be built with ``make setup-dev-env; cd docs; make html``.
- public doc is hosted on http://pythonhosted.org/psutil/.
- it is uploaded on every new release with ``make upload-doc``.

=======================
Releasing a new version
=======================

These are notes for myself (Giampaolo):

- ``make release``
- post announce (``make print-announce``) on psutil and python-announce mailing
  lists, twitter, g+, blog.

=============
FreeBSD notes
=============

- setup:

.. code-block:: bash

  $ pkg install python python3 gcc git vim screen bash
  $ chsh -s /usr/local/bin/bash user  # set bash as default shell

- ``/usr/src`` contains the source codes for all installed CLI tools (grep in it).