Getting started
---------------

releng-tool is made on Python. This document will outline package definitions,
scripts and more which are most likely Python scripts, and in turn will be
invoked/processed by the releng-tool. While releng-tool supports running on
various host systems (e.g. Linux, OS X, Windows, etc.), this guide will
primarily show examples following a Unix-styled file system.

The following will provide a very simple script-based project solution to get
started. This example will make a project with two packages, setup a dependency
between them and setup scripts to help show a developer how packages are
processed. If there is no desire to make a simple project example, one may
venture to the `actually getting started`_ section.

To start, make a new folder for the project, two sample packages and move into
the root folder:

.. code-block:: shell-session

   $ mkdir -p my-project/package/libx
   $ mkdir -p my-project/package/liby
   $ cd my-project/

Inside the ``libx`` project, the package definition and script-based files will
be created. First, build the package definition ``my-project/libx/libx`` with
the following content:

.. code-block:: python

   #!/usr/bin/env python
   # -*- coding: utf-8 -*-

   LIBX_VERSION='1.0.0'

Next, create a build script for the ``libx`` project
``my-project/libx/libx-build`` with the following content:

.. code-block:: python

   #!/usr/bin/env python
   # -*- coding: utf-8 -*-

   print('invoked libx package build stage')

This is a very simple script-based package (all package options explained later
in this document). Repeat the same steps for the ``liby`` package with the file
``my-project/liby/liby`` containing:

.. code-block:: python

   #!/usr/bin/env python
   # -*- coding: utf-8 -*-

   LIBY_DEPENDENCIES=['libx']
   LIBY_VERSION='2.1.0'

And ``my-project/liby/libx-build`` containing:

.. code-block:: python

   #!/usr/bin/env python
   # -*- coding: utf-8 -*-

   print('invoked liby package build stage')

One difference with this package is the definition of ``LIBY_DEPENDENCIES``,
which tells releng-tool to ensure that ``libx`` package is processed before
``liby``.

With this minimal set of packages, the project's releng-tool configuration can
now be created. At the root of the project folder, create a ``releng``
configuration file with the following contents:

.. code-block:: python

   #!/usr/bin/env python
   # -*- coding: utf-8 -*-

   packages = [
       'libx',
       'liby',
   ]

This sample project should be ready for a spin. While in the ``my-project``
folder, invoke ``releng-tool``:

.. code-block:: shell-session

   $ releng-tool
   patching libx...
   configuring libx...
   building libx...
   invoked libx package build stage
   installing libx...
   patching liby...
   configuring liby...
   building liby...
   invoked liby package build stage
   installing liby...
   generating license information...
   (success) completed (0:00:00)

This above output shows that the ``libx`` package's stage are invoke followed by
``liby`` package's stages. For the build stage in each package, each respective
package script has been invoked. While this example only prints a message, more
elaborate scripts can be made to handle a package's source to build.

To clean the project, a ``releng-tool clean`` request can be invoked:

.. code-block:: shell-session

   $ releng-tool clean

Now the project is in a state again to perform a fresh build. This concludes the
initial getting started example. Feel free to remove the example project and
prepare for steps to make a real releng-tool project.
