trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From zw...@apache.org
Subject [trafficserver] branch master updated: Runroot: Add a new doc on runroot for programs
Date Mon, 03 Dec 2018 17:13:53 GMT
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 <chitianhaoxp@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.


Mime
View raw message