From Fedora Project Wiki
 
(29 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{admon/warning|This is only a DRAFT!}}
{{admon/warning|This is only a DRAFT!}}


= Guidelines for packaging Drupal 8 modules, themes, and profiles =
= Different Kinds of Packages =
 
== Different Kinds of Packages ==
* '''[http://drupal.org/project/modules Modules]''': Modules extend and customize Drupal functionality.
* '''[http://drupal.org/project/modules Modules]''': Modules extend and customize Drupal functionality.
* '''[http://drupal.org/project/themes Themes]''': Themes allow users to change the look and feel of their Drupal site.
* '''[http://drupal.org/project/themes Themes]''': Themes allow users to change the look and feel of their Drupal site.
* '''[http://drupal.org/project/distributions Distributions/Profiles]''': Distributions/profiles provide site features and functions for a specific type of site.
* '''[http://drupal.org/project/distributions Distributions/Profiles]''': Distributions/profiles provide site features and functions for a specific type of site.


== Naming Scheme ==
= Naming Scheme =
Every package '''MUST''' be named <code>drupal8-''&lt;drupal_project''&gt;</code>.  Drupal itself enforces unique project names for each of its' projects and there is a single namespace for all modules, themes, and distributions/profiles.  The <code>''&lt;drupal_project''&gt;</code> '''MUST''' match the drupal.org project name (i.e. drupal.org/project/<code>''&lt;drupal_project''&gt;</code>).
Every package '''MUST''' be named <code>drupal8-''&lt;drupal_project&gt;''</code>.  Drupal itself enforces unique project names for each of its' projects and there is a single namespace for all modules, themes, and distributions/profiles.  The <code>''&lt;drupal_project''&gt;</code> '''MUST''' match the drupal.org project name (i.e. drupal.org/project/<code>''&lt;drupal_project&gt;''</code>).
 
{{admon/tip|
<pre>Name: %{drupal8_name}</pre>
}}
 
= Required Spec Macro Definitions =
Every package:
* '''MUST''' define "<code>%global drupal8_project &lt;drupal_project&gt;</code>"
** <code>''&lt;drupal_project''&gt;</code> '''MUST''' match the drupal.org project name (i.e. drupal.org/project/<code>''&lt;drupal_project&gt;''</code>)
* '''MUST''' define "<code>%global drupal8_type module/profile/theme</code>"
* '''MUST''' define "<code>%global drupal8_pre_release PRE_RELEASE</code>" if package is a '''pre-release'''
* '''MUST''' define "<code>%global drupal8_commit COMMIT</code>" if package is a '''dev release'''
* '''SHOULD''' define "<code>%global drupal8_commit_date YYYYMMDD</code>" if package is a '''dev release'''


== File Placement ==
= File Placement =
* '''Modules''': A module package '''MUST''' be placed in the <code>%drupal8_modules</code> directory
* '''Modules''': A module package '''MUST''' be placed in the <code>%drupal8_modules</code> directory
* '''Themes''': A theme package '''MUST''' be placed in the <code>%drupal8_themes</code> directory
* '''Themes''': A theme package '''MUST''' be placed in the <code>%drupal8_themes</code> directory
Line 17: Line 28:
* '''Libraries''': A library package '''MUST''' be placed in the <code>%drupal8_libraries</code> directory
* '''Libraries''': A library package '''MUST''' be placed in the <code>%drupal8_libraries</code> directory


== Requires and Provides ==
{{admon/tip|
<pre>%global drupal8_type module/profile/theme
 
%install
%{drupal8_install}
</pre>
}}
 
= Requires and Provides =


Every package '''MUST''' include the following in its' spec:
Every package '''MUST''' include the following in its' spec:
Line 23: Line 42:
<pre>BuildRequires: drupal8-rpmbuild</pre>
<pre>BuildRequires: drupal8-rpmbuild</pre>


The <code>drupal8-rpmbuild</code> package automatically scans files for provides [1] and requires [2] and automatically adds them to the package during build time as "<code>drupal8(<drupal_project>)</code>" and "<code>php-composer(<vendor>/<project>)</code>" virtual resources. 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.
The <code>drupal8-rpmbuild</code> package automatically scans files for [[#Automatic_Requires|requires]] and [[#Automatic_Provides|provides]] and automatically adds them to the package during build time. The use of virtual provides and requires helps alleviate the confusion of sub-projects and which projects actually provide those sub-modules. They also help simplify spec files.
 
== Automatic Requires ==
 
* <code>drupal8(core)</code> is always a requirement
* <code>drupal8(*)</code> requires are only determined from the project's main <code><drupal_project>.info.yml</code> file
** "<code>dependencies</code>" property
* <code>composer.json</code> files are not used for automatic requires because of dependency version formats and minimum Fedora/EPEL version for autoloaders
* Also see [[#Requiring_a_Minimum_PHP_Version|Requiring a Minimum PHP Version]] section
 
== Automatic Provides ==
 
* <code>drupal8(*)</code> virtual provides are determined from all project's <code>*.info.yml</code> file names
* <code>php-composer(*)</code> virtual provides are determined from all project's <code>composer.json</code> files
** <code>name</code> property
** <code>replace</code> property where version = <code>self.version</code>
 
== Drupal Projects ==
 
Every package '''MUST''' use <code>drupal8(*)</code> dependencies for Drupal project dependencies.


[1] From <code>*.info.yml</code> and <code>composer.json</code> filenames<br />
{{admon/note|
[2] From <code>*.info</code> file "dependencies" entries
* See [[#Automatic_Requires|Automatic Requires]]
* For optional sub-project dependencies, [[Packaging:WeakDependencies|weak dependencies]] '''SHOULD''' be used
}}


=== Other Packages ===
== Other Packages ==


See [[Packaging:PHP#Other_Packages|PHP packaging guidelines]].
See [[Packaging:PHP#Other_Packages|PHP packaging guidelines: Other Packages]].


=== PHP Extensions ===
== PHP Extensions ==


See [[Packaging:PHP#Extensions_Requires|PHP packaging guidelines]].
See [[Packaging:PHP#Extensions_Requires|PHP packaging guidelines: Extensions Requires]].


=== 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]).
Since all packages require <code>drupal8(core)</code> which requires Drupal 8's minimum PHP version, most packages do not need to require a minimum PHP version.  If packages require a minimum PHP version greater than Drupal 8's minimum version, the project maintainers should have the minimum version provided in the project's main <code>*.info.yml</code> file and <code>drupal8-rpmbuild</code> will automatically find and require the minimum PHP version.
{{admon/important|This needs to be added to the <code>drupal8-rpmbuild</code> package so it is automatic.}}


== Macros and Scriptlets ==
= Macros and Scriptlets =


Macros provided by the <code>drupal8-rpmbuild</code> package:
Macros provided by the <code>drupal8-rpmbuild</code> package:
Line 47: Line 86:
! Macro !! Value !! Description
! Macro !! Value !! Description
|-
|-
| <code>%drupal8_version</code> || ''8.x.y<sup>*</sup>'' || Drupal 8 version.<br />''* Value is dynamically updated by the Drupal 8 core package.''
| <code>%drupal8_core_version</code> || <code>8.*.*</code> <sup>*</sup>'' || Drupal 8 core version.<br />
|-
| <code>%drupal8_php_min_ver</code> || <code>5.5.9</code> <sup>*</sup>'' || Drupal 8 core minimum PHP version requirement.<br />
|-
|-
| <code>%drupal8</code> || <code>%{_datadir}/drupal8</code> || Drupal 8 base directory.
| <code>%drupal8</code> || <code>%{_datadir}/drupal8</code> || Drupal 8 base install directory.
|-
|-
| <code>%drupal8_modules</code> || <code>%{drupal8}/modules</code> ||  Drupal 8 modules directory.
| <code>%drupal8_modules</code> || <code>%{drupal8}/modules/rpm</code> <sup>**</sup> ||  Drupal 8 modules install directory.
|-
|-
| <code>%drupal8_profiles</code> || <code>%{drupal8}/profiles</code> ||  Drupal 8 profiles directory.
| <code>%drupal8_profiles</code> || <code>%{drupal8}/profiles/rpm</code> <sup>**</sup> ||  Drupal 8 profiles install directory.
|-
|-
| <code>%drupal8_themes</code> || <code>%{drupal8}/themes</code> ||  Drupal 8 themes directory.
| <code>%drupal8_themes</code> || <code>%{drupal8}/themes/rpm</code> <sup>**</sup> ||  Drupal 8 themes install directory.
|-
|-
| <code>%drupal8_libraries</code> || <code>%{drupal8}/libraries</code> || Drupal 8 library directory.
| <code>%drupal8_libraries</code> || <code>%{drupal8}/libraries</code> || Drupal 8 libraries install directory.
|-
|-
| <code>%drupal8_var</code> || <code>%{_localstatedir}/lib/drupal8</code> || Drupal 8 var directory.
| <code>%drupal8_var</code> || <code>%{_localstatedir}/lib/drupal8</code> || Drupal 8 var directory.
{{admon/note|
* Files are located in <code>%{drupal8_var}/files/[public,private]/[site]</code>
* <code>%{drupal8_conf}/sites/default/files</code> symlinks to <code>%{drupal8_var}/files/public/default</code>
}}
|-
|-
| <code>%drupal8_conf</code> || <code>%{_sysconfdir}/drupal8</code> || Drupal 8 conf directory.
| <code>%drupal8_conf</code> || <code>%{_sysconfdir}/drupal8</code> || Drupal 8 conf directory.
{{admon/note|
* <code>%{drupal8}/sites</code> symlinks to <code>%{drupal8_conf}/sites</code>
* Site configurations are located in <code>%{drupal8_conf}/sites/[site]</code>
}}
|-
| <code>%drupal8_name</code> || <code>drupal8-%{drupal8_project}</code> || Spec name.
|-
| <code>%drupal8_release</code> || <code>%{?drupal8_pre_release:.%{drupal8_pre_release}}%{?drupal8_commit:.%{?drupal8_commit_date}git%(c=%{drupal8_commit}; echo ${c:0:7})}%{?dist}</code> || Spec release.
|-
| <code>%drupal8_url</code> || <code>https://www.drupal.org/project/%{drupal8_project}</code> || Spec URL.
|-
| <code>%drupal8_source</code> || <code>%{!?drupal8_commit:https://ftp.drupal.org/files/projects/%{drupal8_project}-8.x-%{?version}%{?drupal8_pre_release:-%{drupal8_pre_release}}.tar.gz}%{?drupal8_commit:%{drupal8_project}-8.x-%{?version}-%{drupal8_commit}.tar.gz}</code>
<br />
<br />
Broken out:
* Without <code>%drupal8_commit</code> defined:
<code>https://ftp.drupal.org/files/projects/%{drupal8_project}-8.x-%{?version}%{?drupal8_pre_release:-%{drupal8_pre_release}}.tar.gz</code>
* With <code>%drupal8_commit</code> defined:
<code>%{drupal8_project}-8.x-%{?version}-%{drupal8_commit}.tar.gz</code>
|| Spec source.
<br />
{{admon/important|
With <code>%drupal8_commit</code> defined, source is generated by running:<br />
<code>/usr/lib/rpm/drupal8-get-dev-source.sh SPEC</code>
}}
|-
| <code>%drupal8_files</code> || <code>.rpm/files.txt</code> || Package files list.
* Generated by <code>%drupal8_install</code>
* Used in spec as "<code>%files -f %{drupal8_files}</code>"
|-
| <code>%drupal8_prep</code> || <code>%setup -qn %{drupal8_project} \<br />
%{_rpmconfigdir}/drupal8-prep-licenses-and-docs.sh</code>
|| Prep scriptlet used in <code>%prep</code>.
|-
| <code>%drupal8_install</code> || <code>%define drupal8_type_dir %{expand:%%{drupal8_%{drupal8_type}s}} \<br />
mkdir -p %{buildroot}%{drupal8_type_dir}/%{drupal8_project} \<br />
cp -pr * %{buildroot}%{drupal8_type_dir}/%{drupal8_project}/ \<br />
cp .rpm/licenses-and-docs.txt .rpm/files.txt \<br />
echo "%{drupal8_type_dir}/%{drupal8_project}" >> .rpm/files.txt \<br />
cat .rpm/files.txt</code>
|| Install scriptlet used in <code>%install</code>.
|}
|}


== Additional Hints ==
''* Value is dynamically updated by the Drupal 8 core package.''


== Template ==
''** <code>rpm</code> sub-directory so RPM-installed Drupal projects are separated from manually installed Drupal projects.''


{{admon/note|Replace <code>%{__TYPE_MACRO__}</code> in the template below with the actual macro name matching the project type:
= Template =
* <code>%{drupal8_modules}</code> for modules
* <code>%{drupal8_profiles}</code> for profiles
* <code>%{drupal8_themes}</code> for themes}}


<pre>
<pre>
%global drupal_project __DRUPAL_PROJECT__
%global drupal8_project    __DRUPAL8_PROJECT__
%global drupal8_type        module/profile/theme
#%%global drupal8_pre_release
#%%global drupal8_commit
#%%global drupal8_commit_date


Name:          drupal8-%{drupal_project}
Name:          %{drupal8_name}
Version:      __VERSION__
Version:      __VERSION__
Release:      1%{?dist}
Release:      1%{drupal8_release}
Summary:      __SUMMARY__
Summary:      __SUMMARY__


Group:        Applications/Publishing
License:      GPLv2+
License:      GPLv2+
URL:          https://www.drupal.org/project/%{drupal_project}
URL:          %{drupal8_url}
Source0:      https://ftp.drupal.org/files/projects/%{drupal_project}-8.x-%{version}.tar.gz
Source0:      %{drupal8_source}


BuildArch:    noarch
BuildArch:    noarch
Line 91: Line 179:
%description
%description
__DESCRIPTION__
__DESCRIPTION__
This package provides the following Drupal project(s):
* %{drupal_project}




%prep
%prep
%setup -qn %{drupal_project}
%{drupal8_prep}
 
: Licenses and docs
mkdir -p .rpm/{licenses,docs}
mv LICENSE.txt .rpm/licenses/
mv composer.json .rpm/docs/




Line 110: Line 190:


%install
%install
mkdir -p %{buildroot}''%{__TYPE_MACRO__}''/%{drupal_project}
%{drupal8_install}
cp -pr * %{buildroot}''%{__TYPE_MACRO__}''/%{drupal_project}/




%files
%files -f %{drupal8_files}
%license .rpm/licenses/*
%doc .rpm/docs/*
%{drupal8_modules}/%{drupal_project}




Line 124: Line 200:
- Initial package
- Initial package
</pre>
</pre>
=== Distribution/Profile ===

Latest revision as of 19:03, 28 January 2016

This is only a DRAFT!

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.
  • Distributions/Profiles: Distributions/profiles provide site features and functions for a specific type of site.

Naming Scheme

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

Name: %{drupal8_name}

Required Spec Macro Definitions

Every package:

  • MUST define "%global drupal8_project <drupal_project>"
    • <drupal_project> MUST match the drupal.org project name (i.e. drupal.org/project/<drupal_project>)
  • MUST define "%global drupal8_type module/profile/theme"
  • MUST define "%global drupal8_pre_release PRE_RELEASE" if package is a pre-release
  • MUST define "%global drupal8_commit COMMIT" if package is a dev release
  • SHOULD define "%global drupal8_commit_date YYYYMMDD" if package is a dev release

File Placement

  • Modules: A module package MUST be placed in the %drupal8_modules directory
  • Themes: A theme package MUST be placed in the %drupal8_themes directory
  • Distributions/Profiles: A distribution/profile package MUST be placed in the %drupal8_profiles directory
  • Libraries: A library package MUST be placed in the %drupal8_libraries directory
%global drupal8_type module/profile/theme

%install
%{drupal8_install}

Requires and Provides

Every package MUST include the following in its' spec: 

BuildRequires: drupal8-rpmbuild

The drupal8-rpmbuild package automatically scans files for requires and provides and automatically adds them to the package during build time. The use of virtual provides and requires helps alleviate the confusion of sub-projects and which projects actually provide those sub-modules. They also help simplify spec files.

Automatic Requires

  • drupal8(core) is always a requirement
  • drupal8(*) requires are only determined from the project's main <drupal_project>.info.yml file
    • "dependencies" property
  • composer.json files are not used for automatic requires because of dependency version formats and minimum Fedora/EPEL version for autoloaders
  • Also see Requiring a Minimum PHP Version section

Automatic Provides

  • drupal8(*) virtual provides are determined from all project's *.info.yml file names
  • php-composer(*) virtual provides are determined from all project's composer.json files
    • name property
    • replace property where version = self.version

Drupal Projects

Every package MUST use drupal8(*) dependencies for Drupal project dependencies.


Other Packages

See PHP packaging guidelines: Other Packages.

PHP Extensions

See PHP packaging guidelines: Extensions Requires.

Requiring a Minimum PHP Version

Since all packages require drupal8(core) which requires Drupal 8's minimum PHP version, most packages do not need to require a minimum PHP version. If packages require a minimum PHP version greater than Drupal 8's minimum version, the project maintainers should have the minimum version provided in the project's main *.info.yml file and drupal8-rpmbuild will automatically find and require the minimum PHP version.

Macros and Scriptlets

Macros provided by the drupal8-rpmbuild package:

Macro Value Description
%drupal8_core_version 8.*.* * Drupal 8 core version.
%drupal8_php_min_ver 5.5.9 * Drupal 8 core minimum PHP version requirement.
%drupal8 %{_datadir}/drupal8 Drupal 8 base install directory.
%drupal8_modules %{drupal8}/modules/rpm ** Drupal 8 modules install directory.
%drupal8_profiles %{drupal8}/profiles/rpm ** Drupal 8 profiles install directory.
%drupal8_themes %{drupal8}/themes/rpm ** Drupal 8 themes install directory.
%drupal8_libraries %{drupal8}/libraries Drupal 8 libraries install directory.
%drupal8_var %{_localstatedir}/lib/drupal8 Drupal 8 var directory.
  • Files are located in %{drupal8_var}/files/[public,private]/[site]
  • %{drupal8_conf}/sites/default/files symlinks to %{drupal8_var}/files/public/default

%drupal8_conf %{_sysconfdir}/drupal8 Drupal 8 conf directory.
  • %{drupal8}/sites symlinks to %{drupal8_conf}/sites
  • Site configurations are located in %{drupal8_conf}/sites/[site]

%drupal8_name drupal8-%{drupal8_project} Spec name.
%drupal8_release %{?drupal8_pre_release:.%{drupal8_pre_release}}%{?drupal8_commit:.%{?drupal8_commit_date}git%(c=%{drupal8_commit}; echo ${c:0:7})}%{?dist} Spec release.
%drupal8_url https://www.drupal.org/project/%{drupal8_project} Spec URL.
%drupal8_source %{!?drupal8_commit:https://ftp.drupal.org/files/projects/%{drupal8_project}-8.x-%{?version}%{?drupal8_pre_release:-%{drupal8_pre_release}}.tar.gz}%{?drupal8_commit:%{drupal8_project}-8.x-%{?version}-%{drupal8_commit}.tar.gz}



Broken out:

  • Without %drupal8_commit defined:

https://ftp.drupal.org/files/projects/%{drupal8_project}-8.x-%{?version}%{?drupal8_pre_release:-%{drupal8_pre_release}}.tar.gz

  • With %drupal8_commit defined:

%{drupal8_project}-8.x-%{?version}-%{drupal8_commit}.tar.gz

Spec source.


With %drupal8_commit defined, source is generated by running:
/usr/lib/rpm/drupal8-get-dev-source.sh SPEC


%drupal8_files .rpm/files.txt Package files list.
  • Generated by %drupal8_install
  • Used in spec as "%files -f %{drupal8_files}"
%drupal8_prep %setup -qn %{drupal8_project} \

%{_rpmconfigdir}/drupal8-prep-licenses-and-docs.sh

Prep scriptlet used in %prep.
%drupal8_install %define drupal8_type_dir %{expand:%%{drupal8_%{drupal8_type}s}} \

mkdir -p %{buildroot}%{drupal8_type_dir}/%{drupal8_project} \
cp -pr * %{buildroot}%{drupal8_type_dir}/%{drupal8_project}/ \
cp .rpm/licenses-and-docs.txt .rpm/files.txt \
echo "%{drupal8_type_dir}/%{drupal8_project}" >> .rpm/files.txt \
cat .rpm/files.txt

Install scriptlet used in %install.

* Value is dynamically updated by the Drupal 8 core package.

** rpm sub-directory so RPM-installed Drupal projects are separated from manually installed Drupal projects.

Template

%global drupal8_project     __DRUPAL8_PROJECT__
%global drupal8_type        module/profile/theme
#%%global drupal8_pre_release
#%%global drupal8_commit
#%%global drupal8_commit_date

Name:          %{drupal8_name}
Version:       __VERSION__
Release:       1%{drupal8_release}
Summary:       __SUMMARY__

License:       GPLv2+
URL:           %{drupal8_url}
Source0:       %{drupal8_source}

BuildArch:     noarch
BuildRequires: drupal8-rpmbuild

%description
__DESCRIPTION__


%prep
%{drupal8_prep}


%build
# Empty build section, nothing to build


%install
%{drupal8_install}


%files -f %{drupal8_files}


%changelog
* ddd MMM DD YYYY __NAME__ <__EMAIL__> __VERSION__-1
- Initial package
Retrieved from "https://fedoraproject.org/w/index.php?title=User:Siwinski/Draft:Packaging:Drupal8&oldid=433177"