You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by zw...@apache.org on 2018/12/03 17:13:53 UTC
[trafficserver] branch master updated: Runroot: Add a new doc on
runroot for programs
This is an automated email from the ASF dual-hosted git repository.
zwoop 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 1ef8b2a Runroot: Add a new doc on runroot for programs
1ef8b2a is described below
commit 1ef8b2ad64f248db1a31d1eebaed4b011a4669b5
Author: Xavier Chi <ch...@gmail.com>
AuthorDate: Fri Nov 30 15:13:30 2018 -0600
Runroot: Add a new doc on runroot for programs
---
doc/appendices/command-line/traffic_layout.en.rst | 12 +--
doc/developer-guide/index.en.rst | 3 +-
doc/developer-guide/layout/index.en.rst | 28 +++++++
doc/developer-guide/layout/runroot.en.rst | 99 +++++++++++++++++++++++
src/traffic_layout/README | 2 +-
5 files changed, 133 insertions(+), 11 deletions(-)
diff --git a/doc/appendices/command-line/traffic_layout.en.rst b/doc/appendices/command-line/traffic_layout.en.rst
index 0898443..443c823 100644
--- a/doc/appendices/command-line/traffic_layout.en.rst
+++ b/doc/appendices/command-line/traffic_layout.en.rst
@@ -21,13 +21,11 @@
traffic_layout
**************
-========
Synopsis
========
:program:`traffic_layout` SUBCOMMAND [OPTIONS]
-===========
Environment
===========
@@ -35,15 +33,13 @@ Environment
The path to the run root file. It has the same effect as the command line option :option:`--run-root`.
-===========
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.
+Document for the :program:`traffic_layout` about the ``runroot``. 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.
+For details about runroot for programs, please refer to ``developer-guide/layout/runroot.en``.
-=====
Usage
=====
@@ -65,7 +61,6 @@ For example, to run traffic_manager, using the runroot, there are several ways:
if none of the above is found as runroot, runroot will not be used and the program will fall back to the default.
-===========
Subcommands
===========
@@ -134,7 +129,6 @@ Example: ::
``--fix`` may perform permission changes on the system configuration files. With normally created runroot with default layout,
there is no such issue since traffic server related files are filtered.
-=======
Options
=======
diff --git a/doc/developer-guide/index.en.rst b/doc/developer-guide/index.en.rst
index 688203c..5deda01 100644
--- a/doc/developer-guide/index.en.rst
+++ b/doc/developer-guide/index.en.rst
@@ -54,4 +54,5 @@ duplicate bugs is encouraged, but not required.
documentation/index.en
host-resolution-proposal.en
client-session-architecture.en
- core-architecture/index.en
\ No newline at end of file
+ core-architecture/index.en
+ layout/index.en
\ No newline at end of file
diff --git a/doc/developer-guide/layout/index.en.rst b/doc/developer-guide/layout/index.en.rst
new file mode 100644
index 0000000..4e17aeb
--- /dev/null
+++ b/doc/developer-guide/layout/index.en.rst
@@ -0,0 +1,28 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+.. include:: ../../common.defs
+
+.. _layout:
+
+Layout
+******
+
+.. toctree::
+ :maxdepth: 2
+
+ runroot.en
diff --git a/doc/developer-guide/layout/runroot.en.rst b/doc/developer-guide/layout/runroot.en.rst
new file mode 100644
index 0000000..7b9c049
--- /dev/null
+++ b/doc/developer-guide/layout/runroot.en.rst
@@ -0,0 +1,99 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+.. include:: ../../common.defs
+
+.. _runroot:
+
+Runroot
+*******
+
+Preface
+=======
+
+Runroot is a powerful feature to detect and define layout at runtime. This document helps to guide through how runroot works.
+For management and setup of runroots, please refer to ``appendices/command-line/traffic_layout.en``
+
+Why do we need runroot
+======================
+
+Runroot is a replacing approach for the previous ``TS_ROOT`` logic. ``TS_ROOT`` is based on replacing a compile-time package install root location.
+Layouts for many systems have data location that are absolute paths that are defined without ``$PREFIX`` variable. So, the current logic is difficult to follow
+and not consistent between trafficserver programs. Furthermore, it is not easy to modify subdirectory locations.
+
+So, we have the runroot which makes ATS easier to use, develop and deploy.
+
+Main logic
+==========
+
+Everything in runroot will go through the class:`Layout` class and all the layout is defined by a single YAML file: ``runroot.yaml``.
+
+Work flow:
+
+#. Command line option ``--run-root``
+#. ``$TS_RUNROOT`` Environment variable
+#. Look in current directory and look up N (default 4) directories for ``runroot.yaml``
+#. Look in executable directory and look up N directories for ``runroot.yaml``.
+#. ``$TS_ROOT`` Environment Variable
+#. Compiler defaults in layout class
+
+Right now, the following programs are integrated with the runroot logic:
+**traffic_server**, **traffic_manager**, **traffic_ctl**, **traffic_layout**, **traffic_crashlog**, **traffic_logcat**, **traffic_logstat**.
+
+The YAML file
+=============
+
+The runroot file (runroot.yaml) can be placed at any location in the filesystem and still be used to define the locations for required |TS| files.
+So we can run traffic_server, for example, by ``traffic_server --run-root=/some/directory/runroot.yaml``.
+
+Below is an example of ``runroot.yaml``.
+
+.. code-block:: yaml
+
+ prefix: /home/myname/runroot
+ exec_prefix: /home/myname/runroot
+ bindir: /home/myname/runroot/bin
+ sbindir: /home/myname/runroot/bin
+ sysconfdir: /etc/trafficserver
+ datadir: /home/myname/runroot/share/trafficserver
+ includedir: /home/myname/runroot/include
+ libdir: /home/myname/runroot/lib
+ libexecdir: /libexec/trafficserver
+ localstatedir: /var
+ runtimedir: /var/trafficserver
+ logdir: /home/myname/runroot/logdir
+ cachedir: /var/trafficserver
+
+The path can be both relative or absolute. We can define wherever we want the directory to be. All the items we need to
+put into ``runroot.yaml`` are shown above and the entries can be optional. For example, if sysconfdir is not in the file, runroot will
+set the sysconfidir, at runtime, to be the default built time sysconfdir concatenated with the prefix.
+
+Runroot management
+==================
+
+We can create, remove and verify runroot using ``traffic_layout`` program. It is fully documented in the appendices.
+
+Guide for development
+=====================
+
+Basic runroot functionality is handled in ``runroot.cc`` and ``runroot.h`` of ``lib/tscore``. ``runroot_handler()`` and ``argparser_runroot_handler()``
+are the main methods for the runroot. The ``Layout`` class will then get the global variable from ``runroot.cc`` to set up the directories properly.
+
+Issue or bug
+============
+
+This functionality should be stable and if there is any issue or bug, please report it on the GitHub and @chitianhao.
diff --git a/src/traffic_layout/README b/src/traffic_layout/README
index 0c65d61..c7b88b8 100644
--- a/src/traffic_layout/README
+++ b/src/traffic_layout/README
@@ -2,4 +2,4 @@ traffic_layout is a easy-to-use tool to:
- show the location of various installation paths and resources.
- deal with traffic server runroot.
-For detailed information, please refer to doc/appendices/command-line/traffic_layout.en.rst.
+For detailed information, please refer to doc/appendices/command-line/traffic_layout.en and doc/developer-guide/layout/runroot.en.