.. _usage: ===== Usage ===== General Options =============== * ``-h``, ``--help``: Show a help message for the user. * ``-q``, ``--quiet``: Suppress the progress bars in the output. Logging options =============== * ``-l``, ``--log-level=LEVEL``: Set the verbosity level of the internal logging system. Available options: ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL``, ``DEBUG``. * ``--log-name=LOGGER``: Filter by the logger name that you want to follow up. It's useful for developers or users reporting bugs. * ``--log-file=FILE``: A path to save the all the log information generated by curdling to a file. Useful logging options to use when reporting bugs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you find anything wrong on curdling, it's highly appreciated if you take your time to contribute to the project and report the issue. It's strongly suggested to upload the log data generated by curdling using the ``--log-level`` and ``--log-name`` options. E.g.:: $ curd --log-level=DEBUG --log-name=curdling install sure curd install ============ Find, build and install packages from remote sources into your environment:: $ curd install [-h] [-r REQUIREMENTS] [-i INDEX] [-c CURDLING_INDEX] [-u] [-f] [REQUIREMENT [REQUIREMENT ...]] Declaring requirements ~~~~~~~~~~~~~~~~~~~~~~ **Command line** You can inform as many requirements as you want in the command line:: $ curd install flask forbiddenfruit sure All the packages and its dependencies are going to be installed by the command above. **requirements.txt** * ``-r``, ``--requirements=FILE``: File containing all the requirements the user wants to install. This option can be repeated as many times as needed and needs to point to a readable file. .. _declaring-requirements: Syntax for declaring requirements --------------------------------- * Each line should contain a separate requirement * Each requirement must be specified as either a URL or a `pkg_resources `_ requirement:: requirement ::= project_name versionspec? extras? versionspec ::= '(' versionlist? ')' versionlist ::= comparison version (',' comparison version)* comparison ::= '<' | '<=' | '!=' | '==' | '>=' | '>' extras ::= '[' extralist? ']' extralist ::= identifier (',' identifier)* project_name ::= identifier identifier ::= [-A-Za-z0-9_]+ version ::= [-A-Za-z0-9_.]+ VCS support ----------- The install command will understand URLs for the most used Version Control Systems we currently have in the market, like ``git``, ``svn``, ``bzr`` and ``hg``. To install a package hosted in a *VCS*, the user needs to inform which VCS is being requested, using the prefix ``vcs+``. E.g.:: $ curd install git+http://github.com/clarete/forbiddenfruit.git Everything after the ``vcs+`` prefix will be forward to the respective command line tool that **must** be installed before requesting any *VCS* links for curdling. Install specific revisions ~~~~~~~~~~~~~~~~~~~~~~~~~~ Curdling also supports installing a specific revision of the package available in the VCS. To inform the revision, use ``@`` and the revision ID, E.g.:: $ curd install git+http://github.com/clarete/forbiddenfruit.git@aeebca4cae6c656046c7223b418faf463d4c68ef It works for all currently supported VCS systems. Precedence when declaring requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Requirements specified directly by the user from either the command line or from a requirements file are special. They're called *Primary Requirements*. The ones found by curdling during the :ref:`retrieve-and-build` process are called *Secondary Requirements*. If a package is requested more than once, curdling will **always** prefer the *Primary Requirements*. Declaring PyPi repositories ~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ``-i``, ``--index=URL``: Set which *PyPi* external repositories the installer should use. Can be repeated as many times as needed. Default repository ------------------ If no repositories are specified, curdling will use the official *PyPi* URL: **http://pypi.python.org/simple**. However, if one single ``-i`` parameter is declared, the default address is removed from the repository list. For example:: $ curd install -i http://localhost/simple flask Will only try to look for the requirements in the address informed in the ``-i`` parameter. The default URL **will not** be used in this case. If the user wants to use a custom repository and the default one together, both addresses have to be manually specified:: $ curd install -i http://localhost/simple -i http://pypi.python.org/simple flask So the user can choose which repository the lookup will happen first. Declaring Curdling repositories ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ``-c``, ``--curdling-index=CURDLING_INDEX``: Set which *Curdling* external repositories the installer should use. Can be repeated as many times as needed. Precedence over *PyPi* repositories. The installer will try to retrieve binary files from any ``curdling`` servers specified before accessing the ones declared using the ``-i`` parameter. Read more about how caching works on curdling in the :ref:`distributed-cache` section. curd uninstall ============== Uninstall packages from your environment. General command:: $ curd uninstall [-h] [-r REQUIREMENTS] [PKG [PKG ...]] * ``-r``, ``--requirements=FILE``: File containing all the requirements the user wants to uninstall. This option can be repeated as many times as needed and needs to point to a readable file. * ``PKG`` is a requirement in the same format as described in the section :ref:`declaring-requirements`.