Changeset 2290 in ProjectBuilder for devel

Timestamp:

Sep 4, 2017, 1:21:20 PM (7 years ago)

Author:

Bruno Cornec

Message:

Document pb Env var, URLs and DIRs !!

File:

• devel/pb-modules/etc/pb.yml.pod (modified) (3 diffs)

devel/pb-modules/etc/pb.yml.pod

@@ -664 +664 @@
  Nature: Optional
  Key: project (as defined in the -p option or PBPROJ environment variable)
- Value: whatever. As soon as this is defined, then that project is known as not well formed (have a subdirectory in its tar file under which all sources are put named project-version). This should be reported upstream to the project. tar files generated by project-builder to not suffer from that. This is valid when packaging for tar files and not CMS.
+ Value: whatever. As soon as this is defined, then that project is known as not well formed (have a subdirectory in its tar file under which all sources are put named project-version). This should be reported upstream to the project. tar files generated by project-builder.org to not suffer from that. This is valid when packaging for tar files and not CMS.
  Conffile: project
  Example: pbwf afio = 1
@@ -1110 +1110 @@
 =over 4
 
-=item B<pb_URL>
-
-=item B<pb_directory_desc>
-
-=item B<pb_environment_variables>
+=item B<pb URLs>
+
+ The pbprojurl and pbconfurl parameters support multiple schemas to point to the repositories to use.
+ They are parsed by project-builder.org to communicate with them. 
+
+ The protocols can be git, git+svn, svk, svn, cvs, hg. 
+ If you have write access to the repository, you'll generally use an ssh access which will be noted by a +ssh at the end of the protocol used. If you don't you may use a +http(s) e.g. to access the repository. 
+
+ Examples:
+
+ pbprojurl: 
+   fossology: git+https://github.com/fossology/fossology.git
+   linuxcoe: cvs+ssh://:ext:bcornec@linuxcoe.cvs.sourceforge.net:/cvsroot/linuxcoe
+   pb: svn+ssh://svn.mondorescue.org/prj/svn/pb
+
+ => You access the upstream FOSSology project in read mode (by https) and the project uses git as a VCS, that will also be used by project-builder.org to build.
+ => You access the upstream LinuxCOE project in write mode (by ssh) and the project uses CVS as a VCS, that will also be used by project-builder.org to build.
+ => For Project-builder.org itself, you access the upstream LinuxCOE project in write mode (by ssh) and the project uses CVS as a VCS, that will also be used by project-builder.org to build.
+ => You access the upstream project-builder.org project in write mode (by ssh) and the project uses subversion as a VCS, that will also be used by project-builder.org to build.
+
+ If you use instead:
+   pb: git+svn+ssh://svn.mondorescue.org/prj/svn/pb
+
+ => You access the upstream project-builder.org project in write mode (by ssh) and the project uses subversion as a VCS, and you use git svn to manage locally the software with git, that will also be used by project-builder.org to build.
+
+
+ In some cases, there is no repository and the files are hosted remotely, in which case you can use an http(s) or ftp protocol
+
+ Examples:
+
+ pbprojurl: 
+   afio: ftp://localhost/src/afio-2.5.tar.gz
+
+ => You access the project in read mode as a tar compressed file format using ftp to have access to it and that will also be used by project-builder.org to build.
+
+
+=item B<pb Directories>
+
+ In order to use project-builder.org to build packages for a project, you need to declare certain directories in your configurationfile, and two URLS, as defined in the previous paragraph, linked to them.
+
+ The first couple to declare is the pbconfurl and pbconfdir. They declare the location of the repository containing project-builder.org configuration files and the local directory in which they are checked out. They do not need to be hosted in the upstream repository and can be managed completely separately. If pbconfdir is not defined, by default it will be taken as the concatention of pbdefdir and the project name. If that's not the case in your setup, then specify the pbconfdir value
+
+ Examples:
+
+ pbconfurl: 
+  python-redfish: git+ssh://git@github.com:bcornec/python-redfish.git
+  fossology: git+https://github.com/fossology/fossology.git
+  uuwl: git+svn+ssh://svn.mondorescue.org/prj/svn/pb/projects/uuwl/pbconf
+  pb: git+svn+ssh://svn.mondorescue.org/prj/svn/pb/pbconf
+  afio: git+svn+ssh://svn.project-builder.org/prj/svn/pb/projects/afio/pbconf
+  linuxcoe: cvs+ssh://:ext:bcornec@linuxcoe.cvs.sourceforge.net:/cvsroot/linuxcoe/pbconf
+
+ pbconfdir:
+  python-redfish: $ENV{'HOME'}/Work/bruno/prj/python-redfish/pbconf
+  fossology: $ENV{'HOME'}/Work/bruno/prj/fossology/git/pbconf
+  uuwl: $ENV{'HOME'}/svn-git/pb/projects/uuwl/pbconf
+
+ pbdefdir:
+  default: $ENV{'HOME'}/svn-git/pb/projects
+  python-redfish: $ENV{'HOME'}/Work/bruno/prj
+  fossology: $ENV{'HOME'}/Work/bruno/prj/fossology
+  uuwl: $ENV{'HOME'}/svn-git
+  pb: $ENV{'HOME'}/svn-git
+
+ => You access the project-builder.org configuration files for python-redfish in write mode (by ssh) and this project is using git as a VCS, that will also be used by project-builder.org to build packages. The first time, project-builder.org will clone the git repository from the pbconfurl URL into the pbconfdir directory, expanding the HOME directory on the fly. If the project is already cloned there it will just use it, with the current branch. The pbdefdir will be used for other parameters, but the pbconfdir value takes precedence (in this case both variable mean the same local location anyway). Here the upstream python-redfish project is hosting the pbconf info directly.
+ => You access the project-builder.org configuration files for FOSSology in read-only mode (by https) and this project is using git as a VCS, that will also be used by project-builder.org to build packages. The first time, project-builder.org will clone the git repository from the pbconfurl URL into the pbconfdir directory, expanding the HOME directory on the fly. If the project is already cloned there it will just use it, with the current branch. The pbdefdir will be used for other parameters, but the pbconfdir value takes precedence (in this case both variable mean the same local location anyway). Here the upstream python-redfish project is hosting the pbconf info directly.
+ => You access the project-builder.org configuration files for UUWL in write mode (by ssh) and this project is using SVN as a VCS to manage the repo and git svn will be used by project-builder.org to build packages. The first time, project-builder.org will clone the SVN repository from the pbconfurl URL into the pbconfdir directory, expanding the HOME directory on the fly. If the project is already cloned there it will just use it, with the current branch. The pbdefdir will be used for other parameters, but the pbconfdir value takes precedence (in this case variables point to different locations). Here the upstream UUWL project is not hosting the pbconf info directly, which is managed in the upstream SVN project-builder.org repository.
+ => You access the project-builder.org configuration files for project-builder.org in write mode (by ssh) and this project is using SVN as a VCS to manage the repo and git svn will be used by project-builder.org to build packages. The first time, project-builder.org will clone the SVN repository from the pbconfurl URL into a directory whose name is the concatenation of the pb pbdefdir path and then the project name (PBPROJ value setup with the -p option see below, here pb), expanding the HOME directory on the fly, as there is no pbconfdir value setup for this project. If the project is already cloned there it will just use it, with the current branch. Here the upstream project-builder.org project is hosting the pbconf info directly.
+ => You access the project-builder.org configuration files for afio in write mode (by ssh) and this project is using SVN as a VCS to manage the repo and git svn will be used by project-builder.org to build packages. The first time, project-builder.org will clone the SVN repository from the pbconfurl URL into a directory whose name is the concatenation of the default pbdefdir path and then the project name (PBPROJ value setup with the -p option see below, here afio), expanding the HOME directory on the fly, as there is no pbconfdir value setup for this project, and no value for this project for the pbdefdir parameter, only the default one. If the project is already cloned there it will just use it, with the current branch. Here the upstream afio project is not hosting the pbconf info directly, which is managed in the upstream SVN project-builder.org repository.
+ => You access the project-builder.org configuration files for LinuxCOE in write mode (by ssh) and this project is using CVS as a VCS, that will be used by project-builder.org to build packages. The first time, project-builder.org will clone the CVS repository from the pbconfurl URL into a directory whose name is the concatenation of the default pbdefdir path and then the project name (PBPROJ value setup with the -p option see below, here linuxcoe), expanding the HOME directory on the fly, as there is no pbconfdir value setup for this project, and no value for this project for the pbdefdir parameter, only the default one. If the project is already cloned there it will just use it, with the current branch. Here the upstream LinuxCOE project is hosting the pbconf info directly.
+
+ Note that ultimately, if pbdefdir is not defined, project-builder.org will use /var/cache by default, which may fail if you do not have appropriate write rights.
+
+ The second couple to declare is the pbprojurl and pbprojdir. Similarly, they declare the location of the repository containing the upstream project files and the local directory in which they are checked out. If pbprojdir is not defined, by default it will be taken as the concatention of pbdefdir and the project name. If that's not the case in your setup, then specify the pbprojdir value
+
+ Examples:
+
+ pbprojurl: 
+  python-redfish: git+ssh://git@github.com:bcornec/python-redfish.git
+  fossology: git+ssh://git@github.com:fossology/fossology.git
+  uuwl: git+svn+ssh://svn.mondorescue.org/prj/svn/uuwl
+  pb: git+svn+ssh://svn.mondorescue.org/prj/svn/pb
+  afio: ftp://localhost/src/afio-2.5.tar.gz
+  linuxcoe: cvs+ssh://:ext:bcornec@linuxcoe.cvs.sourceforge.net:/cvsroot/linuxcoe
+
+ pbprojdir:
+  fossology: $ENV{'HOME'}/Work/bruno/prj/fossology/git
+  pb: $ENV{'HOME'}/svn-git/pb
+  linuxcoe: $ENV{'HOME'}/LinuxCOE/cvs
+
+ pbdefdir:
+  default: $ENV{'HOME'}/svn-git/pb/projects
+  python-redfish: $ENV{'HOME'}/Work/bruno/prj
+  fossology: $ENV{'HOME'}/Work/bruno/prj/fossology
+  uuwl: $ENV{'HOME'}/svn-git
+  pb: $ENV{'HOME'}/svn-git
+
+ => You access the upstream files for python-redfish in write mode (by ssh) and this project is using git as a VCS, that will also be used by project-builder.org to manage the sources. The first time, project-builder.org will clone the git repository from the pbprojurl URL into a directory whose name is the concatenation of the python-redfish pbdefdir path and then the project name (PBPROJ value setup with the -p option see below, here python-redfish), expanding the HOME directory on the fly, as there is no pbprojdir value setup for this project. If the project is already cloned there it will just use it, with the current branch.
+ => You access the upstream files for FOSSology in write mode (by ssh) and this project is using git as a VCS, that will also be used by project-builder.org to manage the sources. The first time, project-builder.org will clone the git repository from the pbprojurl URL into the pbprojdir directory, expanding the HOME directory on the fly. If the project is already cloned there it will just use it, with the current branch. The pbdefdir will be used for other parameters, but the pbprojdir value takes precedence (in this case variables point to different locations).
+ => You access the upstream files for UUWL in write mode (by ssh) and this project is using SVN as a VCS to manage the repo and git svn will be used by project-builder.org to manage the sources. The first time, project-builder.org will clone the git repository from the pbprojurl URL into a directory whose name is the concatenation of the uuwl pbdefdir path and then the project name (PBPROJ value setup with the -p option see below, here uuwl), expanding the HOME directory on the fly, as there is no pbprojdir value setup for this project. If the project is already cloned there it will just use it, with the current branch.
+ => You access the upstream files for project-builder.org in write mode (by ssh) and this project is using SVN as a VCS to manage the repo and git svn will be used by project-builder.org to manage the sources. The first time, project-builder.org will clone the git repository from the pbprojurl URL into the pbprojdir directory, expanding the HOME directory on the fly. If the project is already cloned there it will just use it, with the current branch.
+ => You access the upstream files for afio in read-only mode and this project, which isn't developed anymore upstream, is just providing a compressed tar file using FTP as a VCS and it will be used by project-builder.org to manage the sources. The first time, project-builder.org will extract the sources from the tar file pointed to by the pbprojurl URL into a directory whose name is the concatenation of the default pbdefdir path, as there is no afio entry for this parameter, and then the project name (PBPROJ value setup with the -p option see below, here afio), expanding the HOME directory on the fly, as there is no pbprojdir value setup for this project.
+ => You access the upstream files for LinuxCOE in write mode (by ssh) and this project is using CVS as a VCS to manage the repo and it will be used by project-builder.org to manage the sources. The first time, project-builder.org will export the CVS repository from the pbprojurl URL into the pbprojdir directory, expanding the HOME directory on the fly. If the project is already cloned there it will just use it, with the current branch.
+
+
+ In order to help you validate the value for a given parameter, you may want to use pb -p pbproj getconf param_to_consider
+
+=item B<pb Environment Variables>
+
+ The following environment variables are used by pb when declared to change its behaviour:
+
+ PBACCOUNT
+   Default: Empty
+   Value: Login to use to connect to the VM/VE/RM. Also see -a option.
+
+ PBPROJ
+   Default: Empty
+   Value: Name of the project to build for. Also see -p option.
+
+ PBROOTDIR
+   Default: Empty
+   Value: Root directory of the configuration files for this project. Also see -r option.
+
+ PBV
+   Default: Empty
+   Value: List of VM/VE/RM to build for, separated by ','. Also see -m option
+
+ PBVCSOPT
+   Default: Empty
+   Value: Options to pass to the VCS command when interacting with the repository.
+
+ PBVMOPT
+   Default: Empty
+   Value: Options to pass to the VM engine to launch VMs.
+
+ PBVMTMOUT
+   Default: 120
+   Value: Timeout in seconds to wait for th launch of the VM before communicating with it. Also see parameter vmtmout in configuration files. Takes precedence.
+
+ TMPDIR
+   Default: /tmp
+   Value: Directory where temporary files will be created.
+
+ ftp_proxy
+ http_proxy
+ https_proxy
+   Default: Empty
+   Value: URL of the proxy server to use for these protocols.
+
+
+ The following environment variables are generated by pb and can be used in build scripts:
+
+ PBBUILDDIR
+   Value: Build directory (pbbuild) where packages are created locally. See the schema of ProjectBuilder::Env man page.
+
+ PBCMSLOGFILE
+   Value: Intermediate log file generated for stable versions to create ChangeLog.
+
+ PBCONFDIR
+   Value: Configuration directory (pbconf) where configuration files for the project are stored. See the schema of ProjectBuilder::Env man page. See pbconfdir parameter.
+
+ PBDEFDIR
+   Value: Default directory where the project-builder.org will host host files for the projects, parent of PBPROJ directories. See the schema of ProjectBuilder::Env man page. See pbdefdir parameter.
+
+ PBDESTDIR
+   Value: Destination directory (pbdelivery) where intermediate tar files are created locally. See the schema of ProjectBuilder::Env man page.
+
+ PBDIR
+   Value: Directory where an upstream version is located. See the schema of ProjectBuilder::Env man page. Correspond to PBROOTDIR for project-builder.org conf files.
+
+ PBETC
+   Value: .pbrc.yml configuration file of the user located in his HOME directory.
+
+ PBPACKAGER
+   Value: E-mail address of the packager, used also to get GPG information. See pbpackager parameter.
+
+ PBPASSFILE
+   Value: File containing the pass phrase for the GPG signature. Used with PBPASSPATH. See pbpassfile parameter.
+
+ PBPASSPATH
+   Value: Path of the file containing the pass phrase for the GPG signature. Used with PBPASSFILE. See pbpasspath parameter.
+
+ PBPASSPHRASE
+   Value: Pass phrase for the GPG signature. Used instead of PBPASSPATH+PBPASSFILE. See pbpassphrase parameter.
+
+ PBPKG
+   Value: Name of the package built.
+
+ PBPROJDIR
+   Value: Directory where an upstream project is located. See the schema of ProjectBuilder::Env man page. Correspond to PBPROJ dir under PBDEFDIR for project-builder.org conf files.
+
+ PBPROJTAG
+   Value: Tag of the packages created, indicating the build procedure version. See pbprojtag parameter.
+
+ PBPROJVER
+   Value: Version of the packages created. See pbprojver parameter.
+
+ PBREVISION
+   Value: Revision of the project in the VCS. Revision for SVN, commit ID for git, ...
+
+ PBVMPORT
+   Value: Offset to the base port to communicate with the VM
+
+ PBSOLDESTDIR
+   Value: Target directory for the Solaris prototype
 
 =back
@@ -1120 +1320 @@
 =head1 COPYRIGHT
 
- (c) B. Cornec 2007-2016
+ (c) B. Cornec 2007-today
  Eric Anderson's changes are (c) Copyright 2012 Hewlett Packard
  Provided under the Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) Creative Common License