From cd4739e1d25fcd2f37bbb687cc1427d488eb6ee5 Mon Sep 17 00:00:00 2001 From: Miruna Paun Date: Fri, 14 Apr 2017 17:58:15 +0200 Subject: First draft of Virt profile to master branch LXCR-7536 Updating to the CR that contains info about this new profile documentation as a whole. Signed-off-by: Miruna Paun --- doc/Makefile | 374 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 374 insertions(+) create mode 100644 doc/Makefile (limited to 'doc/Makefile') diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..2149730 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,374 @@ +#2017-04-13 Created first version of virtualization profile + +#Path to this subsystem's root directory +SUBSYSROOT := $(shell pwd) + +# NOTE: MANIFESTHASH in manifest_conf.mk needs to be the final release tag before a release +# The manifest_conf.mk defines MANIFESTHASH and MANIFESTURL and PROFILE_NAME(on front+footers) +include manifest_conf.mk +MANIFESTDIR := $(shell echo "$(MANIFESTURL)" | sed 's/.*\///;s/\.git//') + +# Further down we extract the list of target manifest file names from the manifest itself + + + +# ***************** Generic docbuild.git auto-clone + s_docbuild symlink *** +# This also defines TMPCLONEROOT which optionally can be nondefault using BOOK_GLOBALCLONEROOT=yes or a path +include init.mk + +TMPCLONEROOT_MANIFEST := $(TMPCLONEROOT)/manifest + + +# ******************* AutoGenerated chapter from template and target READMEs ******* +BUILDBOOT_XML := book-enea-linux-release-info/doc/build_boot_generated.xml +BUILDBOOT_TEMPLATE := book-enea-linux-release-info/doc/build_boot_template.xml + +PKGDIFF_GEN_XML := book-enea-linux-release-info/doc/pkgdiff_generated.xml +JIRA_ISSUES_GEN_XML := book-enea-linux-release-info/doc/jiraissues_generated.xml + +MACHINE_LIST_XML := book-enea-linux-release-info/doc/machine_list_generated.xml + +ELTF_PARAMS_TEMPLATE := book-enea-linux-release-info/doc/eltf_params_template.xml +ELTF_PARAMS_UPDATED := book-enea-linux-release-info/doc/eltf_params_updated.xml + + + +# ----------------------------------------------------- +#Path to DocBook make files and templates +DOCBOOKMAKE = $(SUBSYSROOT)/s_docbuild/docmake +DOCBOOKTEMPLATE = $(SUBSYSROOT)/s_docbuild/template + +#Path to the OLINK database including leading part of file name (will add -$(FORMAT).db) +DOCBOOKOLINKDB_BASE = $(SUBSYSROOT)/s_docbuild/olinkdb/olink-targetdb-master + +DOCBOOK_OLINKS ?= yes +DOCBOOK_FO_USEFOP ?= yes +DOCBOOK_TO_BOOKDIR ?= yes +DOCBOOK_CLEANTMP ?= yes + +#Components (books) in this subsystem. Now use all books found here +# COMPONENTS := book-enea-linux-release-info book-enea-linux-open-source +# COMPONENTS += book-enea-linux-eclipse-open-source (as of 13.04.2017 this is not needed) +COMPONENTS := $(shell ls -d book-enea* ) + +# -------------------------------------------------------------- +ifeq ($(VERBOSE),yes) +VERB := +else +VERB := @ +endif +MAKEFLAGS += --no-print-directory +MAKEFLAGS += --directory $(SUBSYSROOT) +MAKEFLAGS += --no-builtin-rules --no-builting-variables + +# Skip xml validation to make it possible to include xml files with unresolved links +VALIDATE = no + +# BL_LABEL is either given on make command line or using BOOK_VER which have defaults below or a timestamp + +# ****************************************************************** + +# Export all parameters including those on the command line +export + +.PHONY: doc books docusage init initbuild initmanifest initpardoc initbuildboot dist + + +docusage: + @echo 'make docusage #Shows this help text' + @echo ' DOCBOOK_TOOLS_VERSIONS=yes #Displays./testeltfver.sh DocBook tools versions in this machine' + @echo 'make doc #Builds doc. ALSO automatically does all inits if needed' + @echo 'make dist BOOK_DIST_DIR=xx/doc #Builds doc as above and copies results to BOOK_DIST_DIR' + @echo ' # Does not work with DOCBOOK_TO_BOOKDIR or BOOK_BUILD_DIR' +# @echo ' BOOK_DIST_ECLIPSE=yes #Currently EclipseHelp formated doc will not be in BOOK_DIST_DIR' + @echo ' # unless BOOK_DIST_ECLIPSE is set to yes' + @echo 'make init #Init all needed init* below' + @echo 'make initbuild #Init s_docbuild Docbook build system and central files' + @echo 'make initmanifest #Init s_manifest by cloning, to detect which targets are included' + @echo 'make initpardoc #Init s_docsrc_common with extracted parameters/' + @echo 'make initbuildboot #Init build_boot chapter from READMEs and template in release info' + @echo 'make initissues #Init known issues section from Jira' + @echo 'make eltf #Test - displays all ELTF_xxx variables that ELTF shall replace' + @echo ' MANIFESTHASH=xxxxx #Option for all inits above to use nondefault manifest version' + @echo ' #It shall either be ref/tags/ or a hashvalue' + @echo ' #Configured tag or hashvalue $(MANIFESTHASH)' + @echo ' #Configured MANIFESTURL $(MANIFESTURL)' + @echo ' #Configured PROFILE_NAME $(PROFILE_NAME)' + @echo ' DOCBOOK_CLEANTMP=no #Option to keep temp files in doc/ and tmp/' + @echo ' BOOK_GLOBALCLONEROOT=yes #Option for all init above to clone all outside the doc directory' + @echo ' BOOK_GLOBALCLONEROOT=otherpath #Option for all init above to clone all to given path' + @echo 'make clean #Clean results and all s_*, but not any external clones' + @echo '' + @echo 'Optional parameters for make doc:' + @echo ' COMP= #Component (book) to build. Book component names are book-*' + @echo ' #Default component/s:' + @echo ' $(COMPONENTS)' + @echo ' FORMAT= #One of: pdf, html, or eclipse (Default all are built)' + @echo ' BL_LABEL= #Becomes footer in book (default: from poky enea.conf MAJORMINOR' + @echo ' # and with profile name taken from the manifest repo name)' + @echo ' DOCBOOK_TO_BOOKDIR=no #(default yes) Avoid moving result to book directory' + @echo ' # and avoid erasing common doc and tmp directories' + @echo ' BOOKFORCE=yes #Force rebuilding (ignore dependency on file times or BL_LABEL)' + @echo ' # Dependency only works if common doc directory is kept' + @echo ' BOOKCONDITION="xx;yy;.." #Include XML elements with condition any of xx or yy' + @echo ' # (if rebuilding, BOOKFORCE=yes may be needed)' + @echo ' # Empty=only default. none=none, all=everything.' + @echo ' BOOKDEFAULTCONDITION #Default conditions, if no BOOKCONDITION. Used in book-*/swcomp.mk' + @echo ' SHOW_COMMENTS=yes #For proofread. Unhide .. comments Only PDF' + @echo ' BOOKVERBOSE=yes #Verbose info building books' + @echo ' DOCBOOK_OLINKS=no #Avoid the olink database in Makefile (in book not using it)' + @echo ' DOCBOOK_OLINK_TARGETDB=only #Build a target db for this book (for links into it)' + @echo ' DOCBOOK_OLINK_TARGETDB=yes #Build a target db AND build the book' + @echo ' #Master olinkdb defined in this Makefile, one per generated format, is:' + @echo ' $(DOCBOOKOLINKDB_BASE)_*.db' + @echo ' Typical examples:' + @echo ' make doc Creates all books, all formats' + @echo ' make doc COMP=book-xxxx FORMAT=html' + @echo ' make doc COMP=book-xxxx FORMAT=pdf' + @echo ' make doc BL_LABEL="Version 1.2.3" Creates all with version in footers and front' + @echo '' + @echo ' Requires docbook-xsl-1.76.1 or later, docbook-xml 4.2, svg1.1, fop-1.0 + fop-hyph.jar' + @echo ' fop + the separate fop-hyph can be found together in package "libfop-java"' + @echo ' otherwise fetch fop-hyph.jar and place in same place as fop.jar' + @echo ' Requires libxml2-2.7.8 or later, libxslt-1.1.26 or later' + @echo ' Requires java machine to run fop (creating PDF). jar for optional FORMAT=eclipse' + @echo ' Without jar, the optional EclipseHelp format can not be built' + @echo ' tools_book_standalone.mk => libxml2, libxslt, and fop (and to catalog-el.xml)' + @echo ' catalog-el.xml => svg, docbook-xml, docbook-xsl' +ifeq ($(DOCBOOK_TOOLS_VERSIONS),yes) + $(VERB)$(MAKE) -f $(DOCBOOKMAKE)/tools_book_standalone.mk book_tools_versions +endif + +# We rely on make doing these in order left to right +init: initbuild initcommon initmanifest initpardoc initbuildboot initpkgdiff initissues +pullall: pullbuild + +# If no COMP, iterate over books-* in COMPONENTS with make doc +ifeq ($(COMP),) +doc: +ifneq ($(filter book-%, $(COMPONENTS)),) + $(VERB)for comp in $(filter book-%, $(COMPONENTS)); do \ + $(MAKE) doc COMP=$$comp; \ + done +endif + +else +include $(SUBSYSROOT)/$(COMP)/swcomp.mk + +doc: books + @# +endif + +dist: doc + @echo "Copying resulting built documents to $(BOOK_DIST_DIR)" + $(VERB)if [ "$(BOOK_DIST_DIR)" = "" ]; then echo "ERROR: Missing BOOK_DIST_DIR parameter, typically shall be xxx/doc"; exit 10; fi + $(VERB)if [ ! -d "`dirname $(BOOK_DIST_DIR)`" ]; then echo "ERROR: Missing parent for BOOK_DIST_DIR"; exit 10; fi + $(VERB)if [ -f "$(BOOK_DIST_DIR)/Makefile" ]; then echo "ERROR: Wrong BOOK_DIST_DIR, contains a Makefile?"; exit 10; fi + $(VERB)if [ ! -d "$(BOOK_DIST_DIR)" ]; then mkdir -p "$(BOOK_DIST_DIR)" ; fi + $(VERB)for book in $(COMPONENTS); do \ + if ls -d $$book/book*.pdf >/dev/null 2>&1; then cp --preserve=timestamps $$book/book*.pdf "$(BOOK_DIST_DIR)" ; fi ; \ + if ls -d $$book/html >/dev/null 2>&1; then cp -r --preserve=timestamps $$book/html "$(BOOK_DIST_DIR)" ; fi ; \ + if [ "$(BOOK_DIST_ECLIPSE)" = "yes" ]; then \ + if ls -d $$book/eclipse >/dev/null 2>&1; then cp -r --preserve=timestamps $$book/eclipse "$(BOOK_DIST_DIR)" ; fi ; \ + fi ; \ + done + +# Default FORMATs +ifeq ($(FORMAT),) +FORMAT=html pdf eclipse +endif + + +books: init +# BOOKPACKAGES is defined in all book-*/swcomp.mk + $(VERB)DISTRO_VERSION=`egrep '"EneaLinux_REL_VER">' $(ELTF_PARAMS_UPDATED) | sed 's/.*//;s/<\/phrase>.*//'` ; \ + BOOKVER="Profile $(PROFILE_NAME)-$$DISTRO_VERSION" ; \ + for book in $(BOOKPACKAGES); do \ + for format in $(FORMAT); do \ + $(MAKE) -f $(DOCBOOKMAKE)/make_docbook_standalone.mk BOOK=$$book FORMAT=$$format BOOK_VER="$$BOOKVER" books || exit 10; \ + done ; \ + done +ifeq ($(DOCBOOK_TO_BOOKDIR),yes) + $(VERB)rm -rf doc tmp +else +ifeq ($(DOCBOOK_CLEANTMP),yes) +# keep only doc/pdf/book-*.pdf doc/eclipse/plugins/com.enea.doc.book-* but delete doc/eclipse/plugins/com.enea.doc.book-*/done* + $(VERB)rm -rf tmp 2>/dev/null ; rm -rf doc/pdf/book-*/ ; rm -rf doc/eclipse/plugins/com.enea.doc.book-*/done* 2>/dev/null +endif +endif + +# cleaninit cleans ALL tmpcommon and all s_* +clean: cleaninit cleanbuildboot cleanpkgdiff cleanissues cleanmanifest + @echo "Cleaning build results and temporary files" + $(VERB)rm -rf doc tmp 2>/dev/null +ifneq ($(filter book-%, $(COMPONENTS)),) + $(VERB)for comp in $(filter book-%, $(COMPONENTS)); do \ + rm -rf $$comp/book*.pdf $$comp/html $$comp/eclipse 2>/dev/null; \ + done + $(VERB)rm -rf doc tmp 2>/dev/null +endif + + +# ****************************************************************** +# ****************** SUPPORT FOR TARGETS *************************** +initmanifest: s_manifest + + +# ----------------------------------------- +# We only clone the manifest to be able to autodetect which targets are in it +# git clone requires only the tag string e.g. EL6, not the entire ref/tags/EL6 that repo requires +# git clone -b hashvalue is not supported. We must first clone, then git checkout hashvalue +# These steps work also for a tag so we could use the same stepwise code + +s_manifest: $(TMPCLONEROOT_MANIFEST) + $(VERB)rm s_manifest 2>/dev/null; ln -s $(TMPCLONEROOT_MANIFEST) s_manifest + +cleanmanifest: + @echo "Cleaning generated manifest files" + $(VERB)rm -f $(MACHINE_LIST_XML) 2>/dev/null + $(VERB)rm -rf "$(TMPCLONEROOT_MANIFEST)" s_manifest 2>/dev/null + +$(TMPCLONEROOT_MANIFEST): + $(VERB)if [ ! -d "$(TMPCLONEROOT)" ] ; then mkdir -p "$(TMPCLONEROOT)" ; fi + $(VERB)if [ ! -d "$(TMPCLONEROOT_MANIFEST)" ]; then mkdir -p "$(TMPCLONEROOT_MANIFEST)" ; fi + $(VERB) MBRANCH=`echo "$(MANIFESTHASH)" | sed 's/.*\///'`; \ + echo "**** Cloning manifest version $$MBRANCH of $(MANIFESTURL) in $(TMPCLONEROOT_MANIFEST)" ; \ + cd "$(TMPCLONEROOT_MANIFEST)"; git clone $(MANIFESTURL) ; cd $(MANIFESTDIR) ; git checkout $(MANIFESTHASH) + $(VERB)if [ ! -d "$(TMPCLONEROOT_MANIFEST)/$(MANIFESTDIR)" ]; then echo "ERROR: Missing $(TMPCLONEROOT_MANIFEST)/$(MANIFESTDIR)"; exit 10 ; fi ; \ + TARGETDEFAULTXMLS=`cd $(TMPCLONEROOT_MANIFEST)/$(MANIFESTDIR); ls -1 */default.xml 2>/dev/null` ; \ + TARGET_LIST=`echo "$$TARGETDEFAULTXMLS" | sed 's/\/default.xml//;s/^/# export MACHINE=/'` ; \ + echo "" >$(MACHINE_LIST_XML) ; \ + echo ">$(MACHINE_LIST_XML) ; \ + echo "\"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd\">" >>$(MACHINE_LIST_XML) ; \ + echo "" >>$(MACHINE_LIST_XML) ; \ + echo "# Set MACHINE to ONE of the targets in this release!" >>$(MACHINE_LIST_XML) ; \ + echo "$$TARGET_LIST" >>$(MACHINE_LIST_XML) ; \ + echo "" >>$(MACHINE_LIST_XML) + + +# **************************************************************************** +# ******************** SUPPORT FOR dynamic pardoc with added parameters ****** +# pardoc-distro can contain MAJOR.MINOR-xxxxx keeping -xxxx when replacing MINOR.MINOR from enea.conf + +PATH_DOCSRC_COMMON = $(SUBSYSROOT)/s_docsrc_common +NAME_DOCSRC_COMMON = docsrc_common +TMPCLONEROOT_DOCSRC_COMMON := $(TMPCLONEROOT)/$(NAME_DOCSRC_COMMON) +TMPPARDOC := $(TMPCLONEROOT_DOCSRC_COMMON)/pardoc-distro.xml + +initpardoc: s_docsrc_common + +cleanpardoc: + @echo "Cleaning dynamic parameters" + $(VERB)rm -rf $(TMPCLONEROOT_DOCSRC_COMMON) ; rm s_docsrc_common + + +s_docsrc_common: $(TMPCLONEROOT_DOCSRC_COMMON) + $(VERB)rm s_docsrc_common 2>/dev/null; ln -s $(TMPCLONEROOT_DOCSRC_COMMON) s_docsrc_common + +$(TMPCLONEROOT_DOCSRC_COMMON): + $(VERB)if [ ! -d "$(TMPCLONEROOT)" ] ; then mkdir -p "$(TMPCLONEROOT)" ; fi + $(VERB)if [ ! -d $(TMPCLONEROOT_DOCSRC_COMMON) ]; then mkdir -p $(TMPCLONEROOT_DOCSRC_COMMON) ; fi + @echo "**** Copy docsrc_common/ files to $(TMPCLONEROOT_DOCSRC_COMMON)" + $(VERB)cat docsrc_common/pardoc-distro.xml >$(TMPPARDOC) + +# **************************************************************************** +# ***** Create XML chapter with build/boot commands from all README files in manifest + +initbuildboot: $(BUILDBOOT_XML) + +cleanbuildboot: + @echo "Cleaning generated build-boot command document file" + $(VERB)rm -f $(BUILDBOOT_XML) 2>/dev/null + + +$(BUILDBOOT_XML): $(BUILDBOOT_TEMPLATE) + @echo "**** Creating $(BUILDBOOT_XML) from READMEs" + $(VERB)INITBB_CMD=initbuildboot.sh ; \ + if [ -f "$$INITBB_CMD" ]; then \ + sh "$$INITBB_CMD" -xml $(BUILDBOOT_XML) -template $(BUILDBOOT_TEMPLATE) -readmebasedir s_manifest/$(MANIFESTDIR); \ + else \ + echo "ERROR: Missing $$INITBB_CMD, can not create $(BUILDBOOT_XML)"; exit 10; \ + fi + +# **************************************************************************** +# ***** Create Package DIFF XML section + +initpkgdiff: $(PKGDIFF_GEN_XML) + +cleanpkgdiff: + @echo "Cleaning generated package diff document file" + $(VERB)rm -f $(PKGDIFF_GEN_XML) 2>/dev/null + +$(PKGDIFF_GEN_XML): + $(VERB)PREVIOUS_BL=`egrep '"prev_baseline"' docsrc_common/pardoc-distro.xml | sed 's/^.*//;s/<\/phrase>.*$$//'` ; \ + echo "**** Generating $(PKGDIFF_GEN_XML) compared to $$PREVIOUS_BL, using gen_pkgdiff.py" ; \ + python gen_pkgdiff.py >$(PKGDIFF_GEN_XML) + + +# **************************************************************************** +# ***** Create Jira Issues XML section for the known bugs chapter + +.PHONY: $(JIRA_ISSUES_GEN_XML) +# We want new issue list to be generated also at build, not only at init + +initissues: $(JIRA_ISSUES_GEN_XML) + + +cleanissues: + @echo "Cleaning generated known issues document file" + $(VERB)rm -f $(JIRA_ISSUES_GEN_XML) 2>/dev/null + +$(JIRA_ISSUES_GEN_XML): + @echo "**** Generating $(JIRA_ISSUES_GEN_XML), fetching from Jira using gen_known_issues.py" + $(VERB)python gen_known_issues.py >$(JIRA_ISSUES_GEN_XML) + +# **************************************************************************** + +# +# All ELTF_ variables names only has upper case, underline and digits +eltf: + @echo "# make eltf extracts and displays all ELTF_ variables found here" + @echo "# in $(SUBSYSROOT)/$(ELTF_PARAMS_TEMPLATE)" + @echo "# Replace all variables, creating a new eltf*updated.xml file from the eltf*template.xml" + @echo "#" + @echo "# Only replace + push the result file $(ELTF_PARAMS_UPDATED), IF IT WILL BE CHANGED." + @echo "#" + @echo "# IMPORTANT: See eltf_params_updated_template_how_to_use.txt for requirements and details!" + @echo "# Below is only a summary!" + @echo "#" + @echo "# ELTF_ variables must be UNIQUE, e.g. a variable must not be a part of another variable" + @echo "#" + @echo "# ELTF_PL_* and ELTF_T_PL_* shall have the format for programlisting and are often multiline - see below." + @echo "#" + @echo "# ELTF_*_URL and ELTF_*_TXTURL are the URL part and TXT part of ulink; those shall be exactly identical," + @echo "# unless the URL is very very long." + @echo "#" + @echo "# ELTF_T_* are target (MACHINE) variables in one subsection, replace with machine specific strings." + @echo "#" + @echo "# Append more target subsections to *updated.xml, if more than one target is in a release!" + @echo "# Replace the line with appended" + @echo "# complete target section elements copied before the variables are replaced." + @echo "# In each target section, replace the ELTF_T* variables with machine dependent strings" + @echo "# Append final lines seen after " + @echo "# but that would often only be two final lines" + @echo "#" + @echo "# ELTF_ Variables: Replace each variable with a string, for ELTF_*PL* it can be multiline" + @echo "# DO NOT use any leading or trailing spaces and DO NOT use TABs" + @echo "#" + @echo "# ELTF_ Everywhere: Only 7-bit ASCII inside the string replacing a variable. Translate characters" + @echo "# like & < > to & < > etc." + @echo "# unless real XML shall be inserted like when entire sections are appended." + @echo "#" + @echo "# ELTF_ programlisting, variables with PL in the name: Max line length < 80 char." + @echo "# Use backslash + indent-leading-spaces for continuation lines." + @echo "# Multiline. No trailing spaces on any line inside the programlisting." + @echo "#" + @echo "# The following variables shall be replaced with suitable contents (egrep from the template):" + @echo "# Again: See details in eltf_params_updated_template_how_to_use.txt" + @echo "# including also examples of contents of each variable!" + @echo "#" + $(VERB)( egrep 'ELTF_[A-Z_0-9][A-Z_0-9]*' $(ELTF_PARAMS_TEMPLATE) 2>/dev/null | sed 's/ELTF_/\nELTF_/g' | egrep 'ELTF_[A-Z_0-9][A-Z_0-9]*' | sed 's/\(ELTF_[A-Z_0-9][A-Z_0-9]*\).*/\1/' ) | sort + @echo "# The make eltf also here extracts any left-over ELTF variables from $(ELTF_PARAMS_UPDATED)" + @echo "# It should not be any left here:" + $(VERB)( egrep 'ELTF_[A-Z_0-9][A-Z_0-9]*' $(ELTF_PARAMS_UPDATED) 2>/dev/null | sed 's/ELTF_/\nELTF_/g' | egrep 'ELTF_[A-Z_0-9][A-Z_0-9]*' | sed 's/\(ELTF_[A-Z_0-9][A-Z_0-9]*\).*/\1/' ) | sort + @echo "# If you see any left-over above, something is wrong" -- cgit v1.2.3-54-g00ecf