= Bootstrapping =

''So, how does one start with project-builder.org on a platform where there are no existing packages ... yet'' ?

Hence, the goal is to take a newer version of a previously supported platform into a fully functioning project-builder.org system using the latest source available.

== Assumptions ==

  * You are running on a platform that can install the types of packages that project-builder.org can already generate
  * You have network access and a subversion client (since that is what is used to house project-builder.org source code)
  * On the platform in use, you have the requisite tools to create a native package

In this example, lets assume you are using a Debian amd64 system

== Setup ==

  * Certainly the easiest way to get started is to grab the nearest equivalent format already available for project-builder.org deliverables (so, continuing the example cited above, [ftp://ftp.project-builder.org/ grab] the lastest stable release source files):
    * in the debian x.0 subdirectories -- libprojectbuilder-perl_<version>.tar.gz and project-builder_<version>.tar.gz
  * Since these were generated with project-builder.org (likely via the cms2build or beyond), you can safely assume that they contain not only the source code for project-builder.org, but also the necessary packaging information itself, for the selected platform
  * In this example, one can extract the source files, enter the resulting directory, and run the typical packaging commands locally to generate installable packages
    * dpkg-buildpackage -rfakeroot -uc -us (and similarly for rpm-based distributions, install the src.rpm and then rpmbuild -ba SPECS/<pkg>.spec
    * ('''NOTE:''' ''since you are not installing from a repository, you may need to satisfy any dependencies manually via the mechanisms on your platform'')

Voila, you have installable packages so go ahead and apply them to your system, and don't worry, we'll be upgrading them to the latest in just a few moments.

== Configuration ==

  * At this point you are almost ready to unleash the full power of project-builder.org, but you must attend to a couple of small details regarding the configuration process

  * for the user (which really should not be root) intending to use project-builder.org (and to build subsequent packages), you must create a simple configuration file
    * create '''~/.pbrc.yml''' with at least the following contents ('''NOTE:''' ''yes, we should supply such a template with future releases''. In the mean time, have a look at this [http://trac.project-builder.org/browser/projects/pb/.pbrc.yml example])

{{{
# how to get project-builder.org source
pburl:
  pb: svn://svn.project-builder.org/mondo/svn/pb

# where to get the packaging templates
pbconfurl:
  pb: svn://svn.project-builder.org/mondo/svn/pb/pbconf

# local prefix for sandbox checkouts and local build artifacts
pbdefdir:
  default: $ENV{'HOME'}/pb/projects
pbdefdir:
  pb: $ENV{'HOME'}
pbconfdir:
  pb: $ENV{'HOME'}/pb/pbconf

# location of Virtual Machine infrastructure
vmpath:
  default: /home/qemu

# location of Virtual Environment (chroot) infrastructure
vepath:
  default: /home/mock
}}}

  * regardless of the type of virtualization you will later employ (lets assume Virtual Machines via qemu), in the directory of '''vmpath''' from the previous configuration file
    * create '''.pbrc.yml''' with at least the following contents (NOTE: an upstream example is also provided for [http://trac.project-builder.org/browser/projects/qemu/.pbrc.yml qemu/kvm] and [http://trac.project-builder.org/browser/pb/devel/rpmbootstrap/etc/.pbrc.yml docker])

{{{
# type of VM
vmtype:
  default: qemu

# VM instance configuration
vmntp:
  default: pool.ntp.org
vmhost:
  default: localhost
vmlogin:
  default: pb
vmport:
  default: 2222
vmtmout:
  default: 120
vmopt: 
  default: -m 384 -daemonize
vmsize:
  default: 5G

# a comma seperated list of all the desired tuples (distro-ver-arch)
vmlist:
  default: mageia-7-x86_64,fedora-30-x86_64,rhel-4-i386,rhel-5-i386,opensuse-15-x86_64,sles-10-i386,gentoo-nover-i386,debian-4.0-i386,ubuntu-8.10-i386
}}}

  ('''NOTE:''' ''the above vmlist is much abbreviated, but the key thing is to ensure the local platform you care about is in this list'')


== Usage ==

Okay, so with much anticipation, you are now ready to build new packages for your local host

  * as the designated user (with the ~/.pbrc.yml) start slowly, grabbing CMS versions of project-builder.org and prepping the build

{{{
pb --verbose --project pb cms2build
}}}

  ('''NOTE:''' ''it may be necessary to initially seed your user's sandbox with an svn checkout to pbdefdir'')

  * ensure you address any errors here, especially those related to the svn operations
  * if all went well, you're ready to build your first package now

{{{
pb --verbose --project pb build2pkg
}}}

  * ensure you address any errors here as well, but if this goes as planned, you are ready to try the big bang approach

{{{
pb --verbose --project pb cms2pkg
}}}

Voila, you should now have newly created packages for your platform, ready to install, and from the very latest cutting edge version, so be brave, upgrade your existing ones to these (and for bonuse points, repeat the pb invocations in the Usage section).