From Fedora Project Wiki
(Build section)
(Directory ownership)
 
(18 intermediate revisions by 2 users not shown)
Line 4: Line 4:
  
 
== How to package a Preupgrade Assistant contents ==
 
== How to package a Preupgrade Assistant contents ==
Contents files are packaged as a subpackage of main package (e.g mariadb)
+
Contents files are packaged as a subpackage of main package (e.g mariadb).
  
 
== Naming guidelines ==
 
== Naming guidelines ==
Every Preupgrade Assistant content subpackage name must start with ''preupgrade-assistant-contents-'' followed by original package name.
+
Every Preupgrade Assistant content subpackage name must start with ''preupgrade-assistant-'' followed by original package name.
  
For example Preupgrade Assistant content subpackage for ''mariadb'' will be named ''preupgrade-assistant-contents-mariadb''.
+
For example Preupgrade Assistant content subpackage for ''mariadb'' will be named ''preupgrade-assistant-mariadb''.
  
 
== Dependencies ==
 
== Dependencies ==
Line 18: Line 18:
  
 
== Architecture ==
 
== Architecture ==
* All ''preupgrade-assistant-contents-*'' subpackages must be architecture independent, i.e. have <code>BuildArch: noarch</code>.
+
* All ''preupgrade-assistant-*'' subpackages must be architecture independent, i.e. have <code>BuildArch: noarch</code>.
  
 
== Macros ==
 
== Macros ==
Line 24: Line 24:
 
* Macro <code>%{preupg_number}</code> means source release from which the system is going to be upgraded, e.g. Fedora 22.
 
* Macro <code>%{preupg_number}</code> means source release from which the system is going to be upgraded, e.g. Fedora 22.
 
* Macro <code>%{postupg_number}</code> means target release to which the system is going to be upgraded, e.g. Fedora 23.
 
* Macro <code>%{postupg_number}</code> means target release to which the system is going to be upgraded, e.g. Fedora 23.
 +
* Macro <code>%{preupg_results}</code> means where the contents files are generated
 +
* Macro <code>%{preupgrade_name}</code> means '''Fedora%{preupg_number}_%{postupg_number}''', e.g. Fedora22_23
 +
* Macro <code>%{preupgrade_dir}</code> reference to '''/usr/share/preupgrade/%{preupgrade_name}'''
 +
 +
== Prep section ==
 +
Copy all contents files to '''%{preupgrade_name}/%{name}''' directory.
 +
 +
Content files are:
 +
* INI file
 +
* check_script (python or bash)
 +
* text file with solution description.
 +
 +
=== INI file structure ===
 +
 +
INI file is checked by '''%{preupgrade_build}''' script. If something is missing user is informed.
 +
 +
[preupgrade]
 +
content_title: Short content name
 +
author: Your Name <yname@ydomain.com>
 +
content_description: 'Enter your description here'
 +
config_file: <configuration_file_separated_by_comma> THIS IS OPTIONAL. IT INFORMS ADMINISTRATOR WHAT FILES ARE AFFECTED
 +
check_script: <checking script name created during this guide>
 +
solution: <text_how_to_solve_a_problem_after_an_upgrade>
 +
applies_to: <specify_package_needs_to_be_on_system. if_not_installed_then_NOT_APPLICABLE> , comma separated
 +
requires: <specify_package_needs_to_be_on_system> THIS IS OPTIONAL
 +
 +
The elements description:
 +
 +
* content_title - Defines a single item to be checked as a part of a group.
 +
* author - Author of the content, will be used in automatically created header of scripts
 +
* content_description - Describes a rule and what the checks are.
 +
* config_file - Defines which configuration files are checked.
 +
* check_script - A script used for checking the system before upgrade. If the script does not exist, the user is notified and the group.xml autogeneration fails.
 +
* solution - Text file which describes how to solve a problem after an upgrade.
 +
* applies_to - Package checked by the script, if not available check will not run. Result is NOT_APPLICABLE.
 +
* requires - If a check script needs awk binary then package gawk should be mentioned here.
 +
 +
=== Bash check script template ===
 +
 +
Template for bash check script
 +
 +
#!/bin/bash
 +
 +
. /usr/share/preupgrade/common.sh
 +
 +
#END GENERATED SECTION
 +
 +
# This check can be used if you need root privilegues
 +
 +
# Copy your config file from RHEL6 (in case of scenario RHEL6_7)
 +
# to Temporary Directory
 +
