This is an automated email from the ASF dual-hosted git repository.
dragon pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 0adfc7a Runroot: Update doc
0adfc7a is described below
commit 0adfc7a0a565188bdbd4bbe06c6fa8187426af80
Author: Xavier Chi <chitianha...@gmail.com>
AuthorDate: Thu Sep 6 10:55:18 2018 -0500
Runroot: Update doc
---
doc/appendices/command-line/traffic_layout.en.rst | 137 ++++++++++++++--------
1 file changed, 85 insertions(+), 52 deletions(-)
diff --git a/doc/appendices/command-line/traffic_layout.en.rst
b/doc/appendices/command-line/traffic_layout.en.rst
index 6d1588e..a330c8d 100644
--- a/doc/appendices/command-line/traffic_layout.en.rst
+++ b/doc/appendices/command-line/traffic_layout.en.rst
@@ -24,6 +24,7 @@ traffic_layout
========
Synopsis
========
+
:program:`traffic_layout` SUBCOMMAND [OPTIONS]
===========
@@ -37,38 +38,89 @@ Environment
===========
Description
===========
+
Document for the special functionality of ``runroot`` inside
:program:`traffic_layout`. This feature
is for the setup of traffic server runroot. It will create a runtime sandbox
for any program of
traffic server to run under.
-Use :program:`traffic_layout` to create sandbox.
-Run any program using the sandbox with ``--run-root=/path/to/file`` or
``--run-root``.
+=====
+Usage
+=====
+
+First we need to create a runroot. It can be created simply by calling command
`init`. ::
+
+ traffic_layout init --path /path/to/runroot
-How it works
---------------
+A runroot will be created in ``/path/to/runroot``, available for other
programs to use.
+If the path is not specified, the current working directory will be used.
-#. Create a sandbox directory for programs to run under.
-#. Copy and symlink build time directories and files to the sandbox, allowing
users to modify freely.
-#. Emit a yaml file that defines layout structure for other programs to use
(relative path).
-#. Users are able to remove runroot and verify permission of the runroot.
+To run traffic_manager, for example, using the runroot, there are several ways:
+ #. ``/path/to/runroot/bin/traffic_manager``
+ #. ``traffic_manager --run-root=/path/to/runroot``
+ #. ``traffic_manager --run-root=/path/to/runroot/runroot_path.yml``
+ #. Set :envvar:`TS_RUNROOT` to ``/path/to/runroot`` and run
``traffic_manager``
+ #. Run ``traffic_manager`` with ``/path/to/runroot`` as current working
directory
+
+.. Note::
+
+ if none of the above is found as runroot, runroot will not be used and the
program will fall back to the default.
===========
Subcommands
===========
-``init``
- Use the current working directory or the specific path to create runroot.
- The path can be relative or set up in :envvar:`TS_RUNROOT`.
+init
+----
+Use the current working directory or the specific path to create runroot.
+The path can be absolute, relative or set up in :envvar:`TS_RUNROOT`.
+
+workflow:
+ #. Create a sandbox directory for programs to run under.
+ #. Copy and symlink build time directories and files to the sandbox,
allowing users to modify freely.
+ #. Emit a YAML file that defines layout structure for other programs to
use (relative path).
+
+Example: ::
+
+ traffic_layout init (--path /path/to/sandbox/) (--force) (--absolute)
(--copy-style=[HARD/SOFT/FULL]) (--layout=special_layout.yml)
+
+For the ``--layout=[<YAML file>]`` option, a custom layout can be used to
construct a runroot.
+Below is an example of customized yaml file (custom.yml) to construct. ::
+
+ prefix: ./runroot
+ exec_prefix: ./runroot
+ bindir: ./runroot/custom_bin
+ sbindir: ./runroot/custom_sbin
+ sysconfdir: ./runroot/custom_sysconf
+ datadir: ./runroot/custom_data
+ includedir: ./runroot/custom_include
+ libdir: ./runroot/custom_lib
+ libexecdir: ./runroot/custom_libexec
+ localstatedir: ./runroot/custom_localstate
+ runtimedir: ./runroot/custom_runtime
+ logdir: ./runroot/custom_log
+ cachedir: ./runroot/custom_cache
+
+If ``traffic_layout init --layout="custom.yml"`` is executed, a runroot
following the format above will be created.
+
+remove
+------
+Find the sandbox to remove in following order:
+ #. specified in --path as absolute or relative.
+ #. ENV variable: :envvar:`TS_RUNROOT`.
+ #. current working directory.
+ #. installed directory.
+
+Example: ::
+
+ traffic_layout remove (--path /path/to/sandbox/) (--force)
+
+verify
+------
+Verify the permission of the sandbox. The permission issues can be fixed with
``--fix`` option.
-``remove``
- Find the sandbox to remove in following order:
- #. specified in --path as absolute or relative.
- #. ENV variable: :envvar:`TS_RUNROOT`
- #. current working directory
- #. installed directory.
+Example: ::
-``verify``
- Verify the permission of the sandbox.
+ traffic_layout verify (--path /path/to/sandbox/) (--fix)
=======
Options
@@ -86,53 +138,34 @@ Options
Print usage information and exit.
+init
+----
.. option:: --force
Force init will create sandbox even if the directory is not empty.
- Force remove will remove a directory even if directory has no yaml file.
.. option:: --absolute
- Put directories in the yaml file in the form of absolute path when
creating.
-
-.. option:: --fix
-
- Fix the permission issues verify found. ``--fix`` requires root privilege
(sudo).
+ Put directories in the YAML file in the form of absolute paths when
creating.
.. option:: --copy-style=[HARD/SOFT/FULL]
- Specify the way of copying executables when creating runroot
+ Specify the way of copying executables when creating runroot.
+ HARD means hard link. SOFT means symlink. FULL means full copy.
.. option:: --layout=[<YAML file>]
- Use specific layout (providing YAML file) to create runroot
+ Use specific layout (providing YAML file) to create runroot.
-========
-Examples
-========
+remove
+------
+.. option:: `--force`
-Initialize the runroot. ::
+ Force remove will remove the directory even if it has no YAML file.
- traffic_layout init (--path /path/to/sandbox/) (--force) (--absolute)
(--copy-style=[HARD/SOFT/FULL])
+verify
+------
-Remove the runroot. ::
-
- traffic_layout remove (--path /path/to/sandbox/) (--force)
-
-Verify the runroot. ::
-
- traffic_layout verify (--path /path/to/sandbox/) (--fix)
-
-
-=========================
-Usage for other programs:
-=========================
-
-All programs can find the runroot to use in the following order
-
- #. specified in --run-root=/path/to/runroot (path needs to be absolute)
- #. :envvar:`TS_RUNROOT`
- #. current working directory
- #. installed directory
+.. option:: --fix
-if none of the above is found as runroot, runroot will not be used
+ Fix the permission issues verify found. ``--fix`` requires root privilege
(sudo).
