Add README
Captured steps for installing application local error yamls
and generating elog-errors.hpp for local repository build
Logging REST API is captured in a README document of dbus repo.
Change-Id: I47d556372c0696f47988df769356abf71af71199
Signed-off-by: Marri Devender Rao <devenrao@in.ibm.com>
diff --git a/README.md b/README.md
index cb0c4da..6041595 100644
--- a/README.md
+++ b/README.md
@@ -12,21 +12,168 @@
To clean the repository run `./bootstrap.sh clean`.
```
-## REST command to delete an error
+# Adding application specific error YAML
+* This document captures steps for adding application specific error YAML files
+ and generating local elog-errors.hpp header file for application use.
+* Should cater for continuous integration (CI) build, bitbake image build, and
+ local repository build.
- curl -c cjar -k -X POST -H "Content-Type: application/json" \
- -d '{"data": [ "root", "<root password>" ] }' https://<BMC IP>/login
+## Continuous Integration (CI) build
+ * Make is called on the repository that is modified.
+ * Dependent packages are pulled based on the dependency list specified in the
+ configure.ac script.
- curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
- -d '{"data": []}' \
- https://<BMC IP>/xyz/openbmc_project/logging/entry/<entry num>/action/Delete
+## Recipe build
+ * Native recipes copy error YAML files to shared location.
+ * phosphor-logging builds elog-errors.hpp by parsing the error YAML files from
+ the shared location.
-## REST command to delete all errors
+## Local repository build
+ * Copies local error YAML files to the shared location in SDK
+ * Make generates elog-errors.hpp by parsing the error YAML files from the
+ shared location.
- curl -c cjar -k -X POST -H "Content-Type: application/json" \
- -d '{"data": [ "root", "<root password>" ] }' https://<<BMC IP>/login
+## Makefile changes
+**Reference**
+ * https://github.com/openbmc/openpower-debug-collector/blob/master/Makefile.am
+### Export error YAML to shared location
+*Modify Makefile.am to export newly added error YAML to shared location*
+```
+yamldir = ${datadir}/phosphor-dbus-yaml/yaml
+nobase_yaml_DATA = \
+ org/open_power/Host.errors.yaml
+```
+### Generate elog-errors.hpp using elog parser from SDK location
+ * Add a conditional check "GEN_ERRORS"
+ * Disable the check for recipe bitbake image build
+ * Enable it for local repository build
+ * If "GEN_ERRORS" is enabled, build generates elog-errors.hpp header file.
+```
+ # Generate phosphor-logging/elog-errors.hpp
+ if GEN_ERRORS
+ ELOG_MAKO ?= elog-gen-template.mako.hpp
+ ELOG_DIR ?= ${OECORE_NATIVE_SYSROOT}${datadir}/phosphor-logging/elog
+ ELOG_GEN_DIR ?= ${ELOG_DIR}/tools/
+ ELOG_MAKO_DIR ?= ${ELOG_DIR}/tools/phosphor-logging/templates/
+ YAML_DIR ?= ${OECORE_NATIVE_SYSROOT}${datadir}/phosphor-dbus-yaml/yaml
+ phosphor-logging/elog-errors.hpp:
+ @mkdir -p ${YAML_DIR}/org/open_power/
+ @cp ${top_srcdir}/org/open_power/Host.errors.yaml \
+ ${YAML_DIR}/org/open_power/Host.errors.yaml
+ @mkdir -p `dirname $@`
+ @chmod 777 $(ELOG_GEN_DIR)/elog-gen.py
+ $(AM_V_at)$(PYTHON) $(ELOG_GEN_DIR)/elog-gen.py -y ${YAML_DIR} \
+ -t ${ELOG_MAKO_DIR} -m ${ELOG_MAKO} -o $@
+ endif
+```
- curl -c cjar -b cjar -k -H "Content-Type: application/json" \
- -X POST https://<<BMC IP>/xyz/openbmc_project/logging/action/deleteAll \
- -d "{\"data\": [] }"
+### Update BUILT_SOURCES
+ * Append elog-errors.hpp to BUILT_SOURCES list and put it in conditional check
+ GEN_ERRORS so that the elog-errors.hpp is generated only during local
+ repository build.
+```
+ if GEN_ERRORS
+ nobase_nodist_include_HEADERS += \
+ phosphor-logging/elog-errors.hpp
+ endif
+ if GEN_ERRORS
+ BUILT_SOURCES += phosphor-logging/elog-errors.hpp
+ endif
+```
+### Conditional check for native build
+ * As the same Makefile is used both for recipe image build and native recipe
+ build, add a conditional to ensure that only installation of error yaml files
+ happens during native build. It is not required to build repository during
+ native build.
+```
+ if !INSTALL_ERROR_YAML
+ endif
+```
+## Autotools changes
+**Reference**
+ * https://github.com/openbmc/openpower-debug-collector/blob/master/configure.ac
+### Add option(argument) to enable/disable installing error yaml file
+ * Install error yaml option(argument) is enabled for native recipe build
+ and disabled for bitbake build.
+
+ * When install error yaml option is disabled do not check for target specific
+ packages in autotools configure script.
+
+### Add option(argument) to install error yaml files
+```
+AC_ARG_ENABLE([install_error_yaml],
+ AS_HELP_STRING([--enable-install_error_yaml],
+ [Enable installing error yaml file]),[], [install_error_yaml=no])
+AM_CONDITIONAL([INSTALL_ERROR_YAML],
+ [test "x$enable_install_error_yaml" = "xyes"])
+AS_IF([test "x$enable_install_error_yaml" != "xyes"], [
+..
+..
+])
+```
+### Add option(argument) to enable/disable generating elog-errors header file
+```
+AC_ARG_ENABLE([gen_errors],
+ AS_HELP_STRING([--enable-gen_errors], [Enable elog-errors.hpp generation ]),
+ [],[gen_errors=yes])
+AM_CONDITIONAL([GEN_ERRORS], [test "x$enable_gen_errors" != "xno"])
+```
+
+## Recipe changes
+**Reference**
+* https://github.com/openbmc/openbmc/blob/master/meta-openbmc-machines\
+/meta-openpower/common/recipes-phosphor/debug/openpower-debug-collector.bb
+
+### Extend recipe for native and nativesdk
+* Extend the recipe for native and native SDK builds
+```
+BBCLASSEXTEND += "native nativesdk"
+```
+### Remove dependencies for native and native SDK build
+* Native recipe caters only for copying error yaml files to shared location.
+* For native and native SDK build remove dependency on packages that recipe
+ build depends
+
+#### Remove dependency on phosphor-logging for native build
+```
+DEPENDS_remove_class-native = "phosphor-logging"
+```
+#### Remove dependency on phosphor-logging for native SDK build
+```
+DEPENDS_remove_class-nativesdk = "phosphor-logging"
+```
+### Add install_error_yaml argument during native build
+* Add package config to enable/disable install_error_yaml feature.
+```
+## Add package config to enable/disable install_error_yaml feature
+PACKAGECONFIG ??= "install_error_yaml"
+PACKAGECONFIG[install_error_yaml] = " \
+ --enable-install_error_yaml, \
+ --disable-install_error_yaml, ,\
+ "
+```
+#### Enable install_error_yaml check for native build
+```
+PACKAGECONFIG_add_class-native = "install_error_yaml"
+PACKAGECONFIG_add_class-nativesdk = "install_error_yaml"
+```
+#### Disable install_error_yaml during target build
+```
+PACKAGECONFIG_remove_class-target = "install_error_yaml"
+```
+
+### Disable generating elog-errors.hpp for bitbake build
+* Disable gen_errors argument for bitbake image build as the application uses
+ the elog-errors.hpp generated by phosphor-logging
+* Argument is enabled by default for local repository build in the configure
+ script of the local repository.
+```
+ XTRA_OECONF += "--disable-gen_errors"
+```
+
+## Local build
+* During local build use --prefix=/usr for the configure script.
+
+**Reference**
+* https://github.com/openbmc/openpower-debug-collector/blob/master/README.md
diff --git a/app-local-errors/README.md b/app-local-errors/README.md
deleted file mode 100644
index 403c593..0000000
--- a/app-local-errors/README.md
+++ /dev/null
@@ -1,67 +0,0 @@
-## Introduction
-This document captures steps for adding application specific error yaml files
-
-### Write app specific error yaml files
-Write error yamls for your application and place them in your application
-repository.
-
-Refer to *Host.errors.yaml* at
-https://github.com/openbmc/openpower-debug-collector/blob/master/org/open_power/
-
-### Makefile rules to run sdbus++ on error yaml files
-Modify the Makefile.am as shown below for generation of error.cpp and erorr.hpp
-```
-org/open_power/Host/error.hpp: ${srcdir}/org/open_power/Host.errors.yaml
- @mkdir -p `dirname $@`
- $(SDBUSPLUSPLUS) -r $(srcdir) error exception-header org.open_power.Host > $@
-```
-```
-org/open_power/Host/error.cpp: ${srcdir}/org/open_power/Host.errors.yaml
- @mkdir -p `dirname $@`
- $(SDBUSPLUSPLUS) -r $(srcdir) error exception-cpp org.open_power.Host > $@
-```
-### Write native recipe to copy error yaml files
-Application specific error yaml files need to be copied to a known location
-so that phosphor-logging can generate error metadata by parsing the error
-yaml files.
-
-Refer to **do_install_append** method in
-**openpower-debug-collector-error-native.bb** at
-https://github.com/openbmc/openbmc/blob/master/meta-openbmc-machines/meta-openpower/common/recipes-phosphor/debug/
-
-### Establish dependency with phosphor-logging
-Establish dependency with phosphor-logging to ensure that error yaml files are
-copied to a known location before phosphor logging parses the error yaml files
-
-Refer to **phosphor-logging-error-logs-native.bbappend** at
-https://github.com/openbmc/openbmc/blob/master/meta-openbmc-machines/meta-openpower/common/recipes-phosphor/debug/
-
-### Generate application local elog-errors.hpp file
-Applications should be independently compilable so it cannot have a
-dependency on the elog-errors.hpp generated by phosphor-logging
-
-Generate application specific elog-errors.hpp using the elog-gen.py
-parser. In the future, elog-errors.hpp will be generated through autotools.
-
-The application specific elog-errors.hpp is for the build process and the
-elog-errors.hpp from phosphor-logging will be used during elog commit/report
-
-#### Example
-python tools/elog-gen.py -y /home/OpenBmc/openpower-occ-control/ -u ./tools/ -t
-tools/phosphor-logging/templates/ -m elog-gen-template.mako.hpp -o
-elog-errors.hpp
-
-### Reporting error
-To report (commit) the error follow the below format
-***report<sdbusplus::exception_t>(metadata)***
-#### *example*
-```
-#include <xyz/openbmc_project/Software/Version/error.hpp>
-#include "elog-errors.hpp" #Use application specific header file
-
-using error =
- sdbusplus::xyz::openbmc_project::Software::Version::Error::ManifestFileFailure;
-using metadata =
-phosphor::logging::xyz::openbmc_project::Software::Version::ManifestFileFailure;
-report<error>(metadata::PATH(tarFilePath.c_str())););
-```