221 lines
7.5 KiB
Plaintext
221 lines
7.5 KiB
Plaintext
= rubygem-asciidoctor: Asciidoctor RPM package spec
|
|
Dan Allen
|
|
:idprefix:
|
|
:idseparator: -
|
|
:compat-mode!:
|
|
:gem_title: Asciidoctor
|
|
:gem_name: asciidoctor
|
|
:gem_version: 1.5.2
|
|
:gem_gem: {gem_name}-{gem_version}.gem
|
|
:gem_url: https://github.com/asciidoctor/asciidoctor
|
|
:rpm_name: rubygem-{gem_name}
|
|
:rpm_rpm: {rpm_name}-{gem_version}.rpm
|
|
:rpm_repo: git://github.com/asciidoctor/rubygem-asciidoctor-rpm.git
|
|
|
|
This repository is the official host of the build materials to create the Fedora RPM package for the https://github.com/asciidoctor/asciidoctor[Asciidoctor] Ruby Gem.
|
|
The RPM package is named `rubygem-asciidoctor`.
|
|
|
|
While this RPM spec was developed specifically for Fedora 18 and above, it may be useful for other RPM-based systems.
|
|
|
|
== Build the Asciidoctor RPM
|
|
|
|
If you want to build the RPM on your own machine, follow the instructions in this section.
|
|
If you want to test a pre-built package, skip to the next section on <<test-the-asciidoctor-rpm-and-report-feedback,testing the RPM>>.
|
|
|
|
=== Preparing your environment
|
|
|
|
You first need to install the packages necessary to build the RPM.
|
|
Begin by installing the `@fedora-packager` group (as root or using sudo):
|
|
|
|
yum install -y @fedora-packager wget
|
|
|
|
Next, clone this repository and switch to it:
|
|
|
|
git clone git://github.com/asciidoctor/rubygem-asciidoctor-rpm.git
|
|
cd rubygem-asciidoctor-rpm
|
|
|
|
Finally, install the packages that this build requires (as root or using sudo):
|
|
|
|
yum-builddep rubygem-asciidoctor.spec
|
|
|
|
Next, we need to put the package source and patches in place.
|
|
|
|
=== Preparing the sources
|
|
|
|
You can build RPMs as a non-privileged user, though you need to prepare the directories first.
|
|
Let's use the directory rpmbuild in our `$HOME` directory:
|
|
|
|
echo "%_topdir %(echo $HOME)/rpmbuild" > $HOME/.rpmmacros
|
|
|
|
You'll also need to create all the required folders:
|
|
|
|
mkdir -p $HOME/rpmbuild/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS}
|
|
|
|
Next, grab the Asciidoctor gem (the sources) and put it into the `$HOME/rpmbuild/SOURCES` directory:
|
|
|
|
wget -O $HOME/rpmbuild/SOURCES/asciidoctor-1.5.2.gem http://rubygems.org/gems/asciidoctor-1.5.2.gem
|
|
|
|
Finally, copy the `.patch` files from this repository to the same directory:
|
|
|
|
cp *.patch $HOME/rpmbuild/SOURCES/
|
|
|
|
You're now ready to build the RPM.
|
|
|
|
=== Building the RPM
|
|
|
|
With everything in place, building the RPM is easy!
|
|
|
|
rpmbuild -ba rubygem-asciidoctor.spec
|
|
|
|
If all goes well, both the binary and source RPMs will emerge in the `$HOME/rpmbuild/RPMS/noarch` and `$HOME/rpmbuild/SRPMS` directories, respectively.
|
|
|
|
Alternatively, you can build directly from the SRPM.
|
|
|
|
wget -P srpms http://kojipkgs.fedoraproject.org/packages/rubygem-asciidoctor/1.5.2/1.fc21/src/rubygem-asciidoctor-1.5.2-1.fc21.src.rpm
|
|
rpmbuild --rebuild srpms/rubygem-asciidoctor-1.5.2-1.fc21.src.rpm
|
|
|
|
The SPRMs are stored with the builds in the http://koji.fedoraproject.org/koji/packageinfo?packageID=15660[koji build system].
|
|
|
|
=== Installing the RPM
|
|
|
|
There's nothing special about installing this RPM.
|
|
I recommend using `yum` because it will install any dependencies that the package requires (though you should already have them if you built the RPM).
|
|
|
|
yum install -y $HOME/rpmbuild/RPMS/noarch/rubygem-asciidoctor-1.5.2.rpm
|
|
|
|
Now, it's time to start using Asciidoctor!
|
|
|
|
== Test the Asciidoctor RPM and report feedback
|
|
|
|
Before the Asciidoctor package (`rubygem-asciidoctor`) can be included in the Fedora distribution, it must be tested by users and receive karma via the http://admin.fedoraproject.org/updates[Bohdi system].
|
|
One way to provide this feedback is to use the http://admin.fedoraproject.org/pkgdb/acls/name/fedora-easy-karma[fedora-easy-karma] tool.
|
|
|
|
=== Enable the updates-testing repository temporarily
|
|
|
|
In a terminal, type:
|
|
|
|
yum install -y rubygem-asciidoctor --enablerepo=updates-testing
|
|
|
|
This command will download and install the asciidoctor package.
|
|
|
|
=== Test the Asciidoctor API
|
|
|
|
First, let's test using Asciidoctor as a Ruby library.
|
|
|
|
. On your computer, create a new file and name it `asciidoctor-test.rb`
|
|
. Copy and paste the following code into the file:
|
|
+
|
|
[source,ruby]
|
|
----
|
|
require 'asciidoctor'
|
|
content = "= My First Document\n\nRender me some **HTML**!"
|
|
puts Asciidoctor.render content, :header_footer => true
|
|
----
|
|
|
|
. Save the file.
|
|
. In a terminal, navigate to the directory where you saved `asciidoctor-test.rb` and type the following command to execute the file with Ruby:
|
|
|
|
ruby asciidoctor-test.rb
|
|
+
|
|
You should see this output in your terminal.
|
|
+
|
|
[source,html]
|
|
----
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<meta name="generator" content="Asciidoctor 1.5.2">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>My First Document</title>
|
|
<link rel="stylesheet" href="./asciidoctor.css">
|
|
</head>
|
|
<body class="article">
|
|
<div id="header">
|
|
<h1>My First Document</h1>
|
|
</div>
|
|
<div id="content">
|
|
<div id="preamble">
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Render me some <strong>HTML</strong>!</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="footer">
|
|
<div id="footer-text">
|
|
Last updated 2013-09-22 17:35:41 MDT
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|
|
----
|
|
|
|
. You can render the output as HTML using:
|
|
|
|
ruby asciidoctor-test.rb > asciidoctor-test.html
|
|
|
|
. Open your browser to see the result.
|
|
. Alternatively, if you're using Gnome, type:
|
|
|
|
gnome-open asciidoctor-test.html
|
|
+
|
|
A new tab should open in your current browser session.
|
|
|
|
=== Test the Asciidoctor CLI
|
|
|
|
Now let's test using the Asciidoctor executable (i.e., CLI).
|
|
|
|
. On your computer, create a new file and name it [path]_test.adoc_
|
|
. Copy and paste the following markup into the file:
|
|
+
|
|
----
|
|
= My Second Document
|
|
Your Name
|
|
|
|
AsciiDoc is _rockin'_ docs.
|
|
----
|
|
|
|
. Save the file
|
|
. In a terminal, navigate to the directory where you saved [path]_test.adoc_ and type the following command to run it through the Asciidoctor processor:
|
|
|
|
asciidoctor test.adoc
|
|
+
|
|
You shouldn't see any output in your terminal.
|
|
That's because it writes the output to the file `test.html`.
|
|
|
|
. Open your browser to see the result.
|
|
. Alternatively, if you're using Gnome, type:
|
|
|
|
gnome-open test.html
|
|
+
|
|
A new tab should open in your current browser session.
|
|
|
|
=== Provide feedback with fedora-easy-karma
|
|
|
|
. If you don't have fedora-easy-karma installed on your computer, type the following command in a terminal.
|
|
|
|
yum install -y fedora-easy-karma
|
|
|
|
. Once fedora-easy-karma is installed, run it in the terminal.
|
|
|
|
fedora-easy-karma --fas-username <yourFASaccount> *asciidoctor
|
|
+
|
|
--
|
|
To be on the safe side, include the flag for your FAS account when you start fedora-easy-karma.
|
|
Once fedora-easy-karma runs, you will not be able to switch accounts.
|
|
|
|
NOTE: It may take fedora-easy-karma several minutes to fetch the list of packages in updates-testing.
|
|
|
|
When fedora-easy-karma finds `rubygem-asciidoctor`, it will display a summary of the package and prompt you to give -1 (negative), 0 (neutral), or 1 (postive) karma to the package.
|
|
For more information about providing karma for packages and how to comment on packages, review the http://fedoraproject.org/wiki/QA:Update_feedback_guidelines[Fedora feedback guidelines].
|
|
--
|
|
|
|
. Enter your karma rating.
|
|
. Next, you will be asked to provide additional, detailed feedback.
|
|
Please comment whether the package worked as expected and you successfully used it, if you think you may have encountered an error, but aren't sure, or if you definitely encountered a bug.
|
|
. When prompted, enter your FAS password.
|
|
. W00t! The feedback process is complete.
|
|
. You can verify your feedback was recorded by visiting the https://admin.fedoraproject.org/updates[Bodhi updates page].
|