// -*- C++ -*-
//
// This file was generated by CLI, a command line interface
// compiler for C++.
//

// Begin prologue.
//
#include <bdep/types-parsers.hxx>
//
// End prologue.

#include <bdep/default-options-files.hxx>

#include <map>

namespace bdep
{
  ::bdep::cli::usage_para
  print_bdep_default_options_files_usage (::std::ostream& os, ::bdep::cli::usage_para p)
  {
    CLI_POTENTIALLY_UNUSED (os);

    if (p != ::bdep::cli::usage_para::none)
      os << ::std::endl;

    os << "\033[1mSYNOPSIS\033[0m" << ::std::endl
       << ::std::endl
       << "\033[1mbdep\033[0m \033[4mcommand\033[0m [\033[4mmode-options\033[0m] ...\033[0m" << ::std::endl
       << ::std::endl
       << "\033[1mDESCRIPTION\033[0m" << ::std::endl
       << ::std::endl
       << "Instead of having a separate config file format for tool configuration, the" << ::std::endl
       << "\033[1mbuild2\033[0m toolchain uses \033[4mdefault options files\033[0m which contain the same options as" << ::std::endl
       << "what can be specified on the command line. The default options files are like" << ::std::endl
       << "options files that one can specify with \033[1m--options-file\033[0m (\033[1mbdep-common-options(1)\033[0m)" << ::std::endl
       << "except that they are loaded by default." << ::std::endl
       << ::std::endl
       << "The default options files are searched for in the \033[1m.build2/\033[0m and \033[1m.build2/local/\033[0m" << ::std::endl
       << "subdirectories of each outer directory beginning from the \033[4mstart directory\033[0m and" << ::std::endl
       << "until reaching either the home directory or the filesystem root directory (both" << ::std::endl
       << "excluding). Then in the \033[1m.build2/\033[0m subdirectory of the home directory and finally" << ::std::endl
       << "in the system directory (for example, \033[1m/etc/build2/\033[0m) if configured." << ::std::endl
       << ::std::endl
       << "Once the search is complete, the files are loaded in the reverse order, that" << ::std::endl
       << "is, beginning from the system directory (if any), followed by the home" << ::std::endl
       << "directory, ending with the start directory, and finishing off with the options" << ::std::endl
       << "specified on the command line.  In other words, the files are loaded from the" << ::std::endl
       << "more generic to the more specific with the command line options having the" << ::std::endl
       << "ability to override any values specified in the default options files." << ::std::endl
       << ::std::endl
       << "The start directory, the names of the default options files, and in which order" << ::std::endl
       << "they are loaded within each directory are determined by the \033[4mcommand\033[0m and" << ::std::endl
       << "potentially its \033[4mmode-options\033[0m. See each command's DEFAULT OPTIONS FILES section" << ::std::endl
       << "for details." << ::std::endl
       << ::std::endl
       << "If a default options file contains \033[1m--no-default-options\033[0m, then the search is" << ::std::endl
       << "stopped at the directory containing this file and no outer files are loaded. If" << ::std::endl
       << "this option is specified on the command line, then none of the default options" << ::std::endl
       << "files are searched for or loaded." << ::std::endl
       << ::std::endl
       << "An additional directory containing default options files can be specified with" << ::std::endl
       << "\033[1m--default-options\033[0m. If such a directory is a subdirectory of the start directory" << ::std::endl
       << "or is between the start directory and the end of the outer search, then its" << ::std::endl
       << "configuration files are loaded at the corresponding point in the directory" << ::std::endl
       << "hierarchy. Otherwise, they are loaded after the home directory." << ::std::endl
       << ::std::endl
       << "The presence of the \033[1m.git\033[0m filesystem entry causes the default options files in" << ::std::endl
       << "this directory and any of its subdirectories to be considered remote. Depending" << ::std::endl
       << "on the command, some security-sensitive options may be disallowed or trigger a" << ::std::endl
       << "prompt when specified in remote options files (in the current implementation" << ::std::endl
       << "this is the case even for files from the \033[1m.build2/local/\033[0m subdirectory since the" << ::std::endl
       << "mere location is not a sufficient ground to definitively conclude that the file" << ::std::endl
       << "is not remote; to be sure we would need to query the version control system)." << ::std::endl
       << "Note that additional default options files specified with \033[1m--default-options\033[0m are" << ::std::endl
       << "never considered remote." << ::std::endl
       << ::std::endl
       << "The order in which default options files are loaded is traced at the verbosity" << ::std::endl
       << "level 3 (\033[1m-V\033[0m option) or higher." << ::std::endl;

    p = ::bdep::cli::usage_para::text;

    return p;
  }
}

// Begin epilogue.
//
//
// End epilogue.