Lovenemesis (talk | contribs) mNo edit summary |
(Redirect Package Maintainer wiki links to docs.fp.o) |
||
(242 intermediate revisions by 10 users not shown) | |||
Line 1: | Line 1: | ||
{{ | {{autolang|base=yes}} | ||
= What is | = What is Fedora Packager for Eclipse? = | ||
Fedora Packager for Eclipse is a plug-in for Eclipse that has been available for Fedora users since F14. It helps Fedora packagers, to package their Fedora RPMs from within Eclipse without needing to resort to the command line (at least for the most part). Think of Fedora Packager for Eclipse as a GUI for <code>fedpkg</code>, although it does ''not'' use it under the covers. | |||
First, install Fedora Packager for Eclipse: | |||
<pre> yum install eclipse-fedorapackager</pre> | |||
'''Some features included in Fedora Packager for Eclipse are:''' | |||
* Conveniently clone Fedora Git projects | * Conveniently clone Fedora Git projects | ||
* RPM | * RPM .spec file editor with syntax highlighting, auto-completion of package names for Requires/BuildRequires templates, <code>%changelog</code> support (<code>Ctrl+Alt+c</code> keyboard shortcut), etc. | ||
* Download source files and upload new source files | * Download source files and upload new source files | ||
* Prepare local builds (execute %prep section of your spec | * Prepare local builds (execute <code>%prep</code> section of your .spec file only) | ||
* Create source | * Create source RPMs based on current .spec file | ||
* | * Perform local builds | ||
* Push builds to Koji (the Fedora build system) | * Push builds to Koji (the Fedora build system) | ||
* Mock builds | * Mock builds | ||
* Push Bodhi updates | * Push Bodhi updates | ||
* Eclipse Git support (via EGit, please refer to EGit documentation) | * Create a local Fedora RPM Project to ease the process of introducing a new Fedora package | ||
* Eclipse Git support (via EGit, please refer to [http://wiki.eclipse.org/EGit/User_Guide EGit documentation]) | |||
= Upgrade to Fedora Packager for Eclipse 0.2.0 = | |||
Old Fedora Packager for Eclipse (0.1.12 and below) did not filter context menu visibility as rigorously as Fedora Packager for Eclipse 0.2 does. In order to do proper filtering of its context menu, version 0.2.0 and above set some persistent state when projects are imported from Fedora Git. This has the effect that the context menu is not shown for projects which have been imported via Fedora Packager for Eclipse 0.1.12 and below. Note that our updated version comes with a tool which makes upgrading those projects simple. Steps required include: | |||
: 1. Open the Fedora Packaging perspective '''Window''' => '''Open Perspective''' => '''Other'''. | |||
[[Image:OpenFedoraPackagingPerspective.png]] | |||
: 2. Click the icon of the conversion tool (as indicated in the screenshot below) | |||
[[Image:ConversionToolIcon.png| Conversion Tool Icon as Shown in the Fedora Packaging Perspective]] | |||
: 3. Select projects in your workspace which should get upgraded | |||
[[Image:SelectProjectsToConvert.png]] | |||
: 4. Click '''OK''' and selected projects should get converted. | |||
After the above steps, the Fedora Packager for Eclipse context menu should show up as usual. | |||
Feel free to [[#Using Fedora Packager for Eclipse | skip to the "Using Fedora Packager" section]] if you are an existing maintainer and know how to package new software for Fedora. | |||
= Getting Started as Maintainer for a New Fedora Package = | |||
If you haven't previously packaged software for Fedora, this guide will lead you through your first package submission. | |||
[[Image:FedoraPackageProcess.png|fedora package process]] | |||
== Creating Account for New Contributors == | |||
If you are a new package maintainer: | |||
=== Creating a new account in Fedora Account System === | |||
* First step is to create account in [https://admin.fedoraproject.org/accounts Fedora Account System (FAS)]. | |||
* Click '''New account''' and fill in the blanks. | |||
* After you create your account, please be sure to sign the CLA (if you click on the '''My Account''' link in the top right, you should see <code>CLA: CLA Done</code>). | |||
* Also you need to upload a public <code>RSA SSH key</code>. You need to use the matching private key to access Fedora machines via SSH. | |||
** Here is information on [http://www.openbsd.org/cgi-bin/man.cgi?query=ssh-keygen creating SSH key]. | |||
=== Creating a Bugzilla Account=== | |||
Create an account in [https://bugzilla.redhat.com/createaccount.cgi Red Hat bugzilla]. | |||
* The email address that you use for your bugzilla account should be the same email address as you use in the ''Fedora Account System'' for all things related to fedora packaging. | |||
* To make you work and your bug tracking easier, there is a task management plug-in for eclipse called '''Mylyn'''. You can follow these instructions on [[Eclipse_How_to_Maintain_Fedora_Package_User_Guide/mylyn_bugzilla|how to integrate your bugizlla account with your mylyn plug-in in eclipse]]. | |||
=== 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 the required FAS certificates set up. When it is certain this is correct it is safe to skip this step. The following explains how to set up those certificates for an [https://admin.fedoraproject.org/accounts/ FAS account].<br/> | |||
* First, install the <code>fedora-packager</code> RPM package: | |||
<pre> yum install fedora-packager </pre> | |||
* Then run the following command and follow the instructions provided: | |||
<pre> fedora-packager-setup </pre> | |||
Feel free to [[#Using Fedora Packager for Eclipse| skip the next section]] if you are an existing maintainer and also know how to create a new software for Fedora. | |||
== Making a Package == | |||
=== Packaging Guidlines === | |||
* If you don't know how to create an RPM package, refer to the tutorial at [[A_Short_RPM_Tutorial|A Short RPM Tutorial]] or the more advanced and much more detailed [[How_to_create_an_RPM_package|how to create an RPM package]]. | |||
* Make sure it is a new package. Check this [https://admin.fedoraproject.org/pkgdb/acls/list/ list of existing packages]. | |||
* Make sure it is a suitable package. Read [https://docs.fedoraproject.org/en-US/packaging-guidelines/ Packaging Guidelines] and [https://docs.fedoraproject.org/en-US/packaging-guidelines/Naming/ Packaging Naming Guidelines]. | |||
* Read some other package submissions to learn about packaging and gain familiarity with the process and requirements. One way of doing this is to join the [https://admin.fedoraproject.org/mailman/listinfo/package-review package-review@lists.fedoraproject.org] mailing list. | |||
=== Creating an RPM package: === | |||
To start with creating an RPM package using Eclipse, perform the steps in [[#Creating_a_Local_Fedora_RPM_Project|creating Local Fedora Packager Project of the user guide]]. | |||
Note that you can populate your project using one of these three options: | |||
: 1. [[#4.a._Start_a_plain_project|Start a plain project]] using .spec file template or an existing .spec file. | |||
: 2. [[#4.b._Use_existing_.spec_file_and_sources_by_importing_SRPM_file|Extract .spec file and resources]] by importing an existing SRPM file to the project. | |||
: 3. [[#4.c._Create_project_using_Rpm_Stubby|Using RPM Stubby]] on <code>feature.xml</code> or <code>pom.xml</code>. | |||
After you created the project, you can use rpm build commands available through the [[#Local_Menu|local context menu]] to build the package and create SRPM file. | |||
In next step you need to submit your .spec file and your SRPM file for review. | |||
== Submiting For Review == | |||
=== Introduce Yourself Using Fedora Mailing Lists === | |||
When a new package maintainer joins the Fedora Project, we request that he/she [https://docs.fedoraproject.org/en-US/package-maintainers/Staying_Close_to_Upstream_Projects/ stays close to upstream]. Inform the developers that you are packaging the software by introducing yourself on the [https://admin.fedoraproject.org/mailman/listinfo/devel devel@lists.fedoraproject.org].<br/> | |||
To sign up for the list, visit the devel list signup page. | |||
* The primary purpose of this is to begin the process of building trust by learning about the package maintainer and increase the chances of your review request being processed sooner. | |||
* The purpose of all this is to break anonymity and foster real-world community within the project. You are under no obligation to reveal personal secrets. The objective is to establish a level of trust with yourself and the other members of the project. | |||
: ''Subject:'' Self Introduction | |||
: ''Body:'' Add any information you believe is applicable including past experience, a link to the review request you have filed and a brief description of yourself. You can also post your GPG key information if you want to. | |||
* Here is the information of [https://docs.fedoraproject.org/en-US/package-maintainers/Joining_the_Package_Maintainers/#join_the_important_mailing_lists possible mailing lists] for you to join. And there is also a list of [[Category:Packaging_SIGs|special interest groups for Fedora Packaging]]. | |||
=== Uploading the Package === | |||
Upload your SRPM and .spec files onto the Internet somewhere. This can be anywhere accessible by a URL. | |||
* If you need hosting space, please make a note of it in your ticket submission and someone will take care of you. | |||
* If you have already got a Fedora Account then you can use your storage at <code><user-name>.fedorapeople.org</code> for this. | |||
<pre> | Example: | ||
<pre> scp path/to/file.spec path/to/rpm-file.src.rpm <user-name>.fedorapeople.org:public_html </pre> | |||
<code>file.spec</code> and <code>rpm-file.src.rpm</code> will then be available via the following URLs: | |||
<pre> http://<user-name>.fedorapeople.org/file.spec | |||
http://<user-name>.fedorapeople.org/rpm-file.src.rpm | |||
</pre> | </pre> | ||
= Using | === Creating Review Request === | ||
Before submitting your request, be sure there is not a previous request for the same package.<br/> | |||
Fill out this form in [https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&format=fedora-review bugzilla]. | |||
:1. Make sure that you put the name of the package (excluding version and release numbers) in the ''Review Summary'' field, along with a very brief summary of what the package is. | |||
:2. Put a description of your package (usually, this can be the same thing as what you put in the spec <code>%description</code>) in the ''Review Description'' field. | |||
:3- Obtain member sponsorship: If this is your first package, or you are a new maintainer who is updating a package, explain it and say that you need a sponsor (you will need sponsorship to check in and build your package).To be able to get sponsored, you should enter '''FE-NEEDSPONSOR''' into the ''Blocks'' field. | |||
:: Sponsorship is not automatic and may require that you further participate in other ways in order to demonstrate your understanding of the packaging guidelines. | |||
:: Key to becoming sponsored is to convince an existing sponsor-level member that you understand and follow the project's guidelines and processes. | |||
:: For more information check this [https://docs.fedoraproject.org/en-US/package-maintainers/How_to_Get_Sponsored_into_the_Packager_Group/ How to get sponsored] user guide. | |||
[[Image:BugzillaForm.png|Bugzilla Form]] | |||
:3. Include the URLs to your SRPM and .spec files. | |||
[[Image:BugzillaReview.png|Bugzilla Review]] | |||
=== Bugzilla feedback === | |||
* You should get notifications of changes by email. Fix any blockers that the reviewer(s) point out. | |||
== Ready to Ship == | |||
Follow these steps after your package is approved by reviewers. | |||
=== Requesting a new package SCM === | |||
When the package is approved by the reviewer, request a git module and branches with the info on [http://fedoraproject.org/wiki/Package_SCM_admin_requests Source Code Management(SCM) admin requests]. | |||
* Requests that require package administrators approval may be requested through the fedora-cvs flag in Bugzilla tickets. Changing the fedora-cvs flag to '''"?"''' in a Bugzilla report means admin attention is needed. | |||
* Mention the name of the branches you need your package to be included in. | |||
[[Image:PackageSCMRequest.png|Package SCM Request]] | |||
=== Fedora Packager Import Wizard === | |||
Once the Fedora Git repository has been created for you, you can import it in Eclipse. | |||
* Go to '''File''' > '''Import''' > '''Git''' > '''Projects from Fedora Git''' (Alternatively use keyboard short-cut <code>CTRL+ALT+F I</code> and enter your package name when prompted. This will clone the desired Git repository. Refer to this user guide on [[Using_Fedora_GIT|Using Fedora Git]] for more information. | |||
* For convenience, the ''Git Repositories view'' will also open once the clone process has finished. <br/><br/> | |||
[[Image:ImportFedoraGit.png|Fedora Git Import]]<br/><br/> | |||
* Here's what the Fedora Git import dialog looks like. Next, specify the package name that will then be prepared for you.<br/><br/> | |||
[[Image:SelectPackageNameGit.png|Select Package Name]]<br/><br/> | |||
* Since you are cloning your new empty git repository, you will just see the '''sources''' file in your cloned package directory. | |||
This | == Updating the SCM == | ||
=== Importing and Committing the Package Contents === | |||
After you have checked out your empty git module, you need to import and commit your package contents into the master branch. | |||
: 1. Right-click on your source files in the SOURCES folder of your local RPM project in Eclipse and click '''Copy'''. | |||
: 2. Right-click on your cloned project from Fedora Git and click '''Paste'''. | |||
: 3. To upload these upstream source files to the lookaside cache, right-click on them, select '''Fedora Packager''' > '''Upload this File''' > '''Add to Existing Sources'''. This adds the files to the list of source files required to build the package. Use '''Fedora Packager''' > '''Upload this File''' > '''Replace Sources''' in order to replace the current content of the '''sources''' file to contain a single line with the MD5 sum of the file selected. More information about the lookaside cache can be found in [[Package_Source_Control#Lookaside_Cache|this document]]. | |||
{{admon/caution|NOTE!| Do not add upstream sources (tar balls, zip files, etc.) to the Fedora Git repository. Use the lookaside cache instead!}} | |||
: 4. Repeat steps <b>1-2</b> for your .spec file in SPECS folder. | |||
: 5. To commit the package contents to the git repository, select the '''source''' file and the '''.spec''' file to commit (alternatively select the Fedora Git project and select desired ''unstaged'' files when the commit dialog is shown), right-click, '''Team''' > '''Commit...''' | |||
* Use this message for your initial commit: "<code>Initial import (#nnnnnn)</code>" (where nnnnnn is your Bugzilla package review bug number). | |||
{{admon/caution|NOTE!| Fedora Packager for Eclipse won't let you to upload your .spec file or any other patches except your sources (tar balls, zip files, etc.) to the Fedora Git repository!}} | |||
=== Building the Package === | |||
* Now you can [[#Building the Package Locally| build your package locally]] using Fedora Packager's features. | |||
< | === Closing the Bugzilla Ticket === | ||
* If your package was built successfully, you should close it as '''NEXTRELEASE'''. | |||
</ | |||
=== Updating Your Package === | |||
Once you have built your package locally, you can perform the following steps to update your package: | |||
: [[#Make Locally Committed Changes Public .28Git Push.29 | Make locally committed changes public]] | |||
: [[#Pushing a Build to Koji | Push the build to Koji]] | |||
: [[#Pushing a Bodhi Update | Push a Bodhi update]] (optional) | |||
* To be able to include your builds in all releases, make sure to read [[#Fedora Packaging Work |these instructions]]. | |||
Continue with [[#Using Fedora Packager for Eclipse | next steps in this user-guide]] to be able to use all available features of Fedora Packager plug-in. | |||
=== Enabling Upstream Release Monitoring === | |||
Fedora has infrastructure available for monitoring new upstream releases of the software you are packaging. | |||
* Refer to [https://docs.fedoraproject.org/en-US/package-maintainers/Upstream_Release_Monitoring/ Upstream Release Monitoring] for more details. | |||
* Learn to handle updates by reading the [https://docs.fedoraproject.org/en-US/package-maintainers/Package_Update_Guide/ Package update HOWTO]. | |||
= Using Fedora Packager for Eclipse = | |||
'''Before continuing with this part, make sure you have read our''' '''[[#Initial Setup|initial setup]] instructions'''. Moreover, please make sure your [[#Configure SSH in Eclipse|FAS SSH keys are properly configured]] in Eclipse. | |||
Most of the features of Fedora Packager for Eclipse are accessible via its context menu or keyboard short-cuts. The richest context menu is available if you [[#Importing a Fedora Git Project |imported a Fedora Git package]]. A subset of this functionality is also available for [[#Creating a Local Fedora RPM Project|Fedora RPM projects]]. The former is intended for Fedora package maintainers and the latter is useful for creating a new Fedora package, which is not yet part of the Fedora distribution. | |||
'''Context Menu''' | |||
The Fedora Packager context menu should be available if you: | |||
: 1. Right-click on a project which got imported via the [[#Importing a Fedora Git Project| Import from Fedora Git]] wizard or a smaller subset for projects created with the [[#Creating a Local Fedora RPM Project| Fedora RPM Project]] wizard. | |||
: 2. Right-click on a .spec file which is contained in a Fedora Packager project (e.g. in the Project Explorer). | |||
: 3. Right-click '''in''' the .spec file itself, while editing it. | |||
[[Image:ContextMenuFedoraPackager.png|Fedora Packager for Eclipse Context Menu]] | |||
'''Available Keyboard Short-Cuts''' | |||
As of Fedora Packager 0.2 available Fedora Packager for Eclipse actions have corresponding keyboard short-cuts. All available short-cuts are shown if you press <code>CTRL+ALT+F</code>. Note that keyboard short-cuts work on the package which is associated with the currently open .spec file (with the exception of importing a new Fedora Git package, <code>CTRL+ALT+F I</code>. | |||
[[Image:KeyboardShortcutsFedoraPackager.png|Fedora Packager for Eclipse Keyboard Short-Cuts]] | |||
'''Fedora Packager for Eclipse Actions''' | |||
The following table describes all Fedora Packager for Eclipse commands in more detail. | |||
{| | |||
! Context Menu Item !! Command Name (as shown when <code>CTRL+ALT+F</code> was pressed) !! Keyboard Short-Cut !! Description | |||
|- | |||
|style="width: 300px;"| Push Build to Koji ||style="width: 150px;"| Koji Build ||style="width: 90px;"| <code>CTRL+ALT+F K</code> || Pushes a regular build to Koji. Checks if there are unpushed changes in the local Git repository prior pushing the build. The build will create an SRPM based on what has been committed and pushed to the Fedora Git repository as well as based on the sources which have been uploaded to the lookaside cache. The target is determined based on the current branch (e.g. master, f15, etc). Once a build has been pushed and was successful, the package will get tagged and will become automatically available in the next Fedora release. | |||
|- | |||
| Perform Scratch Build || Koji Scratch Build || <code>CTRL+ALT+F X</code> || Pushes a scratch build to Koji. Very similar to the above. Checks if there are unpushed changes in the local Git repository prior pushing the build. Scratch builds won't get tagged, though. | |||
|- | |||
| Perform Scratch Build Using Local SRPM || Koji SRPM Scratch Build || <code>CTRL+ALT+F U</code> || Pushes a scratch build to Koji. Koji will use the provides SRPM for the build (i.e. it won't use anything from the Fedora Git repository or lookaside cache. As with all scratch builds, it won't get tagged. | |||
|- | |||
| Create New Bodhi Update || Bodhi Update || <code>CTRL+ALT+F B</code> || Pushes builds which are available in Koji as an update. Updates will usually get pushed to testing and will move to the stable repository. This action checks if there are unpushed changes on the current branch and may prompt for the SSH passphrase as well as for your Eclipse secure storage master password should you have requested Eclipse to store your Bodhi password on a previous update push. It will validate your FAS credentials prior presenting you with the update dialog. The list of builds will get populated with the binary RPMs which the current .spec file produces (again, the Fedora release is based on the currently checked out branch). Additional builds to get pushed as a single update may be added manually. | |||
|- | |||
| Upload This File => Add to existing sources || N/A || N/A || Uploads the currently selected file (the file on which the right-click occurred) to the lookaside cache. Appends an entry to the sources file. Only archive files should get uploaded to the lookaside cache. No text files are permitted such as .spec, .xml, .patch, etc. Add, commit and push them to the Fedora Git repository instead. | |||
|- | |||
| Upload This File => Replace existing sources || N/A || N/A || Uploads the currently selected file (the file on which the right-click occurred) to the lookaside cache. Replaces any existent content in the sources file (i.e. the uploaded file will be the only entry). Only archive files should get uploaded to the lookaside cache. No text files are permitted such as .spec, .xml, .patch, etc. Add, commit and push them to the Fedora Git repository instead. | |||
|- | |||
| Download Sources || Download || <code>CTRL+ALT+F D</code> || Downloads all files as listed in the sources file from the lookaside cache. Does not download files again if already existent in the relevant folder, unless its MD5 checksum mismatches with what's in the sources file. | |||
|- | |||
| Prepare Sources for Build || Prep Sources || <code>CTRL+ALT+F P</code> || Execute the %prep section in the .spec file. This will download sources from the lookaside cache if sources are not yet in the containing folder. Note that this behaviour is slightly different for a [[#Creating a Local Fedora RPM Project|Fedora RPM project]], since downloading from the lookaside cache is not applicable in this case. | |||
|- | |||
| Create SRPM || SRPM Build || <code>CTRL+ALT+F S</code> || Create an SRPM based on the current snapshot of the .spec file and the current Git branch one is on. This will download sources from the lookaside cache if sources are not yet in the containing folder. Note that this behaviour is slightly different for a [[#Creating a Local Fedora RPM Project|Fedora RPM project]], since downloading from the lookaside cache is not applicable in this case. | |||
|- | |||
| Build for Local Architecture || Local Build || <code>CTRL+ALT+F L</code> || Build binary RPMs based on the current snapshot of the .spec file and the current Git branch one is on. This will download sources from the lookaside cache if sources are not yet in the containing folder. Note that this behaviour is slightly different for a [[#Creating a Local Fedora RPM Project|Fedora RPM project]], since downloading from the lookaside cache is not applicable in this case. | |||
|- | |||
| Rebuild Local SRPM in Mock || Mock Build || <code>CTRL+ALT+F R</code> || Rebuild the SRPM which has to be specified by the user in a mock chroot based on the current Git branch one is on. | |||
|- | |||
| Build From Uploaded Sources in Mock || SCM Mock Build || <code>CTRL+ALT+F M</code> || Rebuild the package in a mock chroot based on the current Git branch one is on. This will only use sources as they are available in the pushed Fedora Git repository and the lookaside cache. This won't work if the machine is offline. | |||
|- | |||
| Import SRPM To Repository || SRPM Import || <code>CTRL+ALT+F O</code> || Takes an SRPM specified by the user, extracts its contents into the current branch, replaces the existing sources in the lookaside cache with the extracted source files, and stages any changes made to the Git repository. | |||
|- | |||
| Advanced RPM Actions => Execute RPM Install || N/A || N/A || Execute the %install section of the specfile, and all preceeding sections. | |||
|- | |||
| Advanced RPM Actions => Execute RPM Compile || N/A || N/A || Execute the %build section of the specfile, and all preceeding sections. | |||
|} | |||
As mentioned earlier, as of Fedora Packager for Eclipse 0.2 there are two options for creating Fedora packaging projects: | |||
: 1. Importing an existing Fedora Git project. This should be used for package maintenance. | |||
: 2. Create a new Fedora RPM project for a package not yet in Fedora | |||
First, we'll describe how Fedora Packager for Eclipse can be used for creating a new Fedora package. This is handy if you decided to become a new package maintainer (never packaged something for Fedora before) and would like to submit a package for review. It is also useful for existing package maintainers who would like to introduce a new Fedora package. If you'd like to become a new package maintainer, the Fedora RPM Project option of Fedora Packager for Eclipse 0.2, will help you walking you through the process and will make some parts of it easier for you. For existing packager this will help expediting SRPM creation and submitting it for review. | |||
== Creating a Local Fedora RPM Project == | |||
{{admon/warning|Note| This option should only be used if the software you'd like to package is '''not yet part of the Fedora distribution'''. If it is already part of Fedora, follow instructions [[#Importing a Fedora Git Project| here]].}} | |||
: 1. Select '''New''' > '''Fedora''' > '''Fedora RPM Project''' and click '''Next'''. | |||
: 2. Type the name of your desired package name in '''Project name''' and click '''Next'''. | |||
[[Image:LocalNewProject.png|New Project]] | |||
: 3. Select the option that matches you: | |||
:: If you are an '''Existing maintainer''', select this option and click '''Next'''. | |||
:: If you are a ''New maintainer''', make sure you follow all the mentioned steps to complete your account setting. Once you are finished you can type in your '''FAS Account ID''' and click '''Next'''. | |||
[[Image:LocalNewMaintainers.png|New Maintainers]] | |||
:4. You can start the project in three different ways: | |||
=====4.a. Start a plain project===== | |||
: If you want to upload an existing .spec file, un-check the '''Generate a .spec file from template''' option and click '''Browse''' to upload your file. | |||
: Select your .spec file and click '''Finish'''. | |||
[[Image:LocalPlainSpecProject.png|Plain Spec Project]] | |||
: If you this project does not have any .spec file yet, leave the '''Generate a .spec file from template''' checked and Click '''Next'''. | |||
: Apply any necessary changes and click '''Finish'''. | |||
: Your project content and your generated specfile should look like this: | |||
[[Image:LocalPlainPopulated.png|Plain Populated Project]]<br/><br/> | |||
:5. At the end of creating the project, you will be asked to open the project in the '''Fedora Packager Perspective'''. | |||
Your project will be a local Git repository which has been initialized with the Specfile. The new repository will be automatically opened in the '''Git Repository View''' as part of the Fedora Packager Perspective. | |||
=====4.b. Use existing .spec file and sources by importing SRPM file===== | |||
: If you have already an SRPM, you can upload it to your workspace and the Specfile and sources will be extracted from SRPM. | |||
[[Image:LocalSrpmProject.png|Srpm Project]] | |||
: Select your SRPM file and click '''Finish'''. | |||
: Your project content and your generated specfile should look like this: | |||
[[Image:LocalSrpmPopulate.png|Srpm Populated Project]]<br/><br/> | |||
== | =====4.c. Create project using Rpm Stubby===== | ||
: If you have an Eclipse-feature or Maven-Pom, you can select first option to start your project using [http://www.eclipse.org/linuxtools/projectPages/rpmstubby/ RPM Stubby]. From the drop down list: | |||
:: Select '''ECLIPSE_FEATURE''' to upload an existing ''feature.xml'' file to your project. | |||
:: Or select '''MAVEN_POM''' to upload an existing ''pom.xml'' file to your project. | |||
[[Image:LocalStubbyProject.png|Stubby Project]] | |||
: Select your file and click '''Finish'''. | |||
: Your project content and your generated Specfile should look like this: | |||
[[Image: | [[Image:LocalStubbyPopulate.png|Stubby populate]]<br/><br/> | ||
=====Local Menu===== | |||
Now, you can use Fedora Packager's '''[[#Using_Fedora_Packager_for_Eclipse|context menu]]''' From the main Context Menu. Few commands as is shown in this screen-shot are available to the local project to enable you to [[#Building_the_Package_Locally | locally build your package]]: | |||
[[Image: | [[Image:LocalContextMenu.png|Local Context Menu]]<br/><br/> | ||
'''Local-specific Fedora Packager for Eclipse Actions''' | |||
{| | |||
! Context Menu Item !! Description | |||
|- | |||
| Convert local Fedora project to a Fedora Git project || Convert a local Fedora git project to a regular Fedora Git project by attempting to merge with the remote Fedora Git project of the same name. | |||
|- | |||
| Copy .spec and .src.rpm files to FAS account/public_html || Copies specfile and srpm to the fedorapeople public space for the account associated with the fedora cert. | |||
|- | |||
| Run Fedora Review || Runs the review generation Fedora Review tool command on the package and opens the resulting view in an editor. | |||
|} | |||
== Fedora | == Importing a Fedora Git Project == | ||
Once you are a sponsored Fedora packager you can import Fedora Git packages as follows. Before doing so make sure you've run <code>fedora-packager-setup</code> and configured your FAS [[#Configure SSH in Eclipse|SSH keys in Eclipse]]. | |||
: 1. Select '''Import''' > '''Git''' > '''Projects from Fedora Git''' and click '''Next'''. Alternatively, you can use the keyboard short-cut <code>CTRL+ALT+F I</code> | |||
: 2. Type the name of the package in '''Package name'''. | |||
:: You can find screenshots of these steps in [[#Fedora Packager Import Wizard|Fedora Packager Import Wizard]] section of this user guide. | |||
: 3. Once the new project has been created something akin to the following is seen. | |||
:: In this case, ''eclipse-fedorapackager'' refers to the Git repository name and ''master'' to the currently checked out branch.<br/><br/> | |||
[[Image:GitProjectBranchesView.png|Git Branch View]] | |||
== Fedora Packaging Work == | |||
After a Fedora Git project has been created, all files required for packaging the desired release can be found in the created Eclipse project directly. For example, files for release Fedora 13 correspond to files present in the Eclipse project, once switched to branch '''f13'''. Files in branch '''master''' correspond to '''Fedora rawhide''', the current development release of Fedora. All the development should be done in this branch and once it's done you can [[#Switching Branches .28Git Checkout.29| checkout]] to another desired branch and [http://wiki.eclipse.org/EGit/User_Guide#Rebasing rebase] that branches on top of '''master'''. Then push them together to the upstream.<br/> | |||
The following is a brief description of things to consider doing while packaging up some software. | |||
<pre> | === Uploading Source Files Required for a Package === | ||
$ fedora-cert -n | * In order to upload new sources in Fedora Packager for Eclipse, 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 [[#Using the Specfile Editor|Specfile Editor]] functionality directly. | ||
* Once the new source file is available in the project, it can be uploaded to the lookaside cache by right-clicking on your file, '''Fedora Packager''' > '''Upload This File''' > '''Replace/Add Existing Sources'''. 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. | |||
* 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 in a terminal: | |||
<pre> $ fedora-cert -n | |||
</pre> | </pre> | ||
=== Downloading Source Files Required for a Package === | === 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 and select '''Fedora Packager''' > '''Download Sources'''. This downloads all sources listed in the file <code>sources</code>. | |||
=== Using the Specfile Editor === | |||
Fedora Packager for Eclipse uses the RPM Specfile Editor and ChangeLog plug-in from the [http://www.eclipse.org/linuxtools Eclipse Linux Tools project].<br/> | |||
For instance, a new ChangeLog Entry can easily be created in the .spec file by using the <code>Ctrl+Alt+c</code> keyboard shortcut or by clicking '''Edit''' > '''ChangeLog Entry''' (though a good idea is to set appropriate '''[http://wiki.eclipse.org/Linux_Tools_Project/ChangeLog/User_Guide#ChangeLog_Preferences ChangeLog Preferences]''' first). Also, rpmlint can be run by right-clicking on the .spec file and selecting '''Run Rpmlint'''. <br/> | |||
For more information have a look at the [http://www.eclipse.org/downloads/download.php?file=/technology/linuxtools/videos/specfile-demo.ogg .spec file editor screen-cast], or at the [http://wiki.eclipse.org/Linux_Tools_Project/SpecfileEditor/User_Guide 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: | |||
# 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...'''<br/><br/> | |||
[[Image:GitCommit.png|Git 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 [http://www.kernel.org/pub/software/scm/git/docs/ Git] and [http://wiki.eclipse.org/EGit/User_Guide EGit] documentation for more information on this. | |||
=== Building the Package Locally=== | |||
==== Preparing Sources for Build ==== | |||
Fedora Packager for Eclipse will download and prepare sources for building a package. | |||
* Select your .spec file, right-click, '''Fedora Packager''' > '''Prepare Sources for Build'''. | |||
[[Image:PrepareSourcesForBuild.png|Prepare Sources for Build]] | |||
==== Building 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 environment using mock. Both ways are supported by Fedora Packager for Eclipse. | |||
* To build the RPM locally right-click on the .spec file and select '''Fedora Packager''' > '''Build for Local Architecture'''. Output of the RPM build process will appear in the Eclipse Console view. | |||
Using mock to build your package is a great way to verify that you have the correct <code>BuildRequires</code> in a .spec file. | |||
* To build the RPM locally using mock, right-click on the .spec file and select '''Fedora Packager''' > '''Local Build Using Mock'''. Be aware that this may take a long time and requires the mock package to be installed. Use Eclipse's ''Run in Background'' functionality for convenience. | |||
=== Make Locally Committed Changes Public (Git Push) === | |||
When you are satisfied with your locally-committed changes, you are ready to publish them publicly. Remember, if you made any mistake in your commits, Git allows history to be rewritten before changes are made public. See the [http://www.kernel.org/pub/software/scm/git/docs/ Git] and [http://wiki.eclipse.org/EGit/User_Guide EGit] documentation for more information.<br/> | |||
To bring the local repository in sync with the remote repository (which is by default called [http://wiki.eclipse.org/EGit/User_Guide#Local_Destination origin]): | |||
: 1. Right-click on the Fedora Git project, click '''Team''' > '''Remote''' > '''Push...''' | |||
: 2. Select the Git repository to which you would like to push (usually this is kept unchanged), click '''Next'''.<br/><br/> | |||
[[Image:GitPushDialog.png|Git Push Dialog]]<br/><br/> | |||
: 5. 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 Fedora Packager for Eclipse. | |||
:: Clicking the '''Add all branches spec''' button is a convenience way that pushes all commits to all local branches.<br/><br/> | |||
[[Image:SelectGitReferencesToPush.png|Select Git References]]<br/><br/> | |||
: 4. Carry out the push operation | |||
=== Pushing a Build to Koji === | |||
As of Fedora Packager for Eclipse 0.2 there are three different options of pushing a build to Koji. | |||
: 1. Pushing a regular build | |||
: 2. Pushing a scratch build (using sources from Git and lookaside cache) | |||
: 3. Pushing a scratch build for which the user provides the SRPM | |||
Using the former two is straight forward. Just keep in mind to Git-push local changes before your trigger either one of the two. | |||
[[Image:EclipseFedoraPackagerPushBuildToKoji.png]] | |||
The third option works a bit differently, so we'll focus on it. Pushing a scratch build for which the user specifies the SRPM works as follows: | |||
: 1. It checks if an SRPM is present in the current project. If so you can select either one of them and use that for the Koji build. | |||
: 2. If Fedora Packager for Eclipse can't find an SRPM, it will pop up a file selection dialog so that you can browse to and select any SRPM on your filesystem | |||
: 3. Once the SRPM has been specified, Fedora Packager for Eclipse will upload this SRPM to Koji and Koji will in turn use that SRPM for the build. It won't use any other sources for the build. | |||
[[Image:EclipseFedoraPackagerSelectSRPMForKojiBuild.png]] | |||
After either one of the three Koji builds has been triggered, Eclipse will pop up a message dialog containing the Koji URL to track the pushed build. Here is an example of how the message may look: | |||
[[Image:KojiBuildPopupMessage.png|Koji Popup Dialog]] | |||
Also note that there will be a log entry in the Eclipse Error Log view detailing the Koji-Web URL of the pushed task as well. If you click on the provided URL, a browser tab will open in Eclipse showing you the status of the pushed build. Refresh it in order to follow build progress. | |||
==== Performing A Chain Build ==== | |||
For Fedora Packager for Eclipse 0.4 and later users who would like to push multiple builds at once are able to perform chain builds. To perform access chain build open the Fedora Packaging perspective '''Window''' => '''Open Perspective''' => '''Other'' and select Fedora Packaging. | |||
[[Image:OpenFedoraPackagingPerspective.png]] | |||
The icon should then be visible in the main toolbar. | |||
[[Image:Chain-build-icon.png]] | |||
Click on the icon and the chain build dialog will be displayed. | |||
[[Image:Chain-build-window.png]] | |||
The packages availible for building are are listed in the package list on the left hand side of the dialog. The packages that will be included in the build are listed in the build list on the right hand side in numbered groups. Packages within a group will be built at the same time; groups will be built in numerical with the previously built packages availible in the buildroot. | |||
To add a package to the chain build: | |||
=== | : 1. Check off the packages to be added in the package list. | ||
: 2. Select "Add" to add to the last group numerically or select "Add to new group" to add a new group. | |||
or | |||
: 1. Select package(s) on the package list. | |||
: 2. Click and drag the selection to the desired group. | |||
Once the desired packages have been added to the build, click on '''Chain Build''' to start the build. | |||
==== Advanced Koji Settings ==== | |||
As of Fedora Packager for Eclipse 0.4 there are additional preferences that allow interaction with multiple Koji instances which can be accessed by going to '''Window''' > '''Preferences''', expanding the "Fedora Packager" tree and selecting "Koji". | |||
[[Image:Koji-settings.png]] | |||
Use the "Select default Koji server" combo box to set which of the stored Koji instances to default to when pushing builds to Koji. By default this list has the main Fedora Koji instance and, if not identical, imports your existing Koji settings. To view or manage the known Koji instances click on the "Edit Koji Instances.." button. | |||
[[Image:Server-list.png]] | |||
The "Edit Koji Instances..." dialog has options for adding, editing and removing known Koji instances. The following dialog is used for adding or editing Koji instances: | |||
[[Image:Add-koji.png]] | |||
The "Name" is how the instance will be refered to in program settings. The "Web URL" and "XMLRPC URL" are the URLs of the Koji instance and the location on the koji instance where XMLRPC queries are handled respectively. The "Use Custom Build Targets" checkbox, if checked, will have this Koji instance not use the same default build targets as the default Fedora build server and will instead have a window pop up at build time with a list of available targets to select from. | |||
[[Image: | [[Image:Custom-targets.png]] | ||
In addition to the Koji preferences there are also project properties for managing Koji instances. To access the project properties, right-click on the appropriate project and click on '''Properties''', then select "Fedora Packager Koji". This page allows the setting of a Koji instance that this project's builds are pushed to instead of the default. It also allows the project not to use the default build targets even if the Koji instance it uses normally would. | |||
[[Image:Koji-project-properties.png]] | |||
=== | === Listening for Build Root Updates === | ||
The build root is the set of packages which you package will be built against. When a new package is built for rawhide, a build is pushed to a stable repo of a released version of Fedora, or a build root override is created the corresponding build root is updated. If you are waiting for such an event you can request that eclipse notifies | |||
you when it occures. To do so you right click on the project to open the context menu then go to ('''Fedora Packager''' > '''Notify me when the build root is updated...''') | |||
[[Image:WaitForRepo2.png|WaitForRepo2.png]] | |||
When you click on that menu item you will be presented of valid build roots; select the one you are interested in and this will kick of a job which can be backgrounded and you are notified when the build root is updated. | |||
=== | === Pushing a Bodhi Update === | ||
Fedora Packager for Eclipse can be used to push Bodhi updates as well. For example you can use keyboard short-cut <code>CTRL+ALT+F B</code> or the context menu to trigger this action ('''Fedora Packager''' > '''Create New Bodhi Update'''). Before you push a Bodhi update, make sure that all relevant builds have been pushed to Koji. If you attempt to push an update for a build which does not exist, the Bodhi update will fail. The recommended steps prior pushing a Bodhi update are: | |||
: 1. Push build to Koji | |||
: 2. Make sure your local .spec file matches what's in the remote Git repository | |||
: 3. Right-click on the .spec file of the package you'd like to push an update for | |||
After step three the following actions are carried out by the Bodhi update action of Fedora Packager for Eclipse: | |||
: 1. Fedora Packager for Eclipse (FP for short) checks for unpushed changes of the current branch. | |||
: 2. FP will try to restore saved username and password from Eclipse's secure storage and might therefore prompt for the master password of the secure storage. This only happens if the user ever checked the saved password checkbox of the Bodhi login dialog. | |||
: 3. FP will ask for your Bodhi credentials (your FAS username and password). | |||
[[Image:FedoraPackagerBodhiCredentialsDialog.png|Bodhi Credentials Dialog]] | |||
: 4. FP will validate credentials before presenting the update dialog. | |||
: 5. FP shows the Bodhi update dialog as shown below. | |||
[[Image:FedoraPackagerBodhiUpdateDialog.png|Bodhi Update Dialog]] | |||
Arbitrary additional builds may be added to the list of builds via the '''Add Builds''' button. | |||
[[Image:FedoraPackagerBodhiAddBuildsDialog.png|Bodhi Add Builds Dialog]] | |||
In order to push the update select relevant builds in the dialog (use <code>CTRL+Click</code> to select multiple builds) you'd like to push an update for, choose the update type, provide the request type, add an advisory comment for the update and click '''Save Update'''. If the Bodhi update was successfully pushed, Fedora Packager for Eclipse will show you a message dialog with a link to an URL where the progress of the update can be tracked. | |||
[[Image:FedoraPackagerBodhiPushedUpdate.png|Bodhi Success Message]] | |||
== Configure SSH in Eclipse == | |||
Before you get started with importing packages from Fedora Git, you should have your FAS SSH keys set up in Eclipse. You should do this because if Fedora Packager for Eclipse finds a <code>~/.fedora.cert</code> file, it will use an SSH based clone URL with your FAS username extracted from this certificate. Note that you'll have the option of cloning anonymously anyway. | |||
Eclipse | Unfortunately, Eclipse can't use your ssh-agent. Our believe is that this is because Eclipse has to run on several platforms (not just Eclipse). Since UNIX sockets are platform dependent, this may be be reason why Eclipse can't use it. | ||
'''Eclipse SSH Preferences''' | |||
This should | Press <code>CTRL+3</code>, type "SSH2" and hit return. This should bring you to the following page: | ||
[[Image:EclipseSSHPreferences.png| Eclipse SSH2 Preference page]] | |||
Make sure that your FAS SSH key is listed there and you can successfully unlock your key. | |||
= Feedback/Reporting Bugs = | = Feedback/Reporting Bugs = | ||
* If a bug is found in the Fedora Packager for Eclipse, please feel free to open a ticket at ''[https://fedorahosted.org/eclipse-fedorapackager/report/1 Fedora Hosted]'' (an FAS username is required to create tickets). | |||
If a bug is found in the | * Alternatively, 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] in Red Hat bugzilla in order to find already existing bugs. Thanks! |
Latest revision as of 17:13, 7 October 2021
What is Fedora Packager for Eclipse?
Fedora Packager for Eclipse is a plug-in for Eclipse that has been available for Fedora users since F14. It helps Fedora packagers, to package their Fedora RPMs from within Eclipse without needing to resort to the command line (at least for the most part). Think of Fedora Packager for Eclipse as a GUI for fedpkg
, although it does not use it under the covers.
First, install Fedora Packager for Eclipse:
yum install eclipse-fedorapackager
Some features included in Fedora Packager for Eclipse are:
- Conveniently clone Fedora Git projects
- RPM .spec file editor with syntax highlighting, auto-completion of package names for Requires/BuildRequires templates,
%changelog
support (Ctrl+Alt+c
keyboard shortcut), etc. - Download source files and upload new source files
- Prepare local builds (execute
%prep
section of your .spec file only) - Create source RPMs based on current .spec file
- Perform local builds
- Push builds to Koji (the Fedora build system)
- Mock builds
- Push Bodhi updates
- Create a local Fedora RPM Project to ease the process of introducing a new Fedora package
- Eclipse Git support (via EGit, please refer to EGit documentation)
Upgrade to Fedora Packager for Eclipse 0.2.0
Old Fedora Packager for Eclipse (0.1.12 and below) did not filter context menu visibility as rigorously as Fedora Packager for Eclipse 0.2 does. In order to do proper filtering of its context menu, version 0.2.0 and above set some persistent state when projects are imported from Fedora Git. This has the effect that the context menu is not shown for projects which have been imported via Fedora Packager for Eclipse 0.1.12 and below. Note that our updated version comes with a tool which makes upgrading those projects simple. Steps required include:
- 1. Open the Fedora Packaging perspective Window => Open Perspective => Other.
- 2. Click the icon of the conversion tool (as indicated in the screenshot below)
- 3. Select projects in your workspace which should get upgraded
- 4. Click OK and selected projects should get converted.
After the above steps, the Fedora Packager for Eclipse context menu should show up as usual.
Feel free to skip to the "Using Fedora Packager" section if you are an existing maintainer and know how to package new software for Fedora.
Getting Started as Maintainer for a New Fedora Package
If you haven't previously packaged software for Fedora, this guide will lead you through your first package submission.
Creating Account for New Contributors
If you are a new package maintainer:
Creating a new account in Fedora Account System
- First step is to create account in Fedora Account System (FAS).
- Click New account and fill in the blanks.
- After you create your account, please be sure to sign the CLA (if you click on the My Account link in the top right, you should see
CLA: CLA Done
). - Also you need to upload a public
RSA SSH key
. You need to use the matching private key to access Fedora machines via SSH.- Here is information on creating SSH key.
Creating a Bugzilla Account
Create an account in Red Hat bugzilla.
- The email address that you use for your bugzilla account should be the same email address as you use in the Fedora Account System for all things related to fedora packaging.
- To make you work and your bug tracking easier, there is a task management plug-in for eclipse called Mylyn. You can follow these instructions on how to integrate your bugizlla account with your mylyn plug-in in eclipse.
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 the required FAS certificates set up. When it is certain this is correct it is safe to skip this step. The following explains how to set up those certificates for an FAS account.
- First, install the
fedora-packager
RPM package:
yum install fedora-packager
- Then run the following command and follow the instructions provided:
fedora-packager-setup
Feel free to skip the next section if you are an existing maintainer and also know how to create a new software for Fedora.
Making a Package
Packaging Guidlines
- If you don't know how to create an RPM package, refer to the tutorial at A Short RPM Tutorial or the more advanced and much more detailed how to create an RPM package.
- Make sure it is a new package. Check this list of existing packages.
- Make sure it is a suitable package. Read Packaging Guidelines and Packaging Naming Guidelines.
- Read some other package submissions to learn about packaging and gain familiarity with the process and requirements. One way of doing this is to join the package-review@lists.fedoraproject.org mailing list.
Creating an RPM package:
To start with creating an RPM package using Eclipse, perform the steps in creating Local Fedora Packager Project of the user guide. Note that you can populate your project using one of these three options:
- 1. Start a plain project using .spec file template or an existing .spec file.
- 2. Extract .spec file and resources by importing an existing SRPM file to the project.
- 3. Using RPM Stubby on
feature.xml
orpom.xml
.
After you created the project, you can use rpm build commands available through the local context menu to build the package and create SRPM file. In next step you need to submit your .spec file and your SRPM file for review.
Submiting For Review
Introduce Yourself Using Fedora Mailing Lists
When a new package maintainer joins the Fedora Project, we request that he/she stays close to upstream. Inform the developers that you are packaging the software by introducing yourself on the devel@lists.fedoraproject.org.
To sign up for the list, visit the devel list signup page.
- The primary purpose of this is to begin the process of building trust by learning about the package maintainer and increase the chances of your review request being processed sooner.
- The purpose of all this is to break anonymity and foster real-world community within the project. You are under no obligation to reveal personal secrets. The objective is to establish a level of trust with yourself and the other members of the project.
- Subject: Self Introduction
- Body: Add any information you believe is applicable including past experience, a link to the review request you have filed and a brief description of yourself. You can also post your GPG key information if you want to.
- Here is the information of possible mailing lists for you to join. And there is also a list of.
Uploading the Package
Upload your SRPM and .spec files onto the Internet somewhere. This can be anywhere accessible by a URL.
- If you need hosting space, please make a note of it in your ticket submission and someone will take care of you.
- If you have already got a Fedora Account then you can use your storage at
<user-name>.fedorapeople.org
for this.
Example:
scp path/to/file.spec path/to/rpm-file.src.rpm <user-name>.fedorapeople.org:public_html
file.spec
and rpm-file.src.rpm
will then be available via the following URLs:
http://<user-name>.fedorapeople.org/file.spec http://<user-name>.fedorapeople.org/rpm-file.src.rpm
Creating Review Request
Before submitting your request, be sure there is not a previous request for the same package.
Fill out this form in bugzilla.
- 1. Make sure that you put the name of the package (excluding version and release numbers) in the Review Summary field, along with a very brief summary of what the package is.
- 2. Put a description of your package (usually, this can be the same thing as what you put in the spec
%description
) in the Review Description field. - 3- Obtain member sponsorship: If this is your first package, or you are a new maintainer who is updating a package, explain it and say that you need a sponsor (you will need sponsorship to check in and build your package).To be able to get sponsored, you should enter FE-NEEDSPONSOR into the Blocks field.
- Sponsorship is not automatic and may require that you further participate in other ways in order to demonstrate your understanding of the packaging guidelines.
- Key to becoming sponsored is to convince an existing sponsor-level member that you understand and follow the project's guidelines and processes.
- For more information check this How to get sponsored user guide.
- 3. Include the URLs to your SRPM and .spec files.
Bugzilla feedback
- You should get notifications of changes by email. Fix any blockers that the reviewer(s) point out.
Ready to Ship
Follow these steps after your package is approved by reviewers.
Requesting a new package SCM
When the package is approved by the reviewer, request a git module and branches with the info on Source Code Management(SCM) admin requests.
- Requests that require package administrators approval may be requested through the fedora-cvs flag in Bugzilla tickets. Changing the fedora-cvs flag to "?" in a Bugzilla report means admin attention is needed.
- Mention the name of the branches you need your package to be included in.
Fedora Packager Import Wizard
Once the Fedora Git repository has been created for you, you can import it in Eclipse.
- Go to File > Import > Git > Projects from Fedora Git (Alternatively use keyboard short-cut
CTRL+ALT+F I
and enter your package name when prompted. This will clone the desired Git repository. Refer to this user guide on Using Fedora Git for more information. - For convenience, the Git Repositories view will also open once the clone process has finished.
- Here's what the Fedora Git import dialog looks like. Next, specify the package name that will then be prepared for you.
- Since you are cloning your new empty git repository, you will just see the sources file in your cloned package directory.
Updating the SCM
Importing and Committing the Package Contents
After you have checked out your empty git module, you need to import and commit your package contents into the master branch.
- 1. Right-click on your source files in the SOURCES folder of your local RPM project in Eclipse and click Copy.
- 2. Right-click on your cloned project from Fedora Git and click Paste.
- 3. To upload these upstream source files to the lookaside cache, right-click on them, select Fedora Packager > Upload this File > Add to Existing Sources. This adds the files to the list of source files required to build the package. Use Fedora Packager > Upload this File > Replace Sources in order to replace the current content of the sources file to contain a single line with the MD5 sum of the file selected. More information about the lookaside cache can be found in this document.
- 4. Repeat steps 1-2 for your .spec file in SPECS folder.
- 5. To commit the package contents to the git repository, select the source file and the .spec file to commit (alternatively select the Fedora Git project and select desired unstaged files when the commit dialog is shown), right-click, Team > Commit...
- Use this message for your initial commit: "
Initial import (#nnnnnn)
" (where nnnnnn is your Bugzilla package review bug number).
Building the Package
- Now you can build your package locally using Fedora Packager's features.
Closing the Bugzilla Ticket
- If your package was built successfully, you should close it as NEXTRELEASE.
Updating Your Package
Once you have built your package locally, you can perform the following steps to update your package:
- To be able to include your builds in all releases, make sure to read these instructions.
Continue with next steps in this user-guide to be able to use all available features of Fedora Packager plug-in.
Enabling Upstream Release Monitoring
Fedora has infrastructure available for monitoring new upstream releases of the software you are packaging.
- Refer to Upstream Release Monitoring for more details.
- Learn to handle updates by reading the Package update HOWTO.
Using Fedora Packager for Eclipse
Before continuing with this part, make sure you have read our initial setup instructions. Moreover, please make sure your FAS SSH keys are properly configured in Eclipse.
Most of the features of Fedora Packager for Eclipse are accessible via its context menu or keyboard short-cuts. The richest context menu is available if you imported a Fedora Git package. A subset of this functionality is also available for Fedora RPM projects. The former is intended for Fedora package maintainers and the latter is useful for creating a new Fedora package, which is not yet part of the Fedora distribution.
Context Menu
The Fedora Packager context menu should be available if you:
- 1. Right-click on a project which got imported via the Import from Fedora Git wizard or a smaller subset for projects created with the Fedora RPM Project wizard.
- 2. Right-click on a .spec file which is contained in a Fedora Packager project (e.g. in the Project Explorer).
- 3. Right-click in the .spec file itself, while editing it.
Available Keyboard Short-Cuts
As of Fedora Packager 0.2 available Fedora Packager for Eclipse actions have corresponding keyboard short-cuts. All available short-cuts are shown if you press CTRL+ALT+F
. Note that keyboard short-cuts work on the package which is associated with the currently open .spec file (with the exception of importing a new Fedora Git package, CTRL+ALT+F I
.
Fedora Packager for Eclipse Actions
The following table describes all Fedora Packager for Eclipse commands in more detail.
Context Menu Item | Command Name (as shown when CTRL+ALT+F was pressed) |
Keyboard Short-Cut | Description |
---|---|---|---|
Push Build to Koji | Koji Build | CTRL+ALT+F K |
Pushes a regular build to Koji. Checks if there are unpushed changes in the local Git repository prior pushing the build. The build will create an SRPM based on what has been committed and pushed to the Fedora Git repository as well as based on the sources which have been uploaded to the lookaside cache. The target is determined based on the current branch (e.g. master, f15, etc). Once a build has been pushed and was successful, the package will get tagged and will become automatically available in the next Fedora release. |
Perform Scratch Build | Koji Scratch Build | CTRL+ALT+F X |
Pushes a scratch build to Koji. Very similar to the above. Checks if there are unpushed changes in the local Git repository prior pushing the build. Scratch builds won't get tagged, though. |
Perform Scratch Build Using Local SRPM | Koji SRPM Scratch Build | CTRL+ALT+F U |
Pushes a scratch build to Koji. Koji will use the provides SRPM for the build (i.e. it won't use anything from the Fedora Git repository or lookaside cache. As with all scratch builds, it won't get tagged. |
Create New Bodhi Update | Bodhi Update | CTRL+ALT+F B |
Pushes builds which are available in Koji as an update. Updates will usually get pushed to testing and will move to the stable repository. This action checks if there are unpushed changes on the current branch and may prompt for the SSH passphrase as well as for your Eclipse secure storage master password should you have requested Eclipse to store your Bodhi password on a previous update push. It will validate your FAS credentials prior presenting you with the update dialog. The list of builds will get populated with the binary RPMs which the current .spec file produces (again, the Fedora release is based on the currently checked out branch). Additional builds to get pushed as a single update may be added manually. |
Upload This File => Add to existing sources | N/A | N/A | Uploads the currently selected file (the file on which the right-click occurred) to the lookaside cache. Appends an entry to the sources file. Only archive files should get uploaded to the lookaside cache. No text files are permitted such as .spec, .xml, .patch, etc. Add, commit and push them to the Fedora Git repository instead. |
Upload This File => Replace existing sources | N/A | N/A | Uploads the currently selected file (the file on which the right-click occurred) to the lookaside cache. Replaces any existent content in the sources file (i.e. the uploaded file will be the only entry). Only archive files should get uploaded to the lookaside cache. No text files are permitted such as .spec, .xml, .patch, etc. Add, commit and push them to the Fedora Git repository instead. |
Download Sources | Download | CTRL+ALT+F D |
Downloads all files as listed in the sources file from the lookaside cache. Does not download files again if already existent in the relevant folder, unless its MD5 checksum mismatches with what's in the sources file. |
Prepare Sources for Build | Prep Sources | CTRL+ALT+F P |
Execute the %prep section in the .spec file. This will download sources from the lookaside cache if sources are not yet in the containing folder. Note that this behaviour is slightly different for a Fedora RPM project, since downloading from the lookaside cache is not applicable in this case. |
Create SRPM | SRPM Build | CTRL+ALT+F S |
Create an SRPM based on the current snapshot of the .spec file and the current Git branch one is on. This will download sources from the lookaside cache if sources are not yet in the containing folder. Note that this behaviour is slightly different for a Fedora RPM project, since downloading from the lookaside cache is not applicable in this case. |
Build for Local Architecture | Local Build | CTRL+ALT+F L |
Build binary RPMs based on the current snapshot of the .spec file and the current Git branch one is on. This will download sources from the lookaside cache if sources are not yet in the containing folder. Note that this behaviour is slightly different for a Fedora RPM project, since downloading from the lookaside cache is not applicable in this case. |
Rebuild Local SRPM in Mock | Mock Build | CTRL+ALT+F R |
Rebuild the SRPM which has to be specified by the user in a mock chroot based on the current Git branch one is on. |
Build From Uploaded Sources in Mock | SCM Mock Build | CTRL+ALT+F M |
Rebuild the package in a mock chroot based on the current Git branch one is on. This will only use sources as they are available in the pushed Fedora Git repository and the lookaside cache. This won't work if the machine is offline. |
Import SRPM To Repository | SRPM Import | CTRL+ALT+F O |
Takes an SRPM specified by the user, extracts its contents into the current branch, replaces the existing sources in the lookaside cache with the extracted source files, and stages any changes made to the Git repository. |
Advanced RPM Actions => Execute RPM Install | N/A | N/A | Execute the %install section of the specfile, and all preceeding sections. |
Advanced RPM Actions => Execute RPM Compile | N/A | N/A | Execute the %build section of the specfile, and all preceeding sections. |
As mentioned earlier, as of Fedora Packager for Eclipse 0.2 there are two options for creating Fedora packaging projects:
- 1. Importing an existing Fedora Git project. This should be used for package maintenance.
- 2. Create a new Fedora RPM project for a package not yet in Fedora
First, we'll describe how Fedora Packager for Eclipse can be used for creating a new Fedora package. This is handy if you decided to become a new package maintainer (never packaged something for Fedora before) and would like to submit a package for review. It is also useful for existing package maintainers who would like to introduce a new Fedora package. If you'd like to become a new package maintainer, the Fedora RPM Project option of Fedora Packager for Eclipse 0.2, will help you walking you through the process and will make some parts of it easier for you. For existing packager this will help expediting SRPM creation and submitting it for review.
Creating a Local Fedora RPM Project
- 1. Select New > Fedora > Fedora RPM Project and click Next.
- 2. Type the name of your desired package name in Project name and click Next.
- 3. Select the option that matches you:
- If you are an Existing maintainer, select this option and click Next.
- If you are a New maintainer', make sure you follow all the mentioned steps to complete your account setting. Once you are finished you can type in your FAS Account ID and click Next.
- 4. You can start the project in three different ways:
4.a. Start a plain project
- If you want to upload an existing .spec file, un-check the Generate a .spec file from template option and click Browse to upload your file.
- Select your .spec file and click Finish.
- If you this project does not have any .spec file yet, leave the Generate a .spec file from template checked and Click Next.
- Apply any necessary changes and click Finish.
- Your project content and your generated specfile should look like this:
- 5. At the end of creating the project, you will be asked to open the project in the Fedora Packager Perspective.
Your project will be a local Git repository which has been initialized with the Specfile. The new repository will be automatically opened in the Git Repository View as part of the Fedora Packager Perspective.
4.b. Use existing .spec file and sources by importing SRPM file
- If you have already an SRPM, you can upload it to your workspace and the Specfile and sources will be extracted from SRPM.
- Select your SRPM file and click Finish.
- Your project content and your generated specfile should look like this:
4.c. Create project using Rpm Stubby
- If you have an Eclipse-feature or Maven-Pom, you can select first option to start your project using RPM Stubby. From the drop down list:
- Select ECLIPSE_FEATURE to upload an existing feature.xml file to your project.
- Or select MAVEN_POM to upload an existing pom.xml file to your project.
- Select your file and click Finish.
- Your project content and your generated Specfile should look like this:
Local Menu
Now, you can use Fedora Packager's context menu From the main Context Menu. Few commands as is shown in this screen-shot are available to the local project to enable you to locally build your package:
Local-specific Fedora Packager for Eclipse Actions
Context Menu Item | Description |
---|---|
Convert local Fedora project to a Fedora Git project | Convert a local Fedora git project to a regular Fedora Git project by attempting to merge with the remote Fedora Git project of the same name. |
Copy .spec and .src.rpm files to FAS account/public_html | Copies specfile and srpm to the fedorapeople public space for the account associated with the fedora cert. |
Run Fedora Review | Runs the review generation Fedora Review tool command on the package and opens the resulting view in an editor. |
Importing a Fedora Git Project
Once you are a sponsored Fedora packager you can import Fedora Git packages as follows. Before doing so make sure you've run fedora-packager-setup
and configured your FAS SSH keys in Eclipse.
- 1. Select Import > Git > Projects from Fedora Git and click Next. Alternatively, you can use the keyboard short-cut
CTRL+ALT+F I
- 2. Type the name of the package in Package name.
- You can find screenshots of these steps in Fedora Packager Import Wizard section of this user guide.
- 3. Once the new project has been created something akin to the following is seen.
- In this case, eclipse-fedorapackager refers to the Git repository name and master to the currently checked out branch.
- In this case, eclipse-fedorapackager refers to the Git repository name and master to the currently checked out branch.
Fedora Packaging Work
After a Fedora Git project has been created, all files required for packaging the desired release can be found in the created Eclipse project directly. For example, files for release Fedora 13 correspond to files present in the Eclipse project, once switched to branch f13. Files in branch master correspond to Fedora rawhide, the current development release of Fedora. All the development should be done in this branch and once it's done you can checkout to another desired branch and rebase that branches on top of master. Then push them together to the upstream.
The following is a brief description of things to consider doing while packaging up some software.
Uploading Source Files Required for a Package
- In order to upload new sources in Fedora Packager for Eclipse, 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 Specfile Editor functionality directly.
- Once the new source file is available in the project, it can be uploaded to the lookaside cache by right-clicking on your file, Fedora Packager > Upload This File > Replace/Add Existing Sources. 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 in 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 and select Fedora Packager > Download Sources. This downloads all sources listed in the file
sources
.
Using the Specfile Editor
Fedora Packager for Eclipse uses the RPM Specfile Editor and ChangeLog plug-in from the Eclipse Linux Tools project.
For instance, a new ChangeLog Entry can easily be created in the .spec file by using the Ctrl+Alt+c
keyboard shortcut or by clicking Edit > ChangeLog Entry (though a good idea is to set appropriate ChangeLog Preferences first). Also, rpmlint can be run by right-clicking on the .spec file and selecting Run Rpmlint.
For more information have a look at the .spec file editor screen-cast, or at the 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:
- 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...
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 and EGit documentation for more information on this.
Building the Package Locally
Preparing Sources for Build
Fedora Packager for Eclipse will download and prepare sources for building a package.
- Select your .spec file, right-click, Fedora Packager > Prepare Sources for Build.
Building 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 environment using mock. Both ways are supported by Fedora Packager for Eclipse.
- To build the RPM locally right-click on the .spec file and select Fedora Packager > Build for Local Architecture. Output of the RPM build process will appear in the Eclipse Console view.
Using mock to build your package is a great way to verify that you have the correct BuildRequires
in a .spec file.
- To build the RPM locally using mock, right-click on the .spec file and select Fedora Packager > Local Build Using Mock. Be aware that this may take a long time and requires the mock package to be installed. Use Eclipse's Run in Background functionality for convenience.
Make Locally Committed Changes Public (Git Push)
When you are satisfied with your locally-committed changes, you are ready to publish them publicly. Remember, if you made any mistake in your commits, Git allows history to be rewritten before changes are made public. See the Git and EGit documentation for more information.
To bring the local repository in sync with the remote repository (which is by default called origin):
- 1. Right-click on the Fedora Git project, click Team > Remote > Push...
- 2. Select the Git repository to which you would like to push (usually this is kept unchanged), click Next.
- 5. 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 Fedora Packager for Eclipse.
- Clicking the Add all branches spec button is a convenience way that pushes all commits to all local branches.
- 4. Carry out the push operation
Pushing a Build to Koji
As of Fedora Packager for Eclipse 0.2 there are three different options of pushing a build to Koji.
- 1. Pushing a regular build
- 2. Pushing a scratch build (using sources from Git and lookaside cache)
- 3. Pushing a scratch build for which the user provides the SRPM
Using the former two is straight forward. Just keep in mind to Git-push local changes before your trigger either one of the two.
The third option works a bit differently, so we'll focus on it. Pushing a scratch build for which the user specifies the SRPM works as follows:
- 1. It checks if an SRPM is present in the current project. If so you can select either one of them and use that for the Koji build.
- 2. If Fedora Packager for Eclipse can't find an SRPM, it will pop up a file selection dialog so that you can browse to and select any SRPM on your filesystem
- 3. Once the SRPM has been specified, Fedora Packager for Eclipse will upload this SRPM to Koji and Koji will in turn use that SRPM for the build. It won't use any other sources for the build.
After either one of the three Koji builds has been triggered, Eclipse will pop up a message dialog containing the Koji URL to track the pushed build. Here is an example of how the message may look:
Also note that there will be a log entry in the Eclipse Error Log view detailing the Koji-Web URL of the pushed task as well. If you click on the provided URL, a browser tab will open in Eclipse showing you the status of the pushed build. Refresh it in order to follow build progress.
Performing A Chain Build
For Fedora Packager for Eclipse 0.4 and later users who would like to push multiple builds at once are able to perform chain builds. To perform access chain build open the Fedora Packaging perspective Window' => Open Perspective => Other and select Fedora Packaging.
The icon should then be visible in the main toolbar.
Click on the icon and the chain build dialog will be displayed.
The packages availible for building are are listed in the package list on the left hand side of the dialog. The packages that will be included in the build are listed in the build list on the right hand side in numbered groups. Packages within a group will be built at the same time; groups will be built in numerical with the previously built packages availible in the buildroot.
To add a package to the chain build:
- 1. Check off the packages to be added in the package list.
- 2. Select "Add" to add to the last group numerically or select "Add to new group" to add a new group.
or
- 1. Select package(s) on the package list.
- 2. Click and drag the selection to the desired group.
Once the desired packages have been added to the build, click on Chain Build to start the build.
Advanced Koji Settings
As of Fedora Packager for Eclipse 0.4 there are additional preferences that allow interaction with multiple Koji instances which can be accessed by going to Window > Preferences, expanding the "Fedora Packager" tree and selecting "Koji".
Use the "Select default Koji server" combo box to set which of the stored Koji instances to default to when pushing builds to Koji. By default this list has the main Fedora Koji instance and, if not identical, imports your existing Koji settings. To view or manage the known Koji instances click on the "Edit Koji Instances.." button.
The "Edit Koji Instances..." dialog has options for adding, editing and removing known Koji instances. The following dialog is used for adding or editing Koji instances:
The "Name" is how the instance will be refered to in program settings. The "Web URL" and "XMLRPC URL" are the URLs of the Koji instance and the location on the koji instance where XMLRPC queries are handled respectively. The "Use Custom Build Targets" checkbox, if checked, will have this Koji instance not use the same default build targets as the default Fedora build server and will instead have a window pop up at build time with a list of available targets to select from.
In addition to the Koji preferences there are also project properties for managing Koji instances. To access the project properties, right-click on the appropriate project and click on Properties, then select "Fedora Packager Koji". This page allows the setting of a Koji instance that this project's builds are pushed to instead of the default. It also allows the project not to use the default build targets even if the Koji instance it uses normally would.
Listening for Build Root Updates
The build root is the set of packages which you package will be built against. When a new package is built for rawhide, a build is pushed to a stable repo of a released version of Fedora, or a build root override is created the corresponding build root is updated. If you are waiting for such an event you can request that eclipse notifies you when it occures. To do so you right click on the project to open the context menu then go to (Fedora Packager > Notify me when the build root is updated...)
When you click on that menu item you will be presented of valid build roots; select the one you are interested in and this will kick of a job which can be backgrounded and you are notified when the build root is updated.
Pushing a Bodhi Update
Fedora Packager for Eclipse can be used to push Bodhi updates as well. For example you can use keyboard short-cut CTRL+ALT+F B
or the context menu to trigger this action (Fedora Packager > Create New Bodhi Update). Before you push a Bodhi update, make sure that all relevant builds have been pushed to Koji. If you attempt to push an update for a build which does not exist, the Bodhi update will fail. The recommended steps prior pushing a Bodhi update are:
- 1. Push build to Koji
- 2. Make sure your local .spec file matches what's in the remote Git repository
- 3. Right-click on the .spec file of the package you'd like to push an update for
After step three the following actions are carried out by the Bodhi update action of Fedora Packager for Eclipse:
- 1. Fedora Packager for Eclipse (FP for short) checks for unpushed changes of the current branch.
- 2. FP will try to restore saved username and password from Eclipse's secure storage and might therefore prompt for the master password of the secure storage. This only happens if the user ever checked the saved password checkbox of the Bodhi login dialog.
- 3. FP will ask for your Bodhi credentials (your FAS username and password).
- 4. FP will validate credentials before presenting the update dialog.
- 5. FP shows the Bodhi update dialog as shown below.
Arbitrary additional builds may be added to the list of builds via the Add Builds button.
In order to push the update select relevant builds in the dialog (use CTRL+Click
to select multiple builds) you'd like to push an update for, choose the update type, provide the request type, add an advisory comment for the update and click Save Update. If the Bodhi update was successfully pushed, Fedora Packager for Eclipse will show you a message dialog with a link to an URL where the progress of the update can be tracked.
Configure SSH in Eclipse
Before you get started with importing packages from Fedora Git, you should have your FAS SSH keys set up in Eclipse. You should do this because if Fedora Packager for Eclipse finds a ~/.fedora.cert
file, it will use an SSH based clone URL with your FAS username extracted from this certificate. Note that you'll have the option of cloning anonymously anyway.
Unfortunately, Eclipse can't use your ssh-agent. Our believe is that this is because Eclipse has to run on several platforms (not just Eclipse). Since UNIX sockets are platform dependent, this may be be reason why Eclipse can't use it.
Eclipse SSH Preferences
Press CTRL+3
, type "SSH2" and hit return. This should bring you to the following page:
Make sure that your FAS SSH key is listed there and you can successfully unlock your key.
Feedback/Reporting Bugs
- If a bug is found in the Fedora Packager for Eclipse, please feel free to open a ticket at Fedora Hosted (an FAS username is required to create tickets).
- Alternatively, try this query in Red Hat bugzilla in order to find already existing bugs. Thanks!