From Fedora Project Wiki
mNo edit summary
mNo edit summary
 
(19 intermediate revisions by the same user not shown)
Line 11: Line 11:


== File Placement ==
== File Placement ==
* '''Modules''': A module package '''MUST''' be placed in the <code>%drupal7_modules</code> directory (base "<code>modules/</code>" directory)
* '''Modules''': A module package '''MUST''' be placed in the <code>%drupal7_modules</code> directory
* '''Themes''': A theme package '''MUST''' be placed in the <code>%drupal7_themes</code> directory (base "<code>themes/</code>" directory)
* '''Themes''': A theme package '''MUST''' be placed in the <code>%drupal7_themes</code> directory
* '''Libraries''': A library package '''MUST''' be placed in the <code>%drupal7_libraries</code> directory (base "<code>libraries/</code>" directory)
* '''Libraries''': A library package '''MUST''' be placed in the <code>%drupal7_libraries</code> directory


== Requires and Provides ==
== Requires and Provides ==


* Every package '''SHOULD''' require "<code>drupal7(<drupal_machine_name>)</code>" virtual resources instead of "<code>drupal7-<drupal_machine_name></code>" packages.
<ul>
* Every package '''MUST''' include the following in its' spec:
<li>Every package '''SHOULD''' require "<code>drupal7(<drupal_machine_name>)</code>" virtual resources instead of "<code>drupal7-<drupal_machine_name></code>" packages.</li>
<pre>%{?drupal7_find_provides_and_requires}</pre>
<li>Every package '''MUST''' include the following in its' spec:
This is for compatibility with RPM < 4.9 (i.e. EPEL 5/6).
<ul>
<pre>BuildRequires: drupal7-rpmbuild &gt;= 7.22-5</pre>
<li>The <code>drupal7-rpmbuild</code> package automatically requires <code>drupal7(core)</code> and scans files for provides (from *.info files) and automatically adds them to the package during build time as "<code>drupal7(<drupal_machine_name>)</code>" virtual resources. [https://drupal.org/node/542202#hidden Hidden projects] are ignored. The use of virtual provides and requires helps alleviate the confusion of sub-modules and which modules actually provide those sub-modules.
The <code>drupal7-rpmbuild</code> package automatically requires <code>drupal7(core)</code> and scans files for provides (from *.info files) and automatically adds them to the package during build time as "<code>drupal7(<drupal_machine_name>)</code>" virtual resources. [https://drupal.org/node/542202#hidden Hidden projects] are ignored. The use of virtual provides and requires helps alleviate the confusion of sub-modules and which modules actually provide those sub-modules. They also help simplify spec files.
<pre>BuildRequires: drupal7-rpmbuild &gt;= 7.23-3</pre></li>
* Every package '''MUST NOT''':
<li>For compatibility with RPM < 4.9 (i.e. EPEL 5/6):
** explicitly require "<code>drupal7</code>" or "<code>drupal7(core)</code>" ('''unless''' a specific core version is required) because <code>drupal7-rpmbuild</code> auro-requires "<code>drupal7(core)</code>"
<pre>%{?drupal7_find_provides_and_requires}</pre></li>
** explicitly provide "<code>drupal7(<drupal_machine_name>)</code>" virtual resources because <code>drupal7-rpmbuild</code> auto-provides these
</ul>
</li>
<li>Every package '''MUST NOT''':
<ul>
<li>explicitly require "<code>drupal7</code>" or "<code>drupal7(core)</code>" ('''unless''' a specific core version is required) because <code>drupal7-rpmbuild</code> auro-requires "<code>drupal7(core)</code>"</li>
<li>explicitly provide "<code>drupal7(<drupal_machine_name>)</code>" virtual resources because <code>drupal7-rpmbuild</code> auto-provides these</li>
</ul>
</li>
</ul>


=== Other Packages ===
=== Other Packages ===
Line 34: Line 42:


See [[Packaging:PHP#Extensions_Requires|PHP packaging guidelines]].
See [[Packaging:PHP#Extensions_Requires|PHP packaging guidelines]].
To get a list of required PHP extensions, use [http://php5.laurent-laville.org/compatinfo/ PHP_CompatInfo (phpcompatinfo)]:
<pre>
phpcompatinfo print --recursive --report=extension unpacked_package_source_directory
</pre>
To install [http://php5.laurent-laville.org/compatinfo/ PHP_CompatInfo (phpcompatinfo)], run "<code>yum install php-bartlett-PHP-CompatInfo</code>".


=== Requiring a Minimum PHP Version ===
=== Requiring a Minimum PHP Version ===


See [[Packaging:PHP#Requiring_a_Minimum_PHP_version|PHP packaging guidelines]] but note that this should not normally be required by most packages (see [http://drupal.org/node/542202#php]).
See [[Packaging:PHP#Requiring_a_Minimum_PHP_version|PHP packaging guidelines]] but note that this should not normally be required by most packages (see [http://drupal.org/node/542202#php]).
{{admon/important|This needs to be added to the <code>drupal7-rpmbuild</code> package so it is automatic.}}
{{admon/important|This should be added to the <code>drupal7-rpmbuild</code> package so it is automatic.}}
 
=== Common Issues ===
 
<ul>
<li>
On RHEL 5/6 there is an issue with the standard auto-requires script (<code>/usr/lib/rpm/find-requires</code>).  When there is no "<code>#!</code>" (she-bang) line at the beginning of an executable PHP file, the script tries to add an invalid "<code><?php</code>" as a dependency.  Rpmbuild then errors out with something similar to the following:
<pre>RPM build errors:
    line 53: Dependency tokens must begin with alpha-numeric, '_' or '/': -</pre>
To fix this issue, find the files that incorrectly have their executable bit set and remove the executable bit in the spec's <code>%prep</code> section.  If there should be no executable files in the package then the following could be added to the spec's <code>%prep</code> section:
<pre>find . -type f -executable -print0 | xargs -0 chmod -x</pre>
{{admon/note|For EPEL 5, use "<code>-perm /+x</code>" instead of "<code>-executable</code>"}}
</li>
</ul>


== Macros and Scriptlets ==
== Macros and Scriptlets ==
Line 53: Line 81:
|-
|-
| <code>%drupal7_libraries</code> || <code>%{_sysconfdir}/drupal7/all/libraries</code> || Drupal 7 libraries directory
| <code>%drupal7_libraries</code> || <code>%{_sysconfdir}/drupal7/all/libraries</code> || Drupal 7 libraries directory
|-
| <code>%drupal7_find_provides_and_requires</code> || ''Fedora:''
<code>%{nil}</code>
<br /><br />
''EPEL 5/6:''<br />
<code>%{expand: \<br />
%global _use_internal_dependency_generator 0<br />
%global __find_provides %{_rpmconfigdir}/drupal7.prov %{version}<br />
%global __find_requires %{_rpmconfigdir}/drupal7.req<br />
}</code>
|| ''Fedora'':
No-op macro to allow spec compatibility with RPM < 4.9 (no fileattrs)
<br /><br />
''EPEL 5/6'':<br />
Macro to allow spec compatibility with RPM < 4.9 (no fileattrs)
|}
|}


Line 61: Line 104:
<pre>
<pre>
  This package provides the following Drupal module(s):
  This package provides the following Drupal module(s):
  * %{module_name}
  * %{module}
</pre>
</pre>
For example, the <code>drupal7-domain</code> package contains the following in its' description:
For example, the <code>drupal7-domain</code> package contains the following in its' description:
<pre>
<pre>
This package provides the following Drupal modules:
This package provides the following Drupal modules:
* %{module_name}
* %{module}
* %{module_name}_alias
* %{module}_alias
* %{module_name}_conf
* %{module}_conf
* %{module_name}_content
* %{module}_content
* %{module_name}_nav
* %{module}_nav
* %{module_name}_settings
* %{module}_settings
* %{module_name}_source
* %{module}_source
* %{module_name}_strict
* %{module}_strict
* %{module_name}_test
* %{module}_theme
* %{module_name}_theme
</pre>
</pre>
{{admon/note|<code>%{module}</code> is defined in the templates below}}
</li>
</li>
</ul>
</ul>
Line 93: Line 136:


=== Module ===
=== Module ===
{{admon/note|This template is for all versions of Fedora and EPEL 6+.  If you are packaging for EPEL 5, see [[Packaging:Guidelines]] for additional requirements that need to be added to the spec.}}


<pre>
<pre>
%{?drupal7_find_provides_and_requires}
%{?drupal7_find_provides_and_requires}


%global module_name __MODULE__
%global module __MODULE__


Name:          drupal7-%{module_name}
Name:          drupal7-%{module}
Version:      __VERSION__
Version:      __VERSION__
Release:      1%{?dist}
Release:      1%{?dist}
Line 106: Line 151:
Group:        Applications/Publishing
Group:        Applications/Publishing
License:      GPLv2+
License:      GPLv2+
URL:          http://drupal.org/project/%{module_name}
URL:          http://drupal.org/project/%{module}
Source0:      http://ftp.drupal.org/files/projects/%{module_name}-7.x-%{version}.tar.gz
Source0:      http://ftp.drupal.org/files/projects/%{module}-7.x-%{version}.tar.gz
Source1:      %{name}-RPM-README.txt
Source1:      %{name}-RPM-README.txt


BuildArch:    noarch
BuildArch:    noarch
BuildRoot:    %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
BuildRequires: drupal7-rpmbuild >= 7.23-3
BuildRequires: drupal7-rpmbuild >= 7.22-5
 
# phpcompatinfo (computed from version __VERSION__)
#Requires:      php-


%description
%description
Line 118: Line 165:


This package provides the following Drupal module(s):
This package provides the following Drupal module(s):
* %{module_name}
* %{module}




%prep
%prep
%setup -q -n %{module_name}
%setup -qn %{module}
cp -p %{SOURCE1} .
cp -p %{SOURCE1} .


Line 131: Line 178:


%install
%install
rm -rf %{buildroot}
mkdir -pm 0755 %{buildroot}%{module}/%{module}
mkdir -p -m 0755 %{buildroot}%{drupal7_modules}/%{module_name}
cp -pr * %{buildroot}%{drupal7_modules}/%{module}/
cp -pr * %{buildroot}%{drupal7_modules}/%{module_name}/
 
 
%clean
rm -rf %{buildroot}




%files
%files
%defattr(-,root,root,-)
%doc *.txt
%doc *.txt
%{drupal7_modules}/%{module_name}
%{drupal7_modules}/%{module}
%exclude %{drupal7_modules}/%{module_name}/*.txt
%exclude %{drupal7_modules}/%{module}/*.txt




Line 153: Line 194:


=== Theme ===
=== Theme ===
{{admon/note|This template is for all versions of Fedora and EPEL 6+.  If you are packaging for EPEL 5, see [[Packaging:Guidelines]] for additional requirements that need to be added to the spec.}}


<pre>
<pre>
%{?drupal7_find_provides_and_requires}
%{?drupal7_find_provides_and_requires}


%global theme_name __THEME__
%global theme  __THEME__


Name:          drupal7-%{theme_name}
Name:          drupal7-%{theme}
Version:      __VERSION__
Version:      __VERSION__
Release:      1%{?dist}
Release:      1%{?dist}
Line 166: Line 209:
Group:        Applications/Publishing
Group:        Applications/Publishing
License:      GPLv2+
License:      GPLv2+
URL:          http://drupal.org/project/%{theme_name}
URL:          http://drupal.org/project/%{theme}
Source0:      http://ftp.drupal.org/files/projects/%{theme_name}-7.x-%{version}.tar.gz
Source0:      http://ftp.drupal.org/files/projects/%{theme}-7.x-%{version}.tar.gz
Source1:      %{name}-RPM-README.txt
Source1:      %{name}-RPM-README.txt


BuildArch:    noarch
BuildArch:    noarch
BuildRoot:    %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
BuildRoot:    %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
BuildRequires: drupal7-rpmbuild >= 7.22-5
BuildRequires: drupal7-rpmbuild >= 7.23-3
 
# phpcompatinfo (computed from version __VERSION__)
#Requires:      php-


%description
%description
Line 179: Line 225:


%prep
%prep
%setup -q -n %{theme_name}
%setup -qn %{theme}
cp -p %{SOURCE1} .
cp -p %{SOURCE1} .


Line 188: Line 234:


%install
%install
rm -rf %{buildroot}
mkdir -pm 0755 %{buildroot}%{drupal7_themes}/%{theme}
mkdir -p -m 0755 %{buildroot}%{drupal7_themes}/%{theme_name}
cp -pr * %{buildroot}%{drupal7_themes}/%{theme}/
cp -pr * %{buildroot}%{drupal7_themes}/%{theme_name}/
 
 
%clean
rm -rf %{buildroot}




%files
%files
%defattr(-,root,root,-)
%doc *.txt
%doc *.txt
%{drupal7_themes}/%{theme_name}
%{drupal7_themes}/%{theme}
%exclude %{drupal7_themes}/%{theme_name}/*.txt
%exclude %{drupal7_themes}/%{theme}/*.txt




Line 208: Line 248:
- Initial package
- Initial package
</pre>
</pre>
[[Category:Packaging guidelines drafts]]

Latest revision as of 15:34, 17 February 2014

This is only a DRAFT!

Guidelines for packaging Drupal 7 modules and themes

Different Kinds of Packages

  • Modules: Modules extend and customize Drupal functionality.
  • Themes: Themes allow users to change the look and feel of their Drupal site.

Naming Scheme

Every package MUST be named drupal7-<drupal_machine_name>. Drupal itself enforces unique machine names for each of its' projects and there is a single namespace for all modules, themes, and distributions/profiles. The <drupal_machine_name> MUST match the drupal.org project name (i.e. drupal.org/project/<drupal_machine_name>).

File Placement

  • Modules: A module package MUST be placed in the %drupal7_modules directory
  • Themes: A theme package MUST be placed in the %drupal7_themes directory
  • Libraries: A library package MUST be placed in the %drupal7_libraries directory

Requires and Provides

  • Every package SHOULD require "drupal7(<drupal_machine_name>)" virtual resources instead of "drupal7-<drupal_machine_name>" packages.
  • Every package MUST include the following in its' spec:
    • The drupal7-rpmbuild package automatically requires drupal7(core) and scans files for provides (from *.info files) and automatically adds them to the package during build time as "drupal7(<drupal_machine_name>)" virtual resources. Hidden projects are ignored. The use of virtual provides and requires helps alleviate the confusion of sub-modules and which modules actually provide those sub-modules.
      BuildRequires: drupal7-rpmbuild >= 7.23-3
    • For compatibility with RPM < 4.9 (i.e. EPEL 5/6):
      %{?drupal7_find_provides_and_requires}
  • Every package MUST NOT:
    • explicitly require "drupal7" or "drupal7(core)" (unless a specific core version is required) because drupal7-rpmbuild auro-requires "drupal7(core)"
    • explicitly provide "drupal7(<drupal_machine_name>)" virtual resources because drupal7-rpmbuild auto-provides these

Other Packages

See PHP packaging guidelines.

PHP Extensions

See PHP packaging guidelines.

To get a list of required PHP extensions, use PHP_CompatInfo (phpcompatinfo):

phpcompatinfo print --recursive --report=extension unpacked_package_source_directory

To install PHP_CompatInfo (phpcompatinfo), run "yum install php-bartlett-PHP-CompatInfo".

Requiring a Minimum PHP Version

See PHP packaging guidelines but note that this should not normally be required by most packages (see [1]).

This should be added to the drupal7-rpmbuild package so it is automatic.

Common Issues

  • On RHEL 5/6 there is an issue with the standard auto-requires script (/usr/lib/rpm/find-requires). When there is no "#!" (she-bang) line at the beginning of an executable PHP file, the script tries to add an invalid "<?php" as a dependency. Rpmbuild then errors out with something similar to the following:
    RPM build errors:
        line 53: Dependency tokens must begin with alpha-numeric, '_' or '/': -

    To fix this issue, find the files that incorrectly have their executable bit set and remove the executable bit in the spec's %prep section. If there should be no executable files in the package then the following could be added to the spec's %prep section:

    find . -type f -executable -print0 | xargs -0 chmod -x
    For EPEL 5, use "-perm /+x" instead of "-executable"

Macros and Scriptlets

Macros provided by the drupal7-rpmbuild package:

Macro Value Description
%drupal7 %{_datadir}/drupal7 Drupal 7 base directory
%drupal7_modules %{drupal7}/modules Drupal 7 modules directory
%drupal7_themes %{drupal7}/themes Drupal 7 themes directory
%drupal7_libraries %{_sysconfdir}/drupal7/all/libraries Drupal 7 libraries directory
%drupal7_find_provides_and_requires Fedora:

%{nil}

EPEL 5/6:
%{expand: \
%global _use_internal_dependency_generator 0
%global __find_provides %{_rpmconfigdir}/drupal7.prov %{version}
%global __find_requires %{_rpmconfigdir}/drupal7.req
}

Fedora:

No-op macro to allow spec compatibility with RPM < 4.9 (no fileattrs)

EPEL 5/6:
Macro to allow spec compatibility with RPM < 4.9 (no fileattrs)

Additional Hints

  • Every module package SHOULD list the Drupal modules it provides in its' description:
     This package provides the following Drupal module(s):
     * %{module}
    

    For example, the drupal7-domain package contains the following in its' description:

    This package provides the following Drupal modules:
    * %{module}
    * %{module}_alias
    * %{module}_conf
    * %{module}_content
    * %{module}_nav
    * %{module}_settings
    * %{module}_source
    * %{module}_strict
    * %{module}_theme
    
    %{module} is defined in the templates below

Templates

RPM README

After installation, you must enable this module from the Drupal administration
page.

If upgrading this module separately from the core Drupal package, be sure to
run the http://hostname/drupal7/upgrade.php script after this RPM is upgraded.

Module

This template is for all versions of Fedora and EPEL 6+. If you are packaging for EPEL 5, see Packaging:Guidelines for additional requirements that need to be added to the spec.
%{?drupal7_find_provides_and_requires}

%global module __MODULE__

Name:          drupal7-%{module}
Version:       __VERSION__
Release:       1%{?dist}
Summary:       __SUMMARY__

Group:         Applications/Publishing
License:       GPLv2+
URL:           http://drupal.org/project/%{module}
Source0:       http://ftp.drupal.org/files/projects/%{module}-7.x-%{version}.tar.gz
Source1:       %{name}-RPM-README.txt

BuildArch:     noarch
BuildRequires: drupal7-rpmbuild >= 7.23-3

# phpcompatinfo (computed from version __VERSION__)
#Requires:      php-

%description
__DESCRIPTION__

This package provides the following Drupal module(s):
* %{module}


%prep
%setup -qn %{module}
cp -p %{SOURCE1} .


%build
# Empty build section, nothing to build


%install
mkdir -pm 0755 %{buildroot}%{module}/%{module}
cp -pr * %{buildroot}%{drupal7_modules}/%{module}/


%files
%doc *.txt
%{drupal7_modules}/%{module}
%exclude %{drupal7_modules}/%{module}/*.txt


%changelog
* ddd MMM DD YYYY __NAME__ <__EMAIL__> __VERSION__-1
- Initial package

Theme

This template is for all versions of Fedora and EPEL 6+. If you are packaging for EPEL 5, see Packaging:Guidelines for additional requirements that need to be added to the spec.
%{?drupal7_find_provides_and_requires}

%global theme  __THEME__

Name:          drupal7-%{theme}
Version:       __VERSION__
Release:       1%{?dist}
Summary:       __SUMMARY__

Group:         Applications/Publishing
License:       GPLv2+
URL:           http://drupal.org/project/%{theme}
Source0:       http://ftp.drupal.org/files/projects/%{theme}-7.x-%{version}.tar.gz
Source1:       %{name}-RPM-README.txt

BuildArch:     noarch
BuildRoot:     %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
BuildRequires: drupal7-rpmbuild >= 7.23-3

# phpcompatinfo (computed from version __VERSION__)
#Requires:      php-

%description
__DESCRIPTION__


%prep
%setup -qn %{theme}
cp -p %{SOURCE1} .


%build
# Empty build section, nothing to build


%install
mkdir -pm 0755 %{buildroot}%{drupal7_themes}/%{theme}
cp -pr * %{buildroot}%{drupal7_themes}/%{theme}/


%files
%doc *.txt
%{drupal7_themes}/%{theme}
%exclude %{drupal7_themes}/%{theme}/*.txt


%changelog
* ddd MMM DD YYYY __NAME__ <__EMAIL__> __VERSION__-1
- Initial package