summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPatrick Georgi <patrick@georgi-clan.de>2015-02-05 23:36:32 +0100
committerPatrick Georgi <pgeorgi@google.com>2015-02-13 09:33:24 +0100
commit3c28d014b7b6d49f2daa33d03008a5355f7aa305 (patch)
treed0847ea5dc268b6ee9d5983c8d82aa7b8982f6f3
parentb32bf54c31aacce1f0824fa3f938f1cc9d8ebf4f (diff)
downloadcoreboot-3c28d014b7b6d49f2daa33d03008a5355f7aa305.tar.xz
documentation: begin documenting our use of git submodules
git submodules have some surprising behaviour, and we make full use of it. Start building a canonical resource for that so developers can spend their time on better things than on fighting git. Change-Id: I5aa721e9b0acb2912a057858fd23a1d59d845ed1 Signed-off-by: Patrick Georgi <patrick@georgi-clan.de> Reviewed-on: http://review.coreboot.org/8371 Tested-by: build bot (Jenkins) Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org> Reviewed-by: Alexandru Gagniuc <mr.nuke.me@gmail.com>
-rw-r--r--documentation/submodules.txt46
1 files changed, 46 insertions, 0 deletions
diff --git a/documentation/submodules.txt b/documentation/submodules.txt
new file mode 100644
index 0000000000..631e351303
--- /dev/null
+++ b/documentation/submodules.txt
@@ -0,0 +1,46 @@
+Use of git submodules in coreboot
+=================================
+coreboot uses git submodules to keep certain parts of the tree separate,
+with two major use cases:
+
+First, we use a vendor tool by NVIDIA for systems based on their SoC
+and since they publish it through git, we can just import it into our
+tree using submodules.
+
+Second, lots of boards these days require binaries and we want to keep
+them separate from coreboot proper to clearly delineate shiny Open Source
+from ugly blobs.
+Since we don't want to impose blobs on users who really don't need them,
+that repository is only downloaded and checked out on explicit request.
+
+Handling submodules
+-------------------
+For the most part, submodules should be automatically checked out on the
+first execution of the coreboot Makefile.
+
+To manually fetch all repositories (eg. when you want to prepare the tree
+for archiving, or to use it without network access), run
+
+ $ git submodule update --init --checkout
+
+This also checks out the binaries below `3rdparty/`
+
+Mirroring coreboot
+------------------
+When running a coreboot mirror to checkout from, for full operation, you
+should also mirror the blobs and nvidia-cbootimage repository, and place
+them in the same directory as the coreboot repository mirror.
+
+That is, when residing in coreboot's repository, `cd ../blobs.git`
+should move you to the blobs repository.
+
+With that, no matter what the URL of your coreboot repository is, the
+git client (of a sufficiently new version) is able to pick up the other
+repositories transparently.
+
+Minimum requirements
+--------------------
+git needs to be able to handle relative paths to submodule repositories,
+and it needs to know about non-automatic submodules.
+
+For these features, we require git version 1.7.6.1 or newer.