- `GBS Usage </documentation/reference/git-build-system/usage>`_: Describes, in more detail, how to use GBS
- `FAQ </documentation/reference/git-build-system/faqs>`_: Frequently Asked Questions
-Configuration File
-==================
+GBS Configuration File
+======================
-The configuration file contains all the configuration settings required by gbs. For example, build root and remote repo url for 'gbs build', remote OBS server for 'gbs remotebuild', etc.
+Configuration File Overview
+---------------------------
+GBS's configuration files are all simple INI-style files that record various choices and settings used by many GBS commands. Some settings represent purely personal preferences, others are vital to a build functioning correctly, and still others tweak command behavior a bit.
-Configuration files used by GBS
--------------------------------
-GBS will search for configuration files (.gbs.conf) within the folders below. If GBS finds multiple configuration files, it will load them in this order:
+**Note:** ".conf" is a common extension for an INI file, an informal standard for configuration files. INI files are simple text files with basic structure composed of sections and properties. Like many tools, GBS supports a hierarchy of configuration files, which are shown below in decreasing precedence:
-- ``/etc/gbs.conf`` # for a global configuration, which exists in the package and which we suggest you don't change
-- ``~/.gbs.conf`` # for a user-specific configuration
-- ``$PWD/.gbs.conf`` # for a project/directory specific configuration
+* **$PWD/.gbs.conf:** project-specific configuration settings that affect only the specific project in the specified working directory. These settings have the highest precedence.
-Configuration values in a later file will override the values set in the previous ones.
+* **/home/<user>/.gbs.conf:** user-specific configuration settings that affect only the specified user.
-There is a global parameter `-c(--conf)` to specify the config file. If this option is used, GBS will load this config file and drop other config files in the default paths.
+* **/etc/gbs.conf:** system-wide configuration settings that affect the entire system. These settings have the lowest precedence.
-If GBS can't find any config files, it will generate a config file into ~/.gbs.conf.
+When specifying the configuration file by using -c (--config) option, one of the above files is loaded and applied by GBS. If no configuration file can be found, GBS automatically generates ~/.gbs.conf. Here's an example of specifying one configuration file among a hierarchy of configuration files:
-Profile oriented style of configuration
----------------------------------------
-A profile can contain many items for GBS build and remote build. There can be many profiles in one config file, such as one for Mobile, one for IVI, and so on.
+::
-The default profile is defined in the [general] section. If you change the profile, all GBS behaviors could change.
+ $ gbs -c ~/gbs-my.conf build -A ...
-The mandatory rules for the section names are:
+2 Profile Oriented Style of Configuration
+-----------------------------------------
+This section provides information about the profile oriented style in a GBS configuration file.
+2.1 Basic Structure
+```````````````````
+The basic structure of a configuration file is composed of properties and sections.
-- Profile section name should be started with `profile.`
-- OBS section name should started with `obs.`
-- Repository section name should started with `repo.`
+2.1.1 Properties
+++++++++++++++++
+The basic element contained in a configuration file is the property. Every property has a name and a value, delimited by an equal sign (=). The name appears to the left of the equal sign.
-Common authentication info can be set in the profile level, no need to set them repeatedly in different obs and repo sections. If the authentication info is different for a different obs or repo, it can be set by the **user** and **passwd** key in the individual section.
+2.1.2 Sections
+++++++++++++++
+Properties may be grouped into various sections, named according to the naming conventions specified in Section 2.2. The section name appears on a line by itself in square brackets ([ ]). All the properties after the section declaration are associated with that section. No explicit "end of section" delimiter is needed. Sections end at the next section declaration or the end of the file. Possible sections include:
-Example of a config file
-````````````````````````
-::
+* **General section**
- [general]
- #Current profile name which should match a profile section name
- profile = profile.tizen
- buildroot = ~/GBS-ROOT/
+ The default profile is defined in the general section and has impacts on GBS behaviors on a general basis. That is, upon the modification of the general section, all GBS behaviors will be changed accordingly. Supported properties include tmpdir, upstream_branch, upstreamtag, buildroot, and packaging_dir.
- [profile.tizen]
- obs = obs.tizen
- repos = repo.tizen_latest
- # If no buildroot for profile, the buildroot in general section will be used
- buildroot = ~/GBS-ROOT-profile.tizen/
+* **Profile section**
- [obs.tizen]
- url = https://api.tizen.org
- user = xxxx
- passwd = xxxx
- # set default base_prj for this obs
- #base_prj=Tizen:Main
- # set default target prj for this obs, default is home:<user>:gbs:<base_prj>
- #target_prj=<specify target project>
+ It is recommended that you set common authentication information in the profile level, instead of repeating identical configurations in various sections. These settings can be automatically passed to OBS and repository sections. Add authentication information to a specific repository or OBS section only when it is unique to the corresponding OBS or repository. In addition, multiple profile sections can exist in one configuration file, enabling the manipulation of GBS behaviors aimed at different devices (for example, mobile phone, IVI) in a central configuration file. For more information, refer to Section 3.2. Supported properties include user, passwd, repos, and obs.
- [repo.tizen_latest]
- url = http://download.tizen.org/releases/trunk/daily/ivi/latest/
- #Optional user and password, set if differ from profile's user and password
- #user =
- #passwd =
+* **OBS section**
-Configure repos for 'gbs build'
-```````````````````````````````
+ The OBS section specifies the configurations of the remote build server for remote build. Supported properties include url, user, and password.
-Repos are configured as repo sections, and the section name must start with 'repo.' There are three types of keys supported for the repo section: url, user, and passwd.
+* **Repository section**
-**Note**: When you specify the repo, please use the release folder, instead of the snapshot folder. The images/repos under the release folder are tested and released by release engineers. The images/repos under the snapshot folder are created by backend service automatically. Quality is not guaranteed.
+ As with the profile section, multiple repository sections can exist in one configuration file, so, various repositories can be manipulated in "batch". Properties supported include url, user, and password. User and password can be omitted if the corresponding repository does not need authentication information.
-You can specify multiple repos in a profile.
+2.2 Naming Conventions
+``````````````````````
+The section names must follow these naming conventions:
-Here's an example:
+* Name the general section exactly as "[general]".
+* Start the profile section name with "profile.". For example, [profile.tizen], [profile.IVI].
+* Start the OBS section name with "obs.". For example, [obs.tizen].
+* Start the repository section name with "repo.".
+
+Here's an example of configuration file:
::
- [profile.tizen]
- repos = repo.tizen_latest, repo.my_local
+ [general]
+ #Current profile name which should match a profile section name
+ tmpdir = /var/tmp
+ editor =
+ packaging_branch = master
+ upstream_branch = upstream
+ upstream_tag = upstream/${upstreamversion}
+ packaging_dir = packaging
+ profile = profile.tizen
+ buildroot = ~/GBS-ROOT/
+ work_dir = .
- [repo.tizen_latest]
- url = http://download.tizen.org/releases/trunk/daily/ivi/latest/
- user = xxx
- passwd = xxx
- [repo.my_local]
- #local repo must be an absolute path
- url = /path/to/local/repo/
+ [profile.tizen]
+ obs = obs.tizen
+ repos = repo.tizen_latest
+ # If no buildroot for profile, the buildroot in general section will be used
+ buildroot = ~/GBS-ROOT-profile.tizen/
+ # Specify build conf for a specific profile by using shell-style variable references
+ buildconf = ${work_dir}/tizen-conf/build.conf
+ # Common authentication information
+ user = xxxxx
+ passwd = xxxxxx
-**Note**: The local repo must be an absolute path. You don't need to run 'createrepo' for that local repo, a plain directory of RPM packages is enough.
+ [obs.tizen]
+ url = https://api.tizen.org
+ user = xxxx
+ passwd = xxxx
+ # set default base_prj for this obs
+ #base_prj=Tizen:Main
+ # set default target prj for this obs, default is home:<user>:gbs:<base_prj>
+ #target_prj=<specify target project>
+ [repo.tizen_latest]
+ url = http://download.tizen.org/releases/trunk/daily/ivi/latest/
+ #Optional user and password, set if differ from profile's user and password
+ #user =
+ #passwd =
-Configure build root for 'gbs build'
-````````````````````````````````````
+3 Configuration Specification
+-----------------------------
+This section provides information about the configuration specification.
-The default gbs build root is ~/GBS-ROOT/, but you can change it and set your own build root. gbs also supports setting different build root directories for different profiles, as follows:
+3.1 Configuring Common Properties
+`````````````````````````````````
+Typical common properties include buildroot, user, and password. To configure the buildroot to override the default value "~/GBS-ROOT", use this assignment equation:
::
- [profile.tizen]
- obs = obs.tizen
- repos = repo.tizen_latest
- buildroot = ~/GBS-ROOT/
+ buildroot=<New_Build_Root>
-**Note**: The plaintext password will be converted automatically as an encoded passwd, so after running gbs, the configuration will be changed as shown below. To change the password, you can delete 'passwdx' and set a new password for 'passwd':
+The reason we need to configure the "passwd" property is because the password line will be automatically converted to an encoded version after running the GBS, as shown in this example:
::
- [obs.tizen]
- url = https://api.tizen.org
- user = xxxx
- passwdx = QlpoOTFBWSZTWVyCeo8AAAKIAHJAIAAhhoGaAlNOLuSKcKEguQT1
+ passwdx = QlpoOTFBWSZTWVyCeo8AAAKIAHJAIAAhhoGaAlNOLuSKcKEguQT1
-Configure multiple profiles
-```````````````````````````
-
-You can configure multiple profiles in one configuration file, for example, one profile for mobile, one profile for ivi, etc. For example, the 'profile' in the 'general' section is used to specify the default profile.
+To reset the password, delete the "passwdx" line above and add this assignment equation:
::
- [general]
- profile = profile.ivi
+ passwd=<New_Password>
- [profile.mobile]
- ...
- [profile.ivi]
- ...
+3.2 Configuring Multiple Profiles
+`````````````````````````````````
+By adding configuration specifications of multiple profiles aimed at various devices in one configuration file, the GBS behaviors oriented for a variety of devices can be manipulated by using a central configuration file. Here's an example of configuring multiple profiles:
-Specify a profile in the command line
-`````````````````````````````````````
+::
+
+ [general]
+ profile = profile.ivi
-Besides specifying the default profile in the configuration file, you can also specify it in the command line by using the `--profile/-P` option . You can specify the whole profile name, such as 'profile.ivi', or just specify the name without 'profile', such as 'ivi' in the case above. For example:
+ [profile.mobile]
+ ...
+ [profile.ivi]
+ ...
+
+When specifying the profile section by using -P (--profile) option, the specified profile configurations are applied by GBS. Here are examples of specifying one profile among multiple profiles:
::
- $ gbs build --profile=profile.mobile -A i586
- $ gbs remotebuild --profile=mobile -A i586 # given profile name without the "profile." prefix
+ $ gbs build --profile=profile.mobile -A i586
+ $ gbs remotebuild --profile=mobile
+
+3.3 Configuring Repository
+``````````````````````````
+This section describes how to configure the repository to adapt the GBS build. The repository configuration specification starts with the section declaration named "[repo.<customized_name>]", and followed by various properties, including:
+
+* url
+
+ The url property specifies the URL of a remote repository, or the full path of a local or remote repository. That is, the following two types of remote repositories are supported:
-Specify a config file in the command line
-`````````````````````````````````````````
+ - a standard RPM repository that has a repodata/ subdirectory under the /repos/ directory.
+ - a Tizen repository that has a builddata/ subdirectory, for example, http://download.tizen.org/releases/daily/2.0alpha/common/latest/
-The option `--config/-C` allows developers to specify one from multiple predefined configuration files. Once '-C' is specified, the default configuration will be skipped.
+ **Note:** To guarantee the quality of the GBS build, the release folder must be used, instead the snapshot folder.
-Example for the command line:
+* user
+
+* passwd
+
+Here's an example of repository configuration specification:
::
- gbs -C ~/gbs-my.conf build -A ...
+ [repo.tizen_latest]
+ url = http://download.tizen.org/releases/trunk/daily/ivi/latest/
+ user = xxx
+ passwd = xxx
+ [repo.my_local]
+ #local repo must be an absolute path
+ url = <Full_Path_of_Local_Repository>
+
+3.4 Shell-Style Variable References
+```````````````````````````````````
+Properties defined in [general] section can be directly used in other sections by using shell-style variable references in GBS 0.17 and later versions.
+
+Here's an example:
+
+::
+ [general]
+ tmpdir=/var/tmp
+ work_dir=~/test
+ [profile.tizen]
+ buildconf=${work_dir}/tizen.conf
+ buildroot=${tmpdir}/profile.tizen/
Upstream tarball and patch-generation support
=============================================
projects / tools / gbs.git / commitdiff