CONFIG_FILE="full_path_to_your_config_file"
 +
mkdir -p $VALUE_TMP_PREUPGRADE/cleanconf/$(dirname $CONFIG_FILE)
 +
cp $CONFIG_FILE $VALUE_TMP_PREUPGRADE/cleanconf/$CONFIG_FILE
 +
 +
# Now check you configuration file for options
 +
# and for other stuff related with configuration
 +
 +
# If configuration can be used on target system (like RHEL7 in case of RHEL6_7)
 +
# the exit should be RESULT_PASS
 +
 +
# If configuration can not be used on target system (like RHEL 7 in case of RHEL6_7)
 +
# scenario then result should be RESULT_FAIL. Correction of
 +
# configuration file is provided either by solution script
 +
# or by postupgrade script located in $VALUE_TMP_PREUPGRADE/postupgrade.d/
 +
 +
# if configuration file can be fixed then fix them in temporary directory
 +
# $VALUE_TMP_PREUPGRADE/$CONFIG_FILE and result should be RESULT_FIXED
 +
# More information about this issues should be described in solution.txt file
 +
# as reference to KnowledgeBase article.
 +
 +
grep "Sometext" $CONFIG_FILE
 +
if [ $? -ne 0 ]; then
 +
    log_info "Config file $CONFIG_FILE will be fixed by solution script"
 +
    # postupgrade.d directory from your content is automatically copied by
 +
    # preupgrade assistant into $VALUE_TMP_PREUPGRADE/postupgrade.d/ directory
 +
    exit $RESULT_FAIL
 +
fi
 +
 +
exit $RESULT_PASS
 +
 +
=== Python check script template ===
 +
 +
Template for python check script
 +
 +
#!/usr/bin/python
 +
# -*- Mode: Python; python-indent: 8; indent-tabs-mode: t -*-
 +
 +
import sys, os, errno
 +
import datetime
 +
 +
from preup.script_api import *
 +
 +
#END GENERATED SECTION
 +
component = "Specify component name used for logging"
 +
# exit functions are exit_{pass,not_applicable, fixed, fail, etc.}
 +
# logging functions are log_{error, warning, info, etc.}
 +
# for logging in-place risk use functions log_{extreme, high, medium, slight}_risk
 +
 +
def main():
 +
    if os.geteuid() != 0:
 +
        sys.stdout.write("Need to be root.\n")
 +
        log_slight_risk("The script needs to be run under root account")
 +
        exit_error()
 +
 +
 +
if __name__ == "__main__":
 +
set_component(component)
 +
main()
 +
exit_pass()
  
 
== Build section ==
 
== Build section ==
 
Run command:
 
Run command:
  %preupgrade_build Fedora%{preupg_number}_%{postupg_number}/
+
  %{preupgrade_build} %{preupgrade_name}/%{name}/
 +
 
 +
%{preupgrade_build} command has to succeed. Warning can be suppressed.
  
 
== Install section ==
 
== Install section ==
Line 33: Line 145:
 
  %install
 
  %install
 
  ...
 
  ...
  mkdir -p ${buildroot}%{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}
+
  mkdir -p ${buildroot}%{preupgrade_dir}/%{name}
  cp preupgrade/* ${buildroot}%{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}/
+
install -p -m 755 %{SourceY} ${buildroot}%{preupgrade_dir}/%{name}/check.sh
 
+
  install -p -m 644 %{SourceZ} ${buildroot}%{preupgrade_dir}/%{name}/solution.txt
== Check section ==
+
install -p -m 644 %{preupgrade_name}-%{preupg_results}/%{name}/group.xml ${buildroot}%{preupgrade_dir}/%{name}/group.xml
* %check_preupgrade needs to be run in %check section.
 
%check
 
%check_preupgrade %{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/
 
  
 
== Files section ==
 
== Files section ==
Line 45: Line 154:
 
  %files
 
  %files
 
  ...
 
  ...
  %dir %{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}
+
  %files -n preupgrade-assistant-%{name}
 +
%dir %{preupgrade_dir}/%{name}
 
* All files except text files should be listed like
 
* All files except text files should be listed like
 
  %files
 
  %files
 
  ...
 
  ...
  %{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}/*.{sh,py}
+
  %files -n preupgrade-assistant-%{name}
  %{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}/*.ini
+
%{preupgrade_dir}/%{name}/*.{sh,py}
 +
  %{preupgrade_dir}/%{name}/*.xml
 
* All text files from content should be listed via
 
* All text files from content should be listed via
 
  %files
 
  %files
 
  ...
 
  ...
  %doc %{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}/*.txt
+
  %files -n preupgrade-assistant-%{name}
 +
%doc %{preupgrade_dir}/%{name}/*.txt
  
 
== Directory ownership ==
 
== Directory ownership ==
Directories <code>%{preupgrade_dir}</code> and
+
Directories <code>/usr/share/preupgrade</code> and
<code>%{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}</code>
+
<code>%{preupgrade_dir}</code>
are owned by package ''preupgrade-assistant'' itself.
+
are owned by package ''preupgrade-assistant'' itself and should not be owned by your package.
  
 
== Sample SPEC ==
 
== Sample SPEC ==
  
Snapshot of mariadb.spec
 
 
<pre>
 
<pre>
 +
Name:            foo
 +
Version:          1.0
 +
Release:          1%{?dist}
 +
Summary:          An example package
 +
URL:              http://example.com
 +
License:          MIT
  
Name:             mariadb
+
Source0:         http://example.com/foo/foo-%{version}.tgz
Version:         %{compatver}.%{bugfixver}
+
Source1:          foo.ini
Release:          4%{?with_debug:.debug}%{?dist}
+
Source2:          foo.sh
Epoch:            1
+
Source3:          foo.txt
 
 
Summary:          A community developed branch of MySQL
 
Group:            Applications/Databases
 
URL:              http://mariadb.org
 
# Exceptions allow client libraries to be linked with most open source SW,
 
# not only GPL code.  See README.mysql-license
 
License:          GPLv2 with exceptions and LGPLv2 and BSD
 
 
 
Source0:          http://mirrors.syringanetworks.net/mariadb/mariadb-%{version}/source/mariadb-%{version}.tar.gz
 
  
SourceX:          mariadb.ini
+
[Bulk of foo packaging elided]
SourceY:          mariadb.sh
 
SourceZ:          mariadb.txt
 
  
%package -n preupgrade-assistant-contents-%{name}
+
%package -n preupgrade-assistant-%{name}
 
BuildRequires:    preupgrade-assistant-devel
 
BuildRequires:    preupgrade-assistant-devel
 
Requires:        preupgrade-assistant
 
Requires:        preupgrade-assistant
  
%description -n preupgrade-assistant-contents-%{name}
+
%description -n preupgrade-assistant-%{name}
The content is used for assessment before upgrading major release via fedup.
+
Files used by preupgrade to assist with upgrading between
 +
major releases of the foo package via fedup.
  
 
%prep
 
%prep
 
# Copy all content files to %{preupgrade_dir}
 
# Copy all content files to %{preupgrade_dir}
mkdir -p preupgrade
+
mkdir -p %{preupgrade_name}/%{name}
cp %{SOURCEX} preupgrade/%{SOURCEX}
+
cp %{SOURCE1} %{preupgrade_name}/%{name}/%{SOURCE1}
cp %{SOURCEY} preupgrade/%{SOURCEY}
+
cp %{SOURCE2} %{preupgrade_name}/%{name}/%{SOURCE2}
cp %{SOURCEZ} preupgrade/%{SOURCEZ}
+
cp %{SOURCE3} %{preupgrade_name}/%{name}/%{SOURCE3}
 +
 
 +
%build
 +
%{preupgrade_build} %{preupgrade_name}/%{name}/
  
 
%install
 
%install
mkdir -p %{buildroor}%{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}
+
mkdir -p %{buildroot}%{preupgrade_dir}/%{name}
cp preupgrade/* %{buildroor}%{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}/
+
install -p -m 755 %{SOURCE2} %{buildroot}%{preupgrade_dir}/%{name}/%{SOURCE2}
 +
install -p -m 644 %{SOURCE3} %{buildroot}%{preupgrade_dir}/%{name}/%{SOURCE3}
 +
install -p -m 644 %{preupgrade_name}-%{preupg_results}/%{name}/group.xml %{buildroot}%{preupgrade_dir}/%{name}/group.xml
  
%check
 
%check_preupg %{buildroor}%{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/
 
  
%files -n preupgrade-assistant-contents-%{name}
+
%files -n preupgrade-assistant-%{name}
%dir %{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}
+
%dir %{preupgrade_dir}/%{name}
%doc %{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}/*.txt
+
%doc %{preupgrade_dir}/%{name}/*.txt
%{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}/*.{py,sh}
+
%{preupgrade_dir}/%{name}/*.{py,sh}
%{preupgrade_dir}/Fedora%{preupg_number}_%{postupg_number}/%{name}/*.ini
+
%{preupgrade_dir}/%{name}/*.xml
 
</pre>
 
</pre>

Latest revision as of 08:35, 20 February 2015

Warning.png
This is a DRAFT.

Preupgrade Assistant contents Packaging guidelines

How to package a Preupgrade Assistant contents

Contents files are packaged as a subpackage of main package (e.g mariadb).

Naming guidelines

Every Preupgrade Assistant content subpackage name must start with preupgrade-assistant- followed by original package name.

For example Preupgrade Assistant content subpackage for mariadb will be named preupgrade-assistant-mariadb.

Dependencies

  • All packages must have
 Requires: preupgrade-assistant
 BuildRequires: preupgrade-assistant-devel

Devel package contains macros and contents validating check script.

Architecture

  • All preupgrade-assistant-* subpackages must be architecture independent, i.e. have BuildArch: noarch.

Macros

  • Macro denoting the parent directory where the package files go is %{preupgrade_dir}. This currently expands to /usr/share/preupgrade.
  • Macro %{preupg_number} means source release from which the system is going to be upgraded, e.g. Fedora 22.
  • Macro %{postupg_number} means target release to which the system is going to be upgraded, e.g. Fedora 23.
  • Macro %{preupg_results} means where the contents files are generated
  • Macro %{preupgrade_name} means Fedora%{preupg_number}_%{postupg_number}, e.g. Fedora22_23
  • Macro %{preupgrade_dir} reference to /usr/share/preupgrade/%{preupgrade_name}

Prep section

Copy all contents files to %{preupgrade_name}/%{name} directory.

Content files are:

  • INI file
  • check_script (python or bash)
  • text file with solution description.

INI file structure

INI file is checked by %{preupgrade_build} script. If something is missing user is informed.

[preupgrade]
content_title: Short content name
author: Your Name <yname@ydomain.com>
content_description: 'Enter your description here'
config_file: <configuration_file_separated_by_comma> THIS IS OPTIONAL. IT INFORMS ADMINISTRATOR WHAT FILES ARE AFFECTED
check_script: <checking script name created during this guide>
solution: <text_how_to_solve_a_problem_after_an_upgrade>
applies_to: <specify_package_needs_to_be_on_system. if_not_installed_then_NOT_APPLICABLE> , comma separated
requires: <specify_package_needs_to_be_on_system> THIS IS OPTIONAL

The elements description:

  • content_title - Defines a single item to be checked as a part of a group.
  • author - Author of the content, will be used in automatically created header of scripts
  • content_description - Describes a rule and what the checks are.
  • config_file - Defines which configuration files are checked.
  • check_script - A script used for checking the system before upgrade. If the script does not exist, the user is notified and the group.xml autogeneration fails.
  • solution - Text file which describes how to solve a problem after an upgrade.
  • applies_to - Package checked by the script, if not available check will not run. Result is NOT_APPLICABLE.
  • requires - If a check script needs awk binary then package gawk should be mentioned here.

Bash check script template

Template for bash check script

#!/bin/bash

. /usr/share/preupgrade/common.sh

#END GENERATED SECTION

# This check can be used if you need root privilegues

# Copy your config file from RHEL6 (in case of scenario RHEL6_7) 
# to Temporary Directory
CONFIG_FILE="full_path_to_your_config_file"
mkdir -p $VALUE_TMP_PREUPGRADE/cleanconf/$(dirname $CONFIG_FILE)
cp $CONFIG_FILE $VALUE_TMP_PREUPGRADE/cleanconf/$CONFIG_FILE

# Now check you configuration file for options
# and for other stuff related with configuration

# If configuration can be used on target system (like RHEL7 in case of RHEL6_7)
# the exit should be RESULT_PASS

# If configuration can not be used on target system (like RHEL 7 in case of RHEL6_7)
# scenario then result should be RESULT_FAIL. Correction of
# configuration file is provided either by solution script
# or by postupgrade script located in $VALUE_TMP_PREUPGRADE/postupgrade.d/

# if configuration file can be fixed then fix them in temporary directory
# $VALUE_TMP_PREUPGRADE/$CONFIG_FILE and result should be RESULT_FIXED
# More information about this issues should be described in solution.txt file
# as reference to KnowledgeBase article.

grep "Sometext" $CONFIG_FILE
if [ $? -ne 0 ]; then
    log_info "Config file $CONFIG_FILE will be fixed by solution script"
    # postupgrade.d directory from your content is automatically copied by
    # preupgrade assistant into $VALUE_TMP_PREUPGRADE/postupgrade.d/ directory
    exit $RESULT_FAIL
fi

exit $RESULT_PASS

Python check script template

Template for python check script

#!/usr/bin/python
# -*- Mode: Python; python-indent: 8; indent-tabs-mode: t -*- 

import sys, os, errno
import datetime

from preup.script_api import *

#END GENERATED SECTION
component = "Specify component name used for logging"
# exit functions are exit_{pass,not_applicable, fixed, fail, etc.}
# logging functions are log_{error, warning, info, etc.}
# for logging in-place risk use functions log_{extreme, high, medium, slight}_risk

def main():
    if os.geteuid() != 0:
        sys.stdout.write("Need to be root.\n")
        log_slight_risk("The script needs to be run under root account")
        exit_error()


if __name__ == "__main__":
	set_component(component) 
	main()
	exit_pass()

Build section

Run command:

%{preupgrade_build} %{preupgrade_name}/%{name}/

%{preupgrade_build} command has to succeed. Warning can be suppressed.

Install section

All files from preupgrade directory should be installed with

%install
...
mkdir -p ${buildroot}%{preupgrade_dir}/%{name}
install -p -m 755 %{SourceY} ${buildroot}%{preupgrade_dir}/%{name}/check.sh
install -p -m 644 %{SourceZ} ${buildroot}%{preupgrade_dir}/%{name}/solution.txt
install -p -m 644 %{preupgrade_name}-%{preupg_results}/%{name}/group.xml ${buildroot}%{preupgrade_dir}/%{name}/group.xml

Files section

  • Directory where Preupgrade Assistant installs files and directories must be owned by the subpackage
%files
...
%files -n preupgrade-assistant-%{name}
%dir %{preupgrade_dir}/%{name}
  • All files except text files should be listed like
%files
...
%files -n preupgrade-assistant-%{name}
%{preupgrade_dir}/%{name}/*.{sh,py}
%{preupgrade_dir}/%{name}/*.xml
  • All text files from content should be listed via
%files
...
%files -n preupgrade-assistant-%{name}
%doc %{preupgrade_dir}/%{name}/*.txt

Directory ownership

Directories /usr/share/preupgrade and %{preupgrade_dir} are owned by package preupgrade-assistant itself and should not be owned by your package.

Sample SPEC

Name:             foo
Version:          1.0
Release:          1%{?dist}
Summary:          An example package
URL:              http://example.com
License:          MIT

Source0:          http://example.com/foo/foo-%{version}.tgz
Source1:          foo.ini
Source2:          foo.sh
Source3:          foo.txt

[Bulk of foo packaging elided]

%package -n preupgrade-assistant-%{name}
BuildRequires:    preupgrade-assistant-devel
Requires:         preupgrade-assistant

%description -n preupgrade-assistant-%{name}
Files used by preupgrade to assist with upgrading between
major releases of the foo package via fedup.

%prep
# Copy all content files to %{preupgrade_dir}
mkdir -p %{preupgrade_name}/%{name}
cp %{SOURCE1} %{preupgrade_name}/%{name}/%{SOURCE1}
cp %{SOURCE2} %{preupgrade_name}/%{name}/%{SOURCE2}
cp %{SOURCE3} %{preupgrade_name}/%{name}/%{SOURCE3}

%build
%{preupgrade_build} %{preupgrade_name}/%{name}/

%install
mkdir -p %{buildroot}%{preupgrade_dir}/%{name}
install -p -m 755 %{SOURCE2} %{buildroot}%{preupgrade_dir}/%{name}/%{SOURCE2}
install -p -m 644 %{SOURCE3} %{buildroot}%{preupgrade_dir}/%{name}/%{SOURCE3}
install -p -m 644 %{preupgrade_name}-%{preupg_results}/%{name}/group.xml %{buildroot}%{preupgrade_dir}/%{name}/group.xml


%files -n preupgrade-assistant-%{name}
%dir %{preupgrade_dir}/%{name}
%doc %{preupgrade_dir}/%{name}/*.txt
%{preupgrade_dir}/%{name}/*.{py,sh}
%{preupgrade_dir}/%{name}/*.xml