Model: Package - mschnitzer/open-build-service-api GitHub Wiki

The Package model represents a source package container on the remote API server.

Class Name: OpenBuildServiceAPI::Package

Instance Attributes:

  • name (String): the name of that source package container

Relations

  • project (OpenBuildServiceAPI::Project): A relation to the project that owns this source package container
  • sources: A relation to the sources of this source package container
  • binaries: A relation to the built binaries of this source package container

Instance Method: #to_s

Converts an instance of OpenBuildServiceAPI::Package into a string. The return value is always the name of the source package container.

Return Value: String

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')
puts "Source package name: #{package}"

Instance Method: #title

Returns the defined title of this source package container. The title is defined in the source container's meta file.

When the meta definition is fetched, the title gets cached. If you want to fetch the title again from the API, you will have to call the #reload! method. (see below)

Return Value: String

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')
puts "Package title: #{package.title}"

Instance Method: #title=(value)

Sets a new title on this source package container. The new title has to be saved by calling the method #save! afterwards on the package container, otherwise the change will remain locally.

Return Value: String (the new title)

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')

package.title = "this is my new title"
package.save!

puts "New package title: #{package.title}"

Instance Method: #description

Returns the defined description of this source package container. The description is defined in the source container's meta file.

When the meta definition is fetched, the description gets cached. If you want to fetch the description again from the API, you will have to call the #reload! method. (see below)

Return Value: String

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')
puts "Package description: #{package.description}"

Instance Method: #description=(value)

Sets a new description on this source package container. The new description has to be saved by calling the method #save! afterwards on the package container, otherwise the change will remain locally.

Return Value: String (the new description)

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')

package.description = "this is my new description"
package.save!

puts "New package description: #{package.description}"

Instance Method: #run_service!

Runs the defined source services on the remote Build Server. This will only work if the source package container has a _service file in place.

Return Value: Boolean (true)

Possible Exceptions:

  • OpenBuildServiceAPI::NoSourceServiceDefinedError when there is no _service file available in the source container

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')

begin
  package.run_service!
  puts "triggered remote services"
rescue OpenBuildServiceAPI::NoSourceServiceDefinedError => err
  puts err.to_s
end

Instance Method: #meta(opts = {})

Returns the meta definition of a source package container. This method accepts a hash of options as an argument. Please find below all available options.

When the meta definition is fetched, it will get cached. If you want to fetch it again from the API, you will have to call the #reload! method. (see below)

Available Option Flags:

  • no_parse: if this is set to true, it will prevent the function from returning a Nokogiri::XML::Document and let it return plaintext XML instead.

Return Value: Nokogiri::XML::Document or String

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')

puts "my plaintext source package definition:"
puts package.meta(no_parse: true)

puts "By default it will return a Nokogiri::XML::Document:"
puts "Nokogiri::XML::Document => #{package.meta.is_a?(Nokogiri::XML::Document)}"

Instance Method: #rebuild!(repository=nil, arch=nil)

Triggers a rebuild of the sources. Alternatively a repository and an architecture can be specified to limit the rebuilding.

Arguments:

  • repository: Optionally define the name of a repository which should be rebuild. Leaving it at nil will cause all repositories to rebuild. (String)
  • arch: Trigger a rebuild only for the given architecture. (String)

Return Value: Boolean (true)

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')

package.rebuild! # rebuilds everything
package.rebuild!('openSUSE_Leap_15.1') # will rebuild the repository openSUSE_Leap_15.1
package.rebuild!('openSUSE_Leap_15.1', 'x86_64') # will only rebuild the repository openSUSE_Leap_15.1 for architecture x86_64

Instance Method: #rebuild_failed!

Triggers a rebuild of the sources for all repositories and architectures where the latest build has failed.

Return Value: Boolean (true)

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')

package.rebuild_failed!

Instance Method: #dirty?

Returns true when some meta information have changed (e.g. by chaning the title of a source package container) but it was not saved yet by calling #save!.

Return Value: Boolean (true/false)

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')

package.title = "a new title without saving it"

if package.dirty?
  puts "it seems something has changed. please call package.save!"
else
  puts "nothing has changed"
end

Instance Method: #save!

Saves all changes (e.g. title changes, meta changes, etc.) on the remote Build Server.

Return Value: Boolean (true/false)

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')

package.title = "new title"
package.description = "new description"

if package.save!
  puts "successfully saved all changes!"
else
  puts "nothing has changed so far!"
end

Instance Method: #delete!(message=nil)

Deletes this source package container from the Build Service.

Arguments:

  • message: specifies a delete reason - this is optional (String)

Possible Exceptions:

  • OpenBuildServiceAPI::PackageDeletionPermissionError when the API account does not have sufficient permissions to delete this source package.

Return Value: Boolean (true)

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')

package.delete!('die!')
puts "package has been deleted"

Instance Method: #reload!

Marks this source package for reloading its information. It will reload the information on demand and not directly when calling this function.

Return Value: Boolean (true)

Example:

project = obs_api.project.find!('home:mschnitzer')
package = project.packages.find!('rubygem-passenger')

# this example demonstrates that a reload makes sense after a while as the meta information for example might have changed in between on the Build Service.

puts "current meta:"
puts package.meta(no_parse: true)

sleep 1800

puts "uh maybe the meta has changed since the last time?"
package.reload!

puts "current meta:"
puts package.meta(no_parse: true)