From Fedora Project Wiki

Line 24: Line 24:
= Using Eclipse Fedorapackager =
= Using Eclipse Fedorapackager =


Since release 14 Fedora uses the Git version control system for keeping track of files required for Fedora packaging. See the [https://fedoraproject.org/wiki/Dist_Git_Project dist-git documentation] for in depth information about dist-git. Fortunately, you don't have to worry about how dist-git works when you are using the Eclipse Fedora Packager plug-in, except for the slightly different approach of doing your packaging work (compared to what you might have been used to when using CVS instead of Git).
Since Fedora 14, the Git version control system for keeping track of files required for Fedora packaging is used. See the [https://fedoraproject.org/wiki/Dist_Git_Project dist-git documentation] for in depth information about dist-git. Fortunately, how dist-git works when using the Eclipse Fedora Packager plug-in is unimportant. There is only a slightly different approach for doing packaging work compared to what might have been used with CVS instead of Git.


== Initial Setup ==
== Initial Setup ==


Note that this step is only required once if you are a new Fedora packager or if you are on a new machine, which does not have required FAS certificates installed. If you are sure you are properly set up, you may safely skip this step. How would you set up those certificates for your [https://admin.fedoraproject.org/accounts/ FAS account]?
This step is only required to be completed once for a new Fedora packager or if using a new machine that does not have required FAS certificates installed. When it is certain the set up is correct it is safe to skip this step. The following explains how to set up those certificates for a [https://admin.fedoraproject.org/accounts/ FAS account]?


First, install the <code>fedora-packager</code> RPM package:
First, install the <code>fedora-packager</code> RPM package:
Line 36: Line 36:
</pre>
</pre>


Then, on a terminal run the following command and simply follow the instructions provided:
Then run the following command and simply follow the instructions provided:  


<pre>
<pre>
Line 42: Line 42:
</pre>
</pre>


Once this is done, you are ready to use Eclipse Fedorapackager. Fire up Eclipse. Let's get started. Yay!
Once this is done Eclipse Fedorapackager is ready for use. Fire up Eclipse. Let's get started. Yay!


== Importing a Fedora Git Project ==
== Importing a Fedora Git Project ==


Getting started is easy. Go to "File" => "Import" => "Git" => "Projects from Fedora Git". This will clone the desired Git repository and will create necessary local branches for you. Also for your convenience the "Git Repositories" view will open once the clone process has finished.
Getting started is easy. Go to "File" => "Import" => "Git" => "Projects from Fedora Git". This will clone the desired Git repository and create necessary local branches. For convenience, the "Git Repositories" view will also open once the clone process has finished.  


[[Image:ImportFedoraGit.png]]
[[Image:ImportFedoraGit.png]]


Here's how the Fedora Git import dialog looks like. Next, you specify the package name which will then be prepared for you.
Here's how the Fedora Git import dialog looks like. Next, specify the package name that will then be prepared for you.  


[[Image:SelectPackageNameGit.png|Image:SelectPackageNameGit.png]]
[[Image:SelectPackageNameGit.png|Image:SelectPackageNameGit.png]]


Once the new project has been created you'll see something like the following. Note the branches in the Git Repository view and "[eclipse-fedorapackager master]" right beside the project name. ''eclipse-fedorapackager'' in this case refers to the Git repository name and ''master'' to the currently checked out branch.
Once the new project has been created something akin to the following is seen. Note the branches in the Git Repository view and "[eclipse-fedorapackager master]" right beside the project name. In this case, ''eclipse-fedorapackager'' refers to the Git repository name and ''master'' to the currently checked out branch.


[[Image:GitProjectBranchesView.png]]
[[Image:GitProjectBranchesView.png]]
Line 60: Line 60:
== Do Your Fedora Packaging Work ==
== Do Your Fedora Packaging Work ==


After your Fedora Git project has been created you will find all files required for packaging the desired release (e.g. Fedora 13, which would correspond to branch '''f13/master'''. Branch '''master''' corresponds to '''Fedora rawhide''', the current development release of Fedora). What follows is a brief description of things you might want to do while packaging up some software. You may choose to do work in a different sequence, but keep in mind that you have to '''push your locally committed changes to the public repository''' before you try a Koji build.
After a Fedora Git project has been created, all files required for packaging the desired release can be found in the corresponding directory. For example, Fedora 13 corresponds to branch '''f13/master'''. Branch '''master''' corresponds to '''Fedora rawhide''', the current development release of Fedora. WThe following is a brief description of things to consider doing while packaging up some software. Working in a different sequence works, but keep in mind that before trying a Koji build '''push your locally committed changes to the public repository'''.


=== Uploading Source Files Required for Your Package ===
=== Uploading Source Files Required for a Package ===


In order to upload new sources in Eclipse Fedorapackager you first have to download upstream sources somehow and put downloaded sources in the folder of your Eclipse project. If you do this outside of Eclipse, don't forget to refresh the project afterwards (F5) so that the file actually shows up. A slick way to download sources is to use RPM editor functionality directly. See its documentation for more information on this. Once you have the new source file available in your project you can upload it to the lookaside cache by right-clicking on the file => Fedora Packager => Upload This File => Replace/Add file. This either adds the file to the sources required to build your package or replaces the current content of the <code>sources</code> file to contain a single line with the MD5 sum of the file you had selected.
In order to upload new sources in Eclipse Fedorapackager, first download upstream sources and place the downloaded sources in the same folder as the Eclipse project. If this is done outside of Eclipse, don't forget to refresh the project afterwards (F5) so that the file actually shows up. A slick way to download sources is to use RPM editor functionality directly. See its documentation for more information on this. Once the new source file is available in the project, it can be uploaded to the lookaside cache by right-clicking on the file=> Fedora Packager => Upload This File => Replace/Add File. This either adds the file to the sources required to build the package or replaces the current content of the <code>sources</code> file to contain a single line with the MD5 sum of the file selected.  


Note you have to have a valid certificate to be able to upload to the lookaside cache. Your certificate may have expired. If it has, you can create a new one by issuing the following command on a terminal:
A valid certificate is required to upload to the lookaside cache. If it has expired, a new one can be created by issuing the following command on a terminal:


<pre>
<pre>
Line 72: Line 72:
</pre>
</pre>


=== Downloading Source Files Required for Your Package ===
=== Downloading Source Files Required for a Package ===


If you want to download required source files for an existing package in order to build it, you can do so by right-clicking on your spec-file => Fedora Packager => Download Sources. This downloads all sources listed in the file <code>sources</code>.
To download the required source files for an existing package in order to build it, right-click on the spec-file => Fedora Packager => Downloaded Sources. This downloads all sources listed in the file <code>sources</code>.


=== Using the Spec-File Editor ===
=== Using the Spec-File Editor ===


Eclipse Fedora Packager uses the RPM Editor and ChangeLog plug-in of the Eclipse Linux Tools project (http://www.eclipse.org/linuxtools). For instance you can easily create a new ChangeLog entry in your spec file by using the <CTRL>+<ALT>+C keyboard shortcut (you may want to set appropriate "ChangeLog" preferences first). Using <CTRL>+<SPACE> auto-completes locally installed packages. Also, you can run rpmlint by right-clicking on your spec file => "Run Rpmlint". For more information have a look at the spec file editor screencast: http://www.eclipse.org/downloads/download.php?file=/technology/linuxtools/videos/specfile-demo.ogg or at the "Specfile Editor User Guide": Help => Help Contents => Specfile Editor User Guide.
Eclipse Fedora Packager uses the RPM Editor and ChangeLog plug-in from the Eclipse Linux Tools project (http://www.eclipse.org/linuxtools). For instance, a new ChangeLog entry can easily be created in the spec file by using the <CTRL>+<ALT>+C keyboard shortcut (though a good idea is to set appropriate “ChangeLog” preferences first). Using <CTRL>+<SPACE> auto-completes locally installed packages. Also, rpmlint can be run by right-clicking on the spec file => “Run Rpmlint”. For more information have a look at the spec file editor screencast: http://www.eclipse.org/downloads/download.php?file=/technology/linuxtools/videos/specfile-demo.ogg or at the "Specfile Editor User Guide": Help => Help Contents => Specfile Editor User Guide.


=== Committing Changes to Your Local Git Repository ===
=== Committing Changes to the Local Git Repository ===


After you've added/changed your spec-file, patches, etc. you want to commit those changes to your repository. You can do so by:
After the spec-file, patches etc. have been added/changed, commit those changes to the repository. This is done by:


# Selecting the files you want to commit (alternatively select your Fedora Git project and select desired ''unstaged'' files when the commit dialog is shown)
# Selecting the files to commit (alternatively select the Fedora Git project and select desired ''unstaged'' files when the commit dialog is shown)
# Right-click, "Team" => "Commit..."
# Right-click, "Team" => "Commit..."


Line 91: Line 91:
=== Switching Branches (Git Checkout) ===
=== Switching Branches (Git Checkout) ===


Switching branches is as easy as double-clicking on the desired local branch you'd like to work on. The currently checked out branch is indicated to the left of the project name. Please make sure to commit, revert or stash changes before you switch to a different branch. Please refer to the Git/EGit documentation for more information on this.
Switching branches is as easy as double-clicking on the desired local branch to be worked on. The currently checked out branch is indicated to the left of the project name. Make sure to commit, revert, or stash changes before switching to a different branch. Refer to the Git/EGit documentation for more information on this.


=== Prepare Sources for a Local Build ===
=== Prepare Sources for a Local Build ===


Eclipse Fedora Packager will download and prepare sources right-clicking on the spec-file => "Fedora Packager" => "Prepare Sources for Build"
Eclipse Fedora Packager will download and prepare sources by right-clicking on the spec-file => “Fedora Packager” => “Prepare Sources for Build”.


[[Image:PrepareSourcesForBuild.png]]
[[Image:PrepareSourcesForBuild.png]]


=== Build RPM for Your Local Architecture ===
=== Build RPM for a Local Architecture ===


This is a great way to test if your spec-file actually builds at all. Once you've successfully built your RPM locally, I recommend to further test your spec-file by doing a build in a chroot'ed environment using {{{mock}}}. Both ways are supported by Eclipse Fedorapackager.
This is a great way to test if the spec-file actually builds at all. Once the RPM has been successfully built locally, it is recommended further testing be carried out on the spec-file by completing a build in a chroot'ed environment using {{{mock}}}. Both ways are supported by Eclipse Fedorapackager.


You can build your RPM locally by selecting the spec-file => right click => "Fedora Packager" => "Build for Local Architecture". You should see output of the RPM build on your Eclipse console.
The RPM can be built locally by selecting the spec-file => right-click => “Fedora Packager” => “Build for Local Architecture”. Output of the RPM build will appear on the Eclipse console.


Using mock-builds is a great way to test "Requires/BuildRequires" of your spec-file. Select your spec-file => right click => "Fedora Packager" => "Local Build Using Mock". Just be aware that this might take a long time (> 20 minutes) and requires you to have the <code>mock</code> package installed. For convenience, you may want to use Eclipse's "Run in Background" functionality.
Using mock-builds is a great way to test the “Requires/BuildRequires” of a spec-file. Select the spec-file => right-click => “Fedora Packager” => “Local Build Using Mock”. Be aware that this may take a long time (>20 minutes) and requires the mock package to be installed. Use Eclipse's “Run in Background” functionality for convenience.


=== Make Locally Committed Changes Public (Git Push) ===
=== Make Locally Committed Changes Public (Git Push) ===


When you are satisfied with your locally committed changes, you are ready to push (or publish) your changes publicly. Remember, Git allows you to rewrite history before you make your changes public. See Git/EGit documentation for more information. Here are the steps required to bring your local repository in synch with ''origin'':
The changes are ready to be pushed (or published) publicly when the locally committed changes are satisfying. Remember, Git allows history to be rewritten before changes are made public. See the Git/EGit documentation for more information. To bring the local repository in sync with ''origin'':


# Select the Fedora Git project
# Select the Fedora Git project
# Right-click, "Team" => "Push..."
# Right-click, "Team" => "Push..."
# Select the Git repository you want to push to (usually you want to keep this unchanged)
# Select the Git repository to be pushed to (usually this is kept unchanged)
# Select Git references you want to push
# Select the Git references to be pushed
# Carry out the push operation
# Carry out the push operation


Line 121: Line 121:
[[Image:GitPushDialog.png|Git push dialog]]
[[Image:GitPushDialog.png|Git push dialog]]


Select the Git references to push. In this example branches ''master'' and ''f14/master'' will get pushed. Keep in mind that source and destination references are the same for Eclipse Fedora Packager. You may also choose to click the "Add all branches spec" button for convenience, which would push commits to all of your local branches.
Select the Git references to push. In this example, branches ''master'' and ''f14/master'' will get pushed. Keep in mind that source and destination references are the same for Eclipse Fedora Packager. Clicking the “Add all branches spec” button is a convenience that pushes all commits to all local branches.


[[Image:SelectGitReferencesToPush.png|Select Git References]]
[[Image:SelectGitReferencesToPush.png|Select Git References]]
Line 127: Line 127:
=== Pushing a Build to Koji ===
=== Pushing a Build to Koji ===


Once you are satisfied with your spec file, make sure to upload sources of your package, commit your changes to your local repository and then push your local changes to the remote repository. When this is done, you can push a build to Koji by right-clicking on your spec file => "Fedora Packager" => "Push Build to Koji".
Once satisfied with a spec file, upload the sources of the package, commit the changes to the local repository, and then push the local changes to the remote repository. When this is done, push a build to Koji by right-clicking the spec file => “Fedora Packager” => “Push to Koji”.


[[Image:EclipseFedoraPackagerPushBuildToKoji.png]]
[[Image:EclipseFedoraPackagerPushBuildToKoji.png]]


Eclipse will pop up a message telling you the Koji URL to track your build. Here is an example, how this message might look like:
Eclipse will pop up a message with the Koji URL to track your build. This is an example of how the message may look:


[[Image:KojiBuildPopupMessage.png]]
[[Image:KojiBuildPopupMessage.png]]


This should provide you with enough information to track your builds.
This should be enough information to track the builds.


=== Pushing a Bohi Update ===
=== Pushing a Bohi Update ===


After you've successfully built your RPMs, you may use Eclipse Fedorapackager to push an update for those packages. To do so, select the spec file => right click => "Fedora Packager" => "Bodhi Update". You'll be asked to provide similar information as when using the Bodhi Web interface. Once you've successfully created an update, you should see your pushed update on the Bodhi updates website (and you may track the status of updates there).
After successfully building the RPMs, use Eclipse Fedorapackager to push an update for those packages. To do so, select the spec file => right click => "Fedora Packager" => "Bodhi Update". Similar information is required when using the Bodhi Web interface. Once an update has successfully been created, the pushed update will be visible on the Bodhi updates website. The status up updates can also be tracked there.


= Feedback/Reporting Bugs =
= Feedback/Reporting Bugs =


If you think you've found a bug in Eclipse Fedora Packager, please feel free to open a ticket at: https://fedorahosted.org/eclipse-fedorapackager/report/1 (you have to log in with your FAS username in order to be able to create tickets). You may also try [https://bugzilla.redhat.com/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=MODIFIED&component=eclipse-fedorapackager&product=Fedora&classification=Fedora this query] on RedHat Bugzilla in order to find already existing bugs. Thanks!
If you think you've found a bug in Eclipse Fedora Packager, please feel free to open a ticket at: https://fedorahosted.org/eclipse-fedorapackager/report/1 (you have to log in with your FAS username in order to be able to create tickets). You may also try [https://bugzilla.redhat.com/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=MODIFIED&component=eclipse-fedorapackager&product=Fedora&classification=Fedora this query] on RedHat Bugzilla in order to find already existing bugs. Thanks!

Revision as of 01:22, 20 October 2010

What is Eclipse Fedora Packager?

Eclipse Fedora Packager is a plug-in for Eclipse. It helps Fedora packagers who are used to IDEs (such as Eclipse IDE), to package their Fedora RPMs from within Eclipse without needing to resort to the command line. (at least for the most part :-) ).

Some features included in the Eclipse Fedora Packager are:

  • Conveniently clone Fedora Git projects
  • RPM-spec-file editor with syntax highlighting, auto-completion and changelog support (<Ctrl>+<Alt>+C keyboard shortcut)
  • Download source files and upload new source files
  • Prepare local builds (execute %prep section of your spec-file only)
  • Create source RPM files based on current spec-file
  • Execute local builds
  • Push builds to Koji (the Fedora build system)
  • Mock builds
  • Push Bodhi updates
  • Eclipse Git support (via EGit, please refer to EGit documentation)

Eclipse Fedora Packager has been available for Fedora users since F14. Want to try it out? Issue the following command to install it:

yum install eclipse-fedorapackager

Using Eclipse Fedorapackager

Since Fedora 14, the Git version control system for keeping track of files required for Fedora packaging is used. See the dist-git documentation for in depth information about dist-git. Fortunately, how dist-git works when using the Eclipse Fedora Packager plug-in is unimportant. There is only a slightly different approach for doing packaging work compared to what might have been used with CVS instead of Git.

Initial Setup

This step is only required to be completed once for a new Fedora packager or if using a new machine that does not have required FAS certificates installed. When it is certain the set up is correct it is safe to skip this step. The following explains how to set up those certificates for a FAS account?

First, install the fedora-packager RPM package:

yum install fedora-packager

Then run the following command and simply follow the instructions provided:

$ fedora-packager-setup

Once this is done Eclipse Fedorapackager is ready for use. Fire up Eclipse. Let's get started. Yay!

Importing a Fedora Git Project

Getting started is easy. Go to "File" => "Import" => "Git" => "Projects from Fedora Git". This will clone the desired Git repository and create necessary local branches. For convenience, the "Git Repositories" view will also open once the clone process has finished.

Here's how the Fedora Git import dialog looks like. Next, specify the package name that will then be prepared for you.

Image:SelectPackageNameGit.png

Once the new project has been created something akin to the following is seen. Note the branches in the Git Repository view and "[eclipse-fedorapackager master]" right beside the project name. In this case, eclipse-fedorapackager refers to the Git repository name and master to the currently checked out branch.

Do Your Fedora Packaging Work

After a Fedora Git project has been created, all files required for packaging the desired release can be found in the corresponding directory. For example, Fedora 13 corresponds to branch f13/master. Branch master corresponds to Fedora rawhide, the current development release of Fedora. WThe following is a brief description of things to consider doing while packaging up some software. Working in a different sequence works, but keep in mind that before trying a Koji build push your locally committed changes to the public repository.

Uploading Source Files Required for a Package

In order to upload new sources in Eclipse Fedorapackager, first download upstream sources and place the downloaded sources in the same folder as the Eclipse project. If this is done outside of Eclipse, don't forget to refresh the project afterwards (F5) so that the file actually shows up. A slick way to download sources is to use RPM editor functionality directly. See its documentation for more information on this. Once the new source file is available in the project, it can be uploaded to the lookaside cache by right-clicking on the file=> Fedora Packager => Upload This File => Replace/Add File. This either adds the file to the sources required to build the package or replaces the current content of the sources file to contain a single line with the MD5 sum of the file selected.

A valid certificate is required to upload to the lookaside cache. If it has expired, a new one can be created by issuing the following command on a terminal:

$ fedora-cert -n

Downloading Source Files Required for a Package

To download the required source files for an existing package in order to build it, right-click on the spec-file => Fedora Packager => Downloaded Sources. This downloads all sources listed in the file sources.

Using the Spec-File Editor

Eclipse Fedora Packager uses the RPM Editor and ChangeLog plug-in from the Eclipse Linux Tools project (http://www.eclipse.org/linuxtools). For instance, a new ChangeLog entry can easily be created in the spec file by using the <CTRL>+<ALT>+C keyboard shortcut (though a good idea is to set appropriate “ChangeLog” preferences first). Using <CTRL>+<SPACE> auto-completes locally installed packages. Also, rpmlint can be run by right-clicking on the spec file => “Run Rpmlint”. For more information have a look at the spec file editor screencast: http://www.eclipse.org/downloads/download.php?file=/technology/linuxtools/videos/specfile-demo.ogg or at the "Specfile Editor User Guide": Help => Help Contents => Specfile Editor User Guide.

Committing Changes to the Local Git Repository

After the spec-file, patches etc. have been added/changed, commit those changes to the repository. This is done by:

  1. Selecting the files to commit (alternatively select the Fedora Git project and select desired unstaged files when the commit dialog is shown)
  2. Right-click, "Team" => "Commit..."

Switching Branches (Git Checkout)

Switching branches is as easy as double-clicking on the desired local branch to be worked on. The currently checked out branch is indicated to the left of the project name. Make sure to commit, revert, or stash changes before switching to a different branch. Refer to the Git/EGit documentation for more information on this.

Prepare Sources for a Local Build

Eclipse Fedora Packager will download and prepare sources by right-clicking on the spec-file => “Fedora Packager” => “Prepare Sources for Build”.

Build RPM for a Local Architecture

This is a great way to test if the spec-file actually builds at all. Once the RPM has been successfully built locally, it is recommended further testing be carried out on the spec-file by completing a build in a chroot'ed environment using {{{mock}}}. Both ways are supported by Eclipse Fedorapackager.

The RPM can be built locally by selecting the spec-file => right-click => “Fedora Packager” => “Build for Local Architecture”. Output of the RPM build will appear on the Eclipse console.

Using mock-builds is a great way to test the “Requires/BuildRequires” of a spec-file. Select the spec-file => right-click => “Fedora Packager” => “Local Build Using Mock”. Be aware that this may take a long time (>20 minutes) and requires the mock package to be installed. Use Eclipse's “Run in Background” functionality for convenience.

Make Locally Committed Changes Public (Git Push)

The changes are ready to be pushed (or published) publicly when the locally committed changes are satisfying. Remember, Git allows history to be rewritten before changes are made public. See the Git/EGit documentation for more information. To bring the local repository in sync with origin:

  1. Select the Fedora Git project
  2. Right-click, "Team" => "Push..."
  3. Select the Git repository to be pushed to (usually this is kept unchanged)
  4. Select the Git references to be pushed
  5. Carry out the push operation

The Git push dialog.

Git push dialog

Select the Git references to push. In this example, branches master and f14/master will get pushed. Keep in mind that source and destination references are the same for Eclipse Fedora Packager. Clicking the “Add all branches spec” button is a convenience that pushes all commits to all local branches.

Select Git References

Pushing a Build to Koji

Once satisfied with a spec file, upload the sources of the package, commit the changes to the local repository, and then push the local changes to the remote repository. When this is done, push a build to Koji by right-clicking the spec file => “Fedora Packager” => “Push to Koji”.

Eclipse will pop up a message with the Koji URL to track your build. This is an example of how the message may look:

This should be enough information to track the builds.

Pushing a Bohi Update

After successfully building the RPMs, use Eclipse Fedorapackager to push an update for those packages. To do so, select the spec file => right click => "Fedora Packager" => "Bodhi Update". Similar information is required when using the Bodhi Web interface. Once an update has successfully been created, the pushed update will be visible on the Bodhi updates website. The status up updates can also be tracked there.

Feedback/Reporting Bugs

If you think you've found a bug in Eclipse Fedora Packager, please feel free to open a ticket at: https://fedorahosted.org/eclipse-fedorapackager/report/1 (you have to log in with your FAS username in order to be able to create tickets). You may also try this query on RedHat Bugzilla in order to find already existing bugs. Thanks!