+++ /dev/null
-#
-# e2factory, the emlix embedded build system
-#
-# Copyright (C) 2007-2009 Gordon Hecker <gh@emlix.com>, emlix GmbH
-# Copyright (C) 2007-2009 Oskar Schirmer <os@emlix.com>, emlix GmbH
-# Copyright (C) 2007-2008 Felix Winkelmann, emlix GmbH
-#
-# For more information have a look at http://www.e2factory.org
-#
-# e2factory is a registered trademark by emlix GmbH.
-#
-# This file is part of e2factory, the emlix embedded build system.
-#
-# e2factory is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program. If not, see <http://www.gnu.org/licenses/>.
-#
-
-SUBDIRS =
-TOPLEVEL = ../..
-
-include $(TOPLEVEL)/make.vars
-
-HTML = manual.html \
- basic-concepts.html buildid.html \
- basic.html environment.html project.html chroot.html licences.html \
- sources.html results.html release.html migration.html \
- faq.html
-
-IMAGES = e2factory_logo.png buildid.png
-
-.PHONY: all install local install-local clean localdist uninstall doc
-
-default: doc
-
-all:
- for s in $(SUBDIRS) ; do \
- $(MAKE) -C $$s $@ ;\
- done
-
-install:
- for s in $(SUBDIRS) ; do \
- $(MAKE) -C $$s $@ ;\
- done
-
-uninstall:
- for s in $(SUBDIRS) ; do \
- $(MAKE) -C $$s $@ ;\
- done
-
-local:
- for s in $(SUBDIRS) ; do \
- $(MAKE) -C $$s $@ ;\
- done
-
-install-local:
- for s in $(SUBDIRS) ; do \
- $(MAKE) -C $$s $@ ;\
- done
-
-doc: manual.tar.gz
- for s in $(SUBDIRS) ; do \
- $(MAKE) -C $$s $@ ;\
- done
-
-install-doc: $(HTML)
- install -d -m 755 $(DOCDIR)/manual
- for f in $(HTML) ; do \
- install -m 644 $$f $(DOCDIR)/manual/ ; \
- done
- for f in $(IMAGES) ; do \
- install -m 644 $$f $(DOCDIR)/manual/ ; \
- done
- install -m 644 manual.css $(DOCDIR)/manual/
-
-%.html: %.text header.html footer.html
- cat header.html >$@
- markdown $< >>$@
- cat footer.html >>$@
-
-manual.tar.gz: $(HTML)
- make DOCDIR=./tmp install-doc
- cp tmp/manual/manual.html tmp/manual/index.html
- tar -C tmp -czf manual.tar.gz manual
- rm -fr tmp
-
-clean:
- rm -f $(HTML) manual.tar.gz
+++ /dev/null
-Basic Concepts
---------------
-
-
-*e2factory* is a tool about reliably building results from sources. That is a short
-and correct description. But let's have a look step-by-step.
-
-Building embedded systems from source usually means taking a lot of steps,
-building different parts of the system, starting with a toolchain, going
-on building the root filesystem and finally creating a flash image, for
-example. You may even want to build an up-to-date set of documentation
-with the final result.
-
-The items mentionen above, toolchain, root filesystem and flash image,
-are usually results in *e2factory*. Each of them usually consists of one
-or more other results, a compiler and assembler and the c library will
-make up the toolchain while the root filesystem could consist of some
-libraries, e.g. zlib and the busybox.
-
-Zlib and busybox are usually results again, but they are built from
-sources (that may or may not be named like the results in those cases).
-
-Thats basically the whole concept: Configure sources and configure
-results using sources and other results as dependencies and *e2factory*
-will build the system taking dependencies into account automatically
-and with no chance of doing mistakes, once the configuration is correctly
-set up.
-
-prev [manual](manual.html)
-next [buildid](buildid.html)
+++ /dev/null
-Basic configuration
--------------------
-
-
-*e2factory* requires some basic settings in configuration files in the
-project:
-
-* .e2/e2version configures the version of e2factory to be used with
- the project (the local tools)
-* .e2/syntax holds the syntax version the project requires
-* .e2/extensions lists zero or more extensions to be installed with
- e2factory (local tools)
-
-.e2/e2version holds a single line specifying a branch and a tag.
-e2factory (the e2-install-e2 tool) installs the version according to the
-tag unless the special tag '^' is used.
-
-Example:
-
- master e2factory-2.3.1
-
-.e2/syntax holds a single line specifying the required syntax version
-
-Example:
-
- 2_3_0
-
-.e2/extensions holds a table specifying a list of extensions. The ref
-must be a valid git ref. If the string has a '/' the ref is passed to
-git as-is, otherwise it is translated into a tag by prepending 'refs/tags/'
-
-Example:
-
- extensions {
- {
- name="e2factory-extension",
- ref="refs/tags/e2factory-extension-2.3.1",
- },
- }
-
-prev [buildid](buildid.html)
-next [environment](environment.html)
+++ /dev/null
-buildid
--------
-
-
-A buildid is calculated for each result that is built. The buildid,
-technically being a sha1 hash, identifies all configuration values
-that influence the build process. That key is used to store the
-result.
-
-That means, if the user requests building a result, *e2factory* may
-check if the result already exists and simply skip building it if
-it does. This feature offers the unique combination of being sure to
-build exactly all results that are influenced by changes done to the
-project configuration or sources.
-
-That makes the workflow as easy as just doing changes and requesting
-the tool to build the system (or a specific set of results). *e2factory*
-minimizes the time by rebuilding exactly the results that are influenced
-by the changes.
-
-The picture shows a quick overview of how the buildid is composed:
-
-
-
-prev [basic-concepts](basic-concepts.html)
-next [basic](basic.html)
+++ /dev/null
-Chroot
-------
-
-
-The build environment, called chroot, is organzied in groups. A result
-specifies its chroot groups and the tool will setup the build environment
-using all files from the groups.
-
-The groups listed in the default_groups list are used with all results.
-
-The chroot groups are set up in the order they appear in the configuration
-file.
-
-To setup the chroot configuration call the e2chroot function with a
-table argument.
-
-The table must specify the following keys:
-
-* default_groups: list of strings
-* groups: list of groups specifications
-
-A group specification must specify the following keys:
-
-* name: group name
-* server: server name
-* files: list of file locations, relative to the server
-
-Example:
-
- e2chroot {
- default_groups = { "base", },
- groups = {
- { name = "base",
- server = "chroot",
- files = {
- {
- location = "chroot/20080916/base.tar.gz",
- sha1 = "adc83b19e793491b1c6ea0fd8b46cd9f32e592fc",
- },
- },
- },
- { name = "host-gcc",
- server = "chroot",
- files = {
- {
- -- server is inherited from the group if not configured here
- server = "chroot",
- location = "chroot/20080916/binutils.tar.gz",
- sha1 = "55b6aaa6f91b7cd6bf7e47dbb7af548ef8bb85e8",
- },
- {
- location = "chroot/20080916/gcc34.tar.gz",
- sha1 = "7f69da1b33b39f124cc37331711de8e12bbbc758",
- },
- },
- },
- }
- }
-
-prev [project](project.html)
-next [licences](licences.html)
+++ /dev/null
-Environment
------------
-
-
-*e2factory* allows setting variables that are valid in the configuration as well
-as in the build processes.
-
-Variables can be published across the whole project or local to a set of
-results. In the first case the variables are available in the whole
-configuration and in all build processes. They influence all buildids.
-
-Publishing variables to a specific set of results will make the variables
-available only in the result configuration for those results and in the
-corresponding build process.
-
-To create a environment table in the configuration call the env function
-with a table argument. The table must have the following structure:
-
-* any key with a string value assigned is directly used as an environment
- variable in the build process
-* if a key is assigned a table, the key is treated as a result name.
- The table must hold keys with string values assigned. These key-value
- pairs are usable in that results configuration and build process.
-
-Calling the env function with a string argument takes that string as a
-env file to load in addition to the current configuration file. The
-filename is relative to the project root.
-
-Examples:
-
- env {
- FOO = "bar",
- ["busybox"] = { BUSYBOX_VERSION = "1.0" }
- }
-
- env "proj/more.env"
-
-prev [basic](basic.html)
-next [project](project.html)
+++ /dev/null
-FAQ
------------------------------
-
-Q: What about 'mktemp' saying 'Permission denied' when running e2-build?
-
-A: You've got old chroot environments left from buggy versions of e2factory
-in your build directory. Remove them, as root.
-
------
-Q: e2-fetch-project does not work with e2-2.2.x. Why?
-
-A: The syntax changed. Call e2-fetch-project --help
-
------
-Q: Tool x does no longer work with e2-2.2.x
-
-A: The tool has disappeared, its syntax changed or the use-case is
- no longer supported. Use the --help flag.
-
------
-Q: I cannot fetch / install local tools in a project that has some
- e2factory version prior to e2factory-2.3.0 configured.
-
-A: Use a configuration file pointing to an e2factory repository that
- has those old versons. They are unfortunately not available in the
- free software repository.
- A compatibility wrapper (e2compat) may be installed with your version
- of e2factory. Use
-
- e2compat fetch-project
- e2compat install-e2
-
------
-prev [migration](migration.html)
-next [manual](manual.html)
+++ /dev/null
-</body>
-</html>
+++ /dev/null
-<html>
-<head>
-<style type="text/css">
-@import url(manual.css);
-</style>
-</head>
-<body>
-<img src="e2factory_logo.png" class="logo" />
-<h2>Users manual</h2>
-
+++ /dev/null
-Licences
---------
-
-
-*e2factory* allows configuring licences that may can be referenced in source
-configurations later on.
-
-To configure licences call the e2licence function with a table argument.
-The table must specify keys with table values. The keys are used as
-the licence identifier, that can be referenced in source configurations.
-The table assigns files to the licence:
-
-* server string: speficy the server name
-* files table: a list of files located on that server
-
-Example:
-
- e2licence {
- gpl_2 = {
- server = ".",
- files = {
- {
- -- server is inherited if not given here
- server = ".",
- location = "licence/gpl-2/COPYING",
- -- sha1 is required when the server is not "."
- -- sha1 = "bd3c28b6df9c950cc68d5141c65acfc661779f5e",
- },
- }
- }
- }
-
-prev [chroot](chroot.html)
-next [sources](sources.html)
+++ /dev/null
-/* manual.css -*- Java -*- */
-
-pre {
- border-style: dashed;
- border-color: black;
- border-width: 1;
- width: 70%;
- position: relative;
- left: 5%;
- padding: 1em;
- background-color: #eee;
-}
+++ /dev/null
-Content
------------------
-
-+ Concepts
- * [basic-concepts](basic-concepts.html)
- * [buildid](buildid.html)
-
-+ Configuration
-
- * [basic](basic.html)
- * [environment](environment.html)
- * [project](project.html)
- * [chroot](chroot.html)
- * [licences](licences.html)
- * [sources](sources.html)
- * [results](results.html)
-
-+ Tools
- * e2-ls-project
- * e2-build
-
-+ Advanced topics
- * [building releases](release.html)
- * [migrating to newer versions of e2factory](migration.html)
-
-+ FAQ
- * [FAQ](faq.html)
-
-next [basic-concepts](basic-concepts.html)
+++ /dev/null
-Migrating to newer versions of e2factory
------------------------------
-
-### Migrating from e2factory-2.3.5 to e2factory-2.3.6 ###
-
-* configure a list of results to be deployed in release mode in the
- `deploy_results` attribute in the project configuration according to
- [project](project.html).
-* optional: consider moving environment configuration from `proj/env`
- to source- or result configuration.
-* change the syntax version to `2_3_6` to acknowledge that you changed
- the configuration.
-
-### Migrating from e2factory-2.3.4 to e2factory-2.3.5 ###
-
-* No changes required
-
-### Migrating from e2factory-2.3.3 to e2factory-2.3.4 ###
-
-* The file `.e2/version` was maintained with the project configuration
- in versions up to 2.3.3. This is no longer the case now.
-
-Remove the `.e2/version` file from the repository
-
- $ git rm .e2/version
- $ git commit
-
-* A file `.e2/global-version` is automatically created on project
- checkout, using the server side project descriptor file.
- This file must not be checked into the project repository.
- If it is not possible to re-checkout the project, copy the file
- `.e2/version` to `.e2/global-version` manually before removing
- it, or fetching the update from upstream.
-
-### Migrating from e2factory-2.3.2 to e2factory-2.3.3 ###
-
-* No changes required
-
-### Migrating from e2factory-2.3.1 to e2factory-2.3.2 ###
-
-* change the chroot configuration format according to the documentation
- [chroot](chroot.html)
-* change the licence configuration format according to the documentation
- [licences](licences.html)
-* in the chroot-, licence-, files source configuration the sha1 checksum
- must be configured using the `sha1` attribute for files not located
- on the `'.'` server.
-* change the syntax version to `2_3_2` to acknowledge that you changed
- the configuration.
-
-Change the syntax compatibility version and the version of your local tools
-
- $ echo '2_3_2' >.e2/syntax
- $ echo 'master e2factory-2.3.2' >.e2/e2version
-
-* Do not forget to commit your changes.
-
-### Migrating from e2-2.1 to e2-2.2.x or up to e2factory-2.3.1 ###
-
-#### Prerequisites: Cleanup the project state: ####
-
-* all project members push valuable changes to sources or the project
- repository to the server
-* all project members except the one doing the migration delete their
- full project working copies.
- They become unusable during the migration to e2-2.2.x.
-* be sure the project is in a state that builds without errors
-* tag the project repository
-* install e2-2.2.x global tools
-
-#### Migrate the project, 1st part ####
-
-* switch the project to use e2-2.2.x local tools:
- Change .e2/e2version to hold 'e2-2.2 e2-2.2.0', commit and push
-* the old project checkout is no longer used now. Remove it.
-
-The commands:
-
- $ echo 'e2-2.2 e2-2.2.0' >.e2/e2version
- $ git commit -m 'switch the project to use e2-2.2.0' .e2/e2version
- $ git push
-
-#### Migrate the project 2nd part ####
-
-* checkout the project again. That will install the e2-2.2.x local tools
-* run e2-build. It will complain about .e2/syntax not matching the local
- tools.
-* Create the .e2/syntax file holding the syntax identifier string
- mentioned by e2-build (Something like `2_2_x`).
-* Now the configuration syntax itself must be fixed to match the syntax
- identifier.
-
-The commands:
-
- $ e2-fetch-project ...
- $ cd ...
- $ e2-build
- $ echo '2_2_0' >.e2/syntax
- $ git add .e2/syntax
-
-#### Migrate the project 3rd part ####
-
-Some details of the project configuration change. Follow the steps below
-to change your project configuration to fit e2-2.2.x.
-Please `git add` all of your changed files immediately, to create a clean
-commit once the migration is successful.
-
-sed scripts listed in the *Useful Commands* section may help you doing the
-work.
-
-* create `proj/config`
- + see [project](project.html)
- + `proj/name` and `proj/default-results` become obsolete. Remove them.
-* fix the chroot configuration (proj/chroot)
- + see [chroot](chroot.html)
-* fix the licence configuration (proj/licences)
- + see [licences](licences.html)
-* fix the source configuration files (src/*/config)
- + see [sources](sources.html)
- + rename the `name` attribute to `location` for *files* sources
- + the `server` attribute can now be specified once on the top-level
- and is inherited by each single file, for *files* sources
- + rename the `remote` attribute to `location` for git sources
- + the `working` attribute for all scm sources has a builtin default
- now: `in/<sourcename>`. No need to specify it any more.
-* fix the result configuration (res/*/config)
- + see [results](results.html)
- + the `files` attribute was removed. The tools will only warn, but
- work anyway.
-
-#### Finish the migration ####
-
-* fetch sources and build with all warnings enabled
-* read the warnings and error messages
-
-The commands:
-
- $ e2-fetch-sources
- $ e2-build --Wall
-
-The basic migration is done now. Create the commit now and push:
-
- $ git commit -m 'migrate to e2-2.2.0'
- $ git push
-
-#### Useful commands ####
-
-Be careful when using these commands. They will do in many cases, but they
-are not reliable. They will even do nonsense, if the patterns match in the
-wrong places. Review the resulting diff before committing changes!
-
- $ sed -i s,'group=','name=', proj/chroot
- $ sed -i s,'group =','name =', proj/chroot
- $ sed -i s,'name =','location =', src/*/config
- $ sed -i s,'name=','location=', src/*/config
- $ sed -i s,'remote =','location =', src/*/config
- $ sed -i s,'remote=','location=', src/*/config
-
-prev [release](release.html)
-next [faq](faq.html)
+++ /dev/null
-Project
--------
-
-
-*e2factory* needs some configuration information to run, that is collected in the
-project configuration.
-
-To setup the project configuration call the e2project function with a
-table argument.
-
-The table must specify the following keys:
-
-* release_id string: release identifier
-* name string: project name
-* default_results table: list of results to build by default
-* deploy_results table: list of results to deploy to archive in release mode
-
-The table may specify the following additional keys:
-
-* chroot\_arch string: architecture to use when running the build process
- x86\_64 or x86\_32 may be used, the latter is the builtin default.
-
-The `release_id` and `name` settings appear as `E2_RELEASE_ID` and
-`E2_PROJECT_NAME` respectively in the environment when the build script runs.
-The `release_id` is used to compute the path where the results are stored
-when building in release mode. The `name` is used to compute the path to
-the chroot build environment.
-
-Example:
-
- e2project {
- name = "foo",
- release_id = "foo-1.0beta",
- default_results = {
- "foo",
- },
- deploy_results = {
- "bar",
- },
- chroot_arch = "x86_32",
- }
-
-prev [environment](environment.html)
-next [chroot](chroot.html)
+++ /dev/null
-Building releases
------------------
-
-
-Prepare building a release with *e2factory*:
-
-* for each scm source:
- * make sure the source is tagged and the tag is configured in the
- source configuration
-* change the release_id attribute in proj/config to the release string
-* commit the file
-* push
-* build in release mode
-* e2factory will store the results listed in the `deploy_results`
- attribute in the project configuration to the releases server.
- The location will be `releases:<project-location>/archive/<release-id>/`
-
-Example:
-
- $ e2-fetch-project project
- $ cd project
- $ e2-fetch-sources
- $ e2-build --build-mode=release
-
-prev [results](results.html)
-next [Migrating to newer versions of e2factory](migration.html)
+++ /dev/null
-Results
--------
-
-
-To create a result in the configuration call the e2result function
-with a table argument. Usually a source configures one or more of the
-following keys:
-
-* sources list of sources
-* chroot list of chroot groups
-* depends list of dependencies
-* env dictionary of environment variables
-
-To use the `collect_project` feature the following keys must be used
-in addition:
-
-* `collect_project` boolean: enable the collect_project flag for this result
-* `collect_project_default_result` string: name of the result that should
- be reproducable
-
-In addition creating a `build-script` is required. The build script must
-be stored in `./res/<name>/build-script` and runs in the build environment.
-
-It is possible to group the results in subfolders. When a folder for a result does
-NOT contain a config file e2 factory tries to search its subfolders for further
-results. To name results in subfolders you have to add the foldername to the result name
-separated with a dot (e.g. xorg.libXau). This occurrs when specify dependencies oder sources.
-
-The `collect_project` flag provides a tree holding everything to rebuild
-the result configured in `collect_project_default_result` in $E2_TMPDIR/project.
-The user must write a build-script to package that tree to a file in
-$E2_TMPDIR/out
-
-All configuration options can be combined. And even a configuration with
-no keys is valid: The `base` chroot group is used automatically, and the
-`build-script` runs and may create a result.
-
-Example configuration:
-
- e2result {
- chroot = {
- "autotools",
- },
- sources = {
- "hello",
- "hello-config",
- },
- depends = {
- "toolchain",
- },
- env = {
- key = "val",
- },
- }
-
-Example (using the `collect_project` flag)
-
- e2result {
- collect_project = true,
- collect_project_default_result = "bsp",
- sources = { },
- depends = { },
- }
-
-Example build script:
-
- DESTDIR=$E2_TMPDIR/root
- make hello
- make DESTDIR=$DESTDIR install
- tar -C $DESTDIR -czf $E2_TMPDIR/out/$E2_RESULT.tar.gz .
-
-prev [sources](sources.html)
-next [release](release.html)
+++ /dev/null
-Sources
--------
-
-
-To create a source from the configuration call the e2source function,
-with a table argument. The table must use the following keys:
-
-generic configuration:
-
-* type: string
-* server: string
-* licences: (old: licence) table of strings
-* env: dictionary, merged into result specific env for results that use
- this source
-
-files source (type = files, default)
-
-* file: file configuration table
- * server string: server name (optional, inherited from top-level)
- * licences table of strings (optional, inherited from top-level)
- * location (old: name) string: file location
- * unpack string: the directory included in the source package
- * patch string: strip n directories when
- * copy string: the directory to copy the file into, relative to
-
-Example:
-
- e2source {
- type = "files",
- server = "upstream",
- licences = { "gpl2" },
- file = {
- {
- location = "z/zlib/1.2.3/zlib-1.2.3.tar.gz",
- unpack = "zlib-1.2.3",
- -- sha1 is required if server is not "."
- sha1 = "60faeaaf250642db5c0ea36cd6dcc9f99c8f3902",
- },
- }
- }
-
-cvs source (type = cvs)
-
-* server
-* cvsroot
-* module
-* working
-* branch
-* tag
-
-Example:
-
- e2source {
- type = "cvs",
- licence = "gpl2",
- server = "cvs-server",
- cvsroot = ".",
- module = "hello",
- branch = "HEAD",
- tag = "hello-1.0",
- }
-
-svn source (type = svn)
-
-* server
-* location
-* branch
-* tag
-* workingcopy_subdir
-
-Example:
-
- e2source {
- type = "svn",
- licence = "gpl2",
- server = "svn-server",
- location = "svn-repo",
- branch = "trunk",
- --branch = "branches/hello-1.0",
- tag = "tags/hello-1.0",
- --workingcopy_subdir = "trunk", -- defaults to the branch directory
- }
-
-git source (type = git)
-
-* server
-* remote (rename to: location)
-* working
-* branch
-* tag table: list of tags, the last one is used for building
-
-Example:
-
- e2source {
- type = "git",
- licence = "gpl2",
- server = "git-server",
- remote = "git/h/hello.git",
- branch = "master",
- tag = "hello-1.0",
- }
-
-subversion source (type = svn)
-
-* ...
-
-prev [licences](licences.html)
-next [results](results.html)
projects / e2factory.git / commitdiff
