.. This file is part of everyapp.bootstrap.
.. Copyright (C) 2010 Krys Lawrence
..
.. everyapp.bootstrap is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by the
.. Free Software Foundation, either version 3 of the License, or (at your
.. option) any later version.
..
.. everyapp.bootstrap is distributed in the hope that it will be useful, but
.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.. or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
.. more details.
..
.. You should have received a copy of the GNU General Public License along with
.. this program.  If not, see <http://www.gnu.org/licenses/>.

.. index:: mkbootstrap, usage; mkbootstrap
.. _mkbootstrap:

mkbootstrap
===========

.. only:: not man

   This |file| provides detailed usage information for the |mkbootstrap|
   command.

.. index::
   pair: mkbootstrap; synopsis

Synopsis
--------

|mkbootstrap| [OPTIONS]

.. index::
   pair: mkbootstrap; description

Description
-----------

|mkbootstrap| is the command-line utility that generates a virtualenv_
bootstrap script and configuration file for a project.  It is also used to
upgrade the bootstrap script whenever newer versions of *everyapp.bootstrap*
are installed.

.. index::
   pair: mkbootstrap; options

Options
-------

|mkbootstrap| accepts several command-line options that are described below.
The basic options are the ones that are used most commonly.  The advanced
options are intended for special situations where more advanced customization
is required.

.. only:: latex

   .. WARNING:: The long versions of the options below should be prefixed by
      two hyphens (``--``) not one.  The PDF version of this documentation does
      not render the double hyphens correctly.

Basic Options
^^^^^^^^^^^^^

The following are the most commonly used options of customizing the behaviour
of |mkbootstrap|.

.. option:: --version

   This option tells |mkbootstrap| to just show program's version and copyright
   information, and then exit.

.. option:: -h, --help

   This option tells |mkbootstrap| to just show program usage information and
   then exit.  It lists all the options described here along with simple
   descriptions.

.. option:: -s FILE_NAME, --script-name FILE_NAME

   Use this option to give the generated bootstrap script a different name or
   location. The default is |bootstrap.py|.

   .. NOTE:: By default, the name of the generated configuration file will also
      change when this option is given.  Use the |-c| option to override this
      behaviour.

.. option:: -c FILE_NAME, --config-name FILE_NAME

   Use this option to give the generated configuration file a different name or
   location.  The default is the same as script name but with a ``.cfg``
   extension.

   .. NOTE:: If you specify a custom location for the configuration file, you
      will need to always specify it when re-generating/upgrading the bootstrap
      script.

.. option:: -e, --etc

   Use this option to generate the configuration file in an |etc| sub-directory
   instead of in the current directory.  This is useful if you want to keep all
   your project's configuration files in a common place and not in the
   project's root directory.  |etc| is a common convention on |POSIX| systems.

   .. NOTE:: You can combine this option with the |-c| option to customize the
      configuration file name, but then you should not specify a custom
      location with that option.

.. option:: -n, --no-customization

   This option tells tells |mkbootstrap| to only generate a plain vanilla
   virtualenv_ bootstrap script, without any customizations or configuration
   file.  The generated bootstrap script is exactly the same as if
   *everyapp.bootstrap* had never even been installed.

   This option makes it easy to use *everyapp.bootstrap* as simply a
   virtualenv_ script generator without adding any extra fanciness.  This is
   arguably a bit easier than creating your own bootstrap script generator as
   described in the virtualenv_ documentation.

   .. NOTE:: If you use this option, then the available command-line options of
      the generated bootstrap script will only be the original ones and not
      include the customized ones provided by this package.

Advanced Options
^^^^^^^^^^^^^^^^

The options listed here are meant for more advanced customization needs.  They
allow you to fully customize the generated bootstrap script and configuration
file.

.. option:: -S FILE_NAME, --customize-script FILE_NAME

   Normally, |mkbootstrap| includes it's own virtualenv_ customization code in
   the generated bootstrap script to provide it's additional functionality.
   You can use this option to have your own virtualenv_ customization code
   included instead.  Just put your customization code in a file and reference
   it with this option.  This is arguably a bit easier than creating your own
   bootstrap script generator as described in the virtualenv_ documentation.

   Additionally, if you include the ``$DEFAULT_CONFIG_FILE_NAME$`` token in
   your code, it will be automatically replaced with the name of the
   configuration file.

   .. SEEALSO:: The `virtualenv documentation`_ on creating custom bootstrap
      scripts for more information on what to put into your customization file.

.. option:: -C FILE_NAME, --default-config FILE_NAME

   Normally, |mkbootstrap| generates the configuration file from a built-in
   template.  You can use this option, however, to use your own default
   configuration file instead.

   .. NOTE:: A new configuration file will not be generated if an existing one
      is already found.

.. index::
   pair: mkbootstrap; examples

Examples
--------

The simplest and most common usage is to just run it in your project's root
directory.  For example::

  cd /path/to/my/project/root
  mkbootstrap

This will generate a virtualenv_ bootstrap script called |bootstrap.py| and a
configuration file called |bootstrap.cfg| in |/path/to/my/project/root| (i.e.
the current directory).

Here are other examples::

  mkboostrap -s bootdev.py

This will generate the files |bootdev.py| and |bootdev.cfg| in the current
directory.

::

  mkboostrap -c venv.cfg

This will generate the files |bootstrap.py| and |venv.cfg| in the current
directory.

::

  cd /path/to/my/project
  mkbootstrap -e

This will generate the configuration file as
|/path/to/my/project/etc/bootstrap.cfg|.

.. .. index::
..    pair: mkbootstrap; output
..
.. Output
.. ------
..
.. (None.)

.. index::
   pair: mkbootstrap; files
   pair: mkbootstrap; directories

Files and Directories
---------------------

|bootstrap.py|
  The generated enhanced virtualenv_ bootstrap script
|bootstrap.cfg|
  The configuration file for |bootstrap.py|

.. .. index::
..    pair: mkbootstrap; environment variables
..
.. Environment Variables
.. ---------------------
..
.. (None.)

.. index::
   pair: mkbootstrap; exit status

Exit Status
-----------

0
  Successful program execution
1
  Operational error
2
  Error parsing command-line options

.. .. index::
..    pair: mkbootstrap; notes
..
.. Notes
.. -----
..
.. (None.)

.. .. index::
..    pair: mkbootstrap; history
..
.. History
.. -------
..
.. (None.)

.. bottom

.. .. index::
..    pair: mkbootstrap; acknowledgements
..
.. Acknowledgements
.. ----------------
..
.. (See THANKS.txt.)
