install
======================================

  ::

    usage: /Users/andrew/env/arm/bin/arm install [-h] [-U] [-n] (-r REQUIREMENTS | role_or_module)
    
    install playbook role
    
    positional arguments:
      role_or_module        specifier of role or module to install locally
    
    optional arguments:
      -h, --help            show this help message and exit
      -U, --upgrade
      -n, --no-dependencies
      -r REQUIREMENTS, --requirements REQUIREMENTS    install from requirements file

      
For specifier syntax, see :doc:`specifiers`.

depedency installation
-------------------------------------

The Ansible Role Manager uses the information contained with a role's ``meta/main.yml``. If there are no
dependencies, it will be defined like::

    ---
    
    # file: ROLE/meta/main.yml
    
    dependencies: [ ]
    
    
If there are dependencies, Ansible will run them first::

    ---
    
    # file: ROLE/meta/main.yml
    
    dependencies:
        - { role: my_local_role }
        
If you install a custom role using ARM, it will try to fetch
and install these roles as well. If the role is located in Ansible
Galaxy, you can specify it with no additional fields::

    ---
    
    # file: ROLE/meta/main.yml
    
    dependencies:
        - { role: repo.owner }
        
For dependent roles that are in other locations, add a ``src`` field, using the same :doc:`specifiers` as before::

    ---
    
    # file: ROLE/meta/main.yml
    
    dependencies:
        - { role: my_local_role, src:git+https://git.myproject.org/SomeOwner/SomeRole }
        
.. WARNING::
        
    In order for Ansible to find the dependent role, the installed name needs to
    match the role name. The previous example has this error and can be fixed by 
    (1) ``my_local_role`` should be changed to ``SomeOwner.SomeRole`` or (2) add
    ``#alias=mycustomrole`` to the source path::

        ---
        
        # file: ROLE/meta/main.yml
        
        dependencies:
            - { role: my_local_role, src:git+https://git.myproject.org/SomeOwner/SomeRole#alias=my_local_role }
            - { role: SomeOwner.SomeRole, src:git+https://git.myproject.org/SomeOwner/SomeRole }
            
    If these don't match, ARM will warn but not throw an error. Ansible, however, will not be able
    to execute properly.

   
requirements file format
-------------------------------------

Use a file where each line is a new role (or module) that should be installed using the same :doc:`specifiers`
as from the ``arm install`` command line. Before installing any role, ARM will download all items in the list
plus all their dependencies. If there is overlap, ARM will only install each item once.

After manually installing roles and modules, the requirements file can be generated by using :doc:`freeze`.