Flock | the social web browser

FBuild

Contents

[edit] What is fbuild?

fbuild is flock build, it is the framework surrounding building flock

  • fbuild is a set of command-line tools to make building flock easier, and to make it easier to communicate between developers how things work.
  • fbuild is not the only way to build flock, nor the prefered way to build flock if you are not developing on it.

You can expect flock developers to refer to variables in fbuild when describing where peices of code are.

[edit] What are the parts?

There are 3 major parts to fbuild. fbuild is ambigious and refers both the developer environment code and the related services (builder servers and release tools)

[edit] fbuild - developer environment

  1. sets up a un*x like environment (cygwin on windows) to be able to find all the bits to build flock
  2. sets up variables to rever to spefic bits of code
  3. provides tools for doing l10n work, working with installers, building libraries

[edit] fbuilder - buildmanager/tinderbox client

  1. FBuilder is a set of scripts that do automated builds of flock and publishes them

[edit] freleaser - fbuild software release managment system

  1. freleaser is a managment application for controling fbuilder, and publishing builds to the public

[edit] The Quick Commands

fenv
This is how you initialize the fbuild environment. By default, it does not modify your path or fill up your environment. If you want all your default shells to use the fbuild environment, add the command fbuild to the end of your .bashrc
jumpmake
Build Flock works everywhere.
fmake
Nice shortcut to make Flock. Works more nicely than `jumpmake` in User:Termie's opinion (maybe update it?). If given arguments, for instance, "common," it makes specifically for that component or set of components. If $F_LAUNCH is set it launches the browser automatically after making.
fmakel
Build Flock and launch.
Comfort Variables
  • $c is the component directory. Most of the code that is specific to Flock is here. This is where you want to go to hack Flock.
  • $b is your build directory where all the files for building Flock should live.
  • $s is the Flock source repository, so here you can find source files, including flock_browser, tools, vendor/code.
  • $m is the mozilla directory. This contains the Mozilla & Flock source code.
  • $o is the object directory. Any time you build Mozilla the file goes here. All the active makefiles are here as well.
fupdate
  • updates all the Flock tools files
  • updates your environment
fupdate_all
  • updates the Flock source files
  • updates your environment
fbuild.sh
  • builds Mozilla using the Mozilla build process
  • regenerates Makefiles and other configure steps
fbuild_all
  • does everything in fupdate.sh
  • updates tools, flock_browser, and if $s/local/fbuild.lock is not present will rebuild the vendor code
  • this means that you are up to date on all code
fqbuild
  • this is the quick build
  • runs make in the object directory ($o)
  • does not update makefiles or other configuration options
locale_set
  • script for managing locales
  • pulls the Firefox locale from CVS and Flock locale from SVN
  • manages .mozconfig entry for locales

[edit] Setup

Like many large projects, the Mozilla development environment is complex. If you are having difficulty, we are here to help.

Build setup on Linux

Build setup on MacOS

Build setup on MSWin

Building by hand or on other OS

[edit] Getting Started

Download fbuild-initialsetup.sh 

$ svn export svn://svn-mirror.flock.com/master/tools/trunk/fbuild/bin/fbuild-initialsetup.sh fbuild-initialsetup.sh

If you wish to build from anonymous add the --anonymous argument to fbuild-initialsetup.sh

Run 

$ sh fbuild-initialsetup.sh
$ . ~/.bashrc
$ fenv
$ flaunch

By default, this builds the browser in ~/fbuild or on MSWIn /cygdrive/C/fbuild.(i.e, C:\fbuild) It also modifies your .bashrc, and from now on you have the command fenv to initialize this new environment.

This runs an interactive script that sets up your environment and offers to do a build of Flock for you.

[edit] Advanced Guide

usage 

usage: ./fbuild-initialsetup.sh [--user scm_user] [--anonymous|--mirror]
[--branch branch_name] [--no-prompt] [--buildbase directory] [ENVIRONMENT_NAME]
      --user scm_user, sets the username for connecting to the repository
      --anonymous, sets default branch, and src repository to the public mirror
      --mirror, is a synonym for anonymous
      --branch branch_name, ie 'branches/buzzard' sets the branch to checkout
      --no-prompt, do not ask the user to verify the buildbase just use default    echo "
      --buildbase fullpath, where fullpath is fp to the directory to build flock in aka \$b"
      ENVIRONMENT_NAME, is label appended to buildbase dir and shell function
      --help, is this mesage


Instructions for using this script:

Run this file from a blank slate. You are prompted to enter the directory in which you want to create the build environment.

The script then checks the Flock build tools, loads the build environment, and installs a helper function in your ~/.bashrc file to load the environment.

After that, the script checks out all Flock browser code and begins the build process. Much time will pass.

There is one command-line option: If a string is passed to the script, it will be assigned to the F_BRANCH variable and function to distinguish the current build from a previous one. For example, if your default build is at /fbuild, but you want to try out something new, you can pass '-test' to this script and it will suggest that defaults use /fbuild-test).

There are many configuration options -- variables you can set in your environment to control aspects of this script and customize it to your own development habits.

Here is a brief description of each of those variables: 

  F_BUILDBASE     --  The default directory where everything is built.
                      If a command line argument is passed to the script,
                      it is appended to this variable.
  
  F_SCMBASE        -- The repository to pull from. You should change
                      this if you are working with a special repository.
  
  F_FORCE_CLEAN   --  When the script checks out the build tools, if the
                      folder is already under SVN source control the script 
                      automatically updates it. However, if this variable
                      is set to "1k" the script wipes out the directory and
                      checks it out again.
  
  F_INSTALL_FUNCTIONS
                  --  By default, the script appends a helper function
                      to your .bashrc. To prevent this, set this variable 
                      to "0".
  
  F_CREATE_HELPER_SCRIPTS
                  --  If you set this to "1" (default is "0"), the script 
                      creates an executable script and a configuration
                      file that help you launch a new bash shell with 
                      proper configuration for the build environment you
                      are setting up.
  
  F_INTERACTIVE_SETUP
                  --  If you set this to "0" (default is "1"), the script
                      doesn't ask you any questions and just goes with
                      defaults.
  
  F_SCM_BRANCH
                  --  branch for flock source
                  default is determined by scm, i.e. trunk for svn
  
  T_SCM_BRANCH
                  --  branch for tools source
                  default is determined by scm, i.e. trunk for svn
  
  V_SCM_BRANCH
                  --  branch for vendor/code source
                  default is determined by scm, i.e. trunk for svn

[edit] Using a branch

The branch for "Cardinal" (a.k.a. the 0.7.x family) is branches/cardinal.

To setup an environment to work on Cardinal: 

$ svn export svn://svn-mirror.flock.com/master/tools/trunk/fbuild/bin/fbuild-initialsetup.sh fbuild-initialsetup.sh
$ ./fbuild-initialsetup.sh --branch branches/cardinal -cardinal

Then you will have a new working environment for Cardinal that can be initialized with 'fenv-cardinal'.

[edit] Using locale_set

You can turn on localization mode with locale_set ab-CD, where ab-CD is a locale name.

The script pulls the locales to $s/flock/l10n, and adds an entry to .mozconfig. The next time you build Flock, an ab-CD version is created.

locale_set --off turns it off, so the next fbuild will create an en-US version.

[edit] How It Works

[edit] Files involved

fenv: A shell function that sources $FBUILD_HOME/lib/build-common.sh

~/.fbuild/defaults: Defines your personal overrides to the build system, or to any other environment variables you want set in the build system for you alone.

$s/scripts/lib/build-platform.sh: Contains platform specific settings. It determines the platform with uname and then runs these scripts in your environment.

$s/scripts/lib/build-Linux.sh: This is for Linux specific stuff. It is currently empty.

$s/scripts/lib/build-Win32.sh: This is for Windows/Cygwin specific settings. It does several things:

  • MOZ_TOOLS='C:\tools\moztools'
  • GLIB_PREFIX='C:\tools\vc71'
  • LIBIDL_PREFIX='C:\tools\vc71'
  • sets VS_PATH (can be overridden in your ~/.fbuild/defaults). Looks for Common7/Tools/vsvars32.bat in that path, then converts vsvars32.bat to ~/.fbuild/vsvars32.sh, and from then on sources that file to set up environment variables for visual studio. You must delete the ~/.fbuild/vsvars32.sh to force your environment to regenerate it.

$s/scripts/lib/build-Darwin.sh: Initializes the fink environment and fixes your path. It adds elements to the front, and makes sure you have the windows paths in the correct place.

There is a script clean_path.pl that removes duplicate entries from your path, working on first appearance precedence. If /bin is at the beginning of your path it remains at the beginning, no matter how many times it appears later in your path.

[edit] How it works

needs updating

[edit] Hacking It

$s/tools/fbuild/lib/build-common.sh: This is the core file. TEST your changes before checking in because they can affect everybody.

[edit] Creating a Start Script

On Debian-based systems (also tested on Ubuntu Dapper, perhaps it works on all unix-based systems?), this script appears to work to start Flock built in the above manner and can be included in a menu item for easy access. 

#!/bin/bash
# A script to start Flock Browser
. ~/.bashrc
b="$HOME/fbuild"
FBUILD_HOME="$b/src/tools/fbuild"; export FBUILD_HOME
if [ -f "$FBUILD_HOME/lib/build-common.sh" ]; then
#  echo ". \"$FBUILD_HOME/lib/build-common.sh\"" # for debugging
  . "$FBUILD_HOME/lib/build-common.sh"
  flaunch
else
  echo "cannot find $FBUILD_HOME/lib/build-common.sh"
  echo "is FBUILD_HOME defined correctly?"
fi

[edit] Related

Build Optimized Flock

Build system

Retrieved from "http://wiki.flock.com/wiki/FBuild"