Difference between pages "Forking An Ebuild" and "Boot Methods"

(Difference between pages)
m
 
(Pure UEFI)
 
Line 1: Line 1:
Often, a Funtoo developer needs to fork an upstream ebuild. This is necessary when we want to apply fixes to it. This page will explain the concepts of forking and how this works in the context of Funtoo.
+
This page describes the various methods that can be used to set up a disk to boot Funtoo Linux. If you have more than one disk, choose a single disk to serve as your boot disk.
  
== Portage Tree Generation ==
+
=== Pure MBR + GRUB ===
  
Funtoo Linux generates its Portage tree using a special script that essentially takes a Gentoo tree as its starting point, and then applies various modifications to it. The modifications involve adding packages from various overlays, including our [[Overlay:Funtoo-overlay]]. Some packages added are brand new, while other packages are our special forked versions that replace existing packages.
+
This option is the "classic" way to boot Funtoo Linux and uses traditional MBR partitions, which have existed since the origin of the PC. Here is the typical disk layout:
  
In the vast majority of cases, when we fork a package, we take full responsibility for all ebuilds associated with that package, meaning that we have a full copy of the <tt>sys-foo/bar</tt> directory in one of our overlays.
+
* MBR at beginning of boot disk
 +
* MBR partition 1, <tt>/dev/sda1</tt> is the <tt>/boot</tt> filesystem (typically ext2)
 +
* MBR partition 2, <tt>/dev/sda2</tt> is ''swap''.
 +
* MBR partition 3, <tt>/dev/sda3</tt> is the <tt>/</tt> (root) filesystem.
  
If you're interested in seeing the actual script that does all these things, take a look at the following files:
+
Here's how the boot process works:
  
; http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/current-update.sh: cronned script that calls <tt>merge.py</tt>.
+
# The system BIOS loads the MBR from your boot disk (containing stage1 of the GRUB boot loader) and runs it.
;http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge.py: python script that does the heavy lifting of combining Gentoo tree with various overlays, including our flora and funtoo-overlay. When we want to change what overlays we merge, what packages we exclude as a matter of policy (such as stale packages in some overlays), we make changes to this file.
+
# Extra boot-related code is loaded by the GRUB stage1 from the <tt>/boot</tt> filesystem on the disk.
; http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge_utils.py: python module that contains classes and methods that implement the merging functionality.
+
  
== Forking an Ebuild ==
+
Now, the boot loader is able to run and load the Linux kernel and initramfs, and start Funtoo Linux.
  
In general, we fork ebuilds from Gentoo that we want to modify in some way. Before you fork an ebuild, it's important to understand that in general we fork entire packages, not just a single ebuild. This means that if you want to make some changes to <tt>sys-foo/bar</tt>, you are going to fork all <tt>sys-foo/bar</tt> ebuilds, and then Funtoo will be responsible for continuing to maintain these ebuilds until the package is unforked. Here are the steps we would use to fork <tt>sys-foo/bar</tt>:
+
=== GPT + GRUB ===
  
# Find <tt>sys-foo/bar</tt> in you regular Portage tree. Make sure you have run <tt>emerge --sync</tt> recently to ensure it is up-to-date. If you want to fork from very recent changes that are not yet in our tree, you may need to grab the most recent Gentoo Portage tree to serve as your source for <tt>sys-foo/bar</tt> (this typically isn't necessary.)
+
This is a more modern way to boot Linux. It uses MBR for booting but uses the more modern GPT partition scheme. Here's the disk layout:
# Copy the <tt>sys-foo/bar</tt> directory in its entirety to <tt>funtoo-overlay/sys-foo/bar</tt>.
+
# Make any necessary modifications to <tt>funtoo-overlay/sys-foo/bar</tt>.
+
# Perform some funtoo-ification steps prior to commit.
+
# Add and commit the changes to funtoo-overlay.
+
# Push changes to funtoo-overlay.
+
  
At this point, the forked <tt>sys-foo/bar</tt> package will be part of funtoo-overlay. The next time our unified Portage tree is generated by <tt>merge.py</tt> (the one that users have in their <tt>/usr/portage</tt> and is updated via <tt>emerge --sync</tt>), your forked ebuild will be used in place of the Gentoo ebuild. Why is this? It is because our <tt>merge.py</tt> script has been defined with a policy that any ebuilds in funtoo-overlay will replace any existing Gentoo ebuilds if they exist. The mechanism of replacement is that our <tt>sys-foo/bar</tt> directory will be used in place of Gentoo's <tt>sys-foo/bar</tt> directory. So this is how the forking process works.
+
* ''no MBR is installed or required''
 +
* GPT partition 1, <tt>/dev/sda1</tt> is the <tt>/boot</tt> filesystem (typically ext2)
 +
* GPT partition 2 type 0xEF02, <tt>/dev/sda2</tt> is the ''boot loader partition'' (this contains a fake MBR).
 +
* GPT partition 3, <tt>/dev/sda3</tt> is ''swap''.
 +
* GPT partition 4, <tt>/dev/sda4</tt> is the <tt>/</tt> (root) filesystem.
  
== Funtoo-ification ==
+
Here's how this hybrid scheme works:
  
When we fork a package from Gentoo, we perform the following tweaks to the package directory before committing:
+
# The system BIOS loads the fake MBR from your boot disk(/dev/sda2) (containing stage1 of the GRUB boot loader) and runs it.
 +
# Extra boot-related code is loaded by the GRUB stage1 from a small (a few MB) GPT partition on the disk.
  
# Removal of <tt>ChangeLog</tt>.
+
Now, the boot loader is able to run and load the Linux kernel and initramfs, and start Funtoo Linux.
# Run <tt>ebuild foo-1.0.ebuild digest</tt> before committing. This will cause the <tt>Manifest</tt> file to be regenerated. Gentoo has a lot more entries in this file than we do, since we use mini-Manfiests that only include DIST listings (for distfiles only.) We want to commit our mini-Manifest (still called <tt>Manifest</tt>, just with less entries in it) rather than the one that came from Gentoo.
+
# Edit the top of each ebuild, and remove all <tt>Copyright</tt> and <tt>$Header:</tt> lines at the top of the file. We have a LICENSE.txt and COPYRIGHT.txt file in the root of our Portage tree, which is easier to maintain than keeping all the years up-to-date in each ebuild. Also, the <tt>$Header:</tt> line is there for the CVS version control system in Gentoo which Funtoo does not use. ''The only comment that should remain on the top of the ebuild is the one stating that it is distributed under the GPLv2.''.
+
  
Here are a few additional changes that you are allowed to make to any forked ebuilds:
+
=== UEFI + GRUB ===
  
# Line length greater than 80 characters. Gentoo enforces an 80-character line length limit. We don't.
+
UEFI is a new-style firmware that is used for booting. It is generally available on all new PCs (2012 and newer) and may be available on older systems as well. Here's the disk layout:
# <tt>KEYWORDS</tt> of <tt>*</tt> and <tt>~*</tt>. Gentoo does not allow these shortcuts. We do. They allow you to say "all arches" and "all unstable arches" in a concise way. Gentoo doesn't allow these shortcuts because it's Gentoo's policy to have each arch team manually approve each package. We do not have this policy so we can use the shortcuts.
+
# Use of <tt>4-python</tt> EAPI. We allow the use of this EAPI for enhanced python functionality.
+
  
[[Category:Development]]
+
* ''no MBR is installed or required''
 +
* GPT partition 1, <tt>/dev/sda1</tt> is the <tt>/boot</tt> filesystem (<tt>vfat</tt> aka "FAT32").
 +
* GPT partition 2, <tt>/dev/sda2</tt> is ''swap''.
 +
* GPT partition 3, <tt>/dev/sda3</tt> is the <tt>/</tt> (root) filesystem.
 +
 
 +
Here's how this boot scheme works:
 +
 
 +
# UEFI (contained in your motherboard's firmware) loads the Bootmanager entry from the RW NVRAM inside your motherboard.
 +
# If there's a valid entry that contains Grub, then the GRUB boot loader code from your <tt>/boot</tt> filesystem will be loaded.
 +
# UEFI can read from <tt>vfat</tt> partitions directly, which is why we use <tt>vfat</tt> instead of the normal <tt>ext2</tt> for <tt>/boot</tt>.
 +
 
 +
Now, the boot loader is able to run and load the Linux kernel and initramfs from the <tt>vfat</tt> <tt>/boot</tt> filesystem, and start Funtoo Linux.
 +
 
 +
=== Pure UEFI ===
 +
 
 +
A Pure UEFI boot is also possible. The partitioning scheme is the same as the UEFI + GRUB scheme, above.
 +
 
 +
Here's how this boot scheme works:
 +
 
 +
# UEFI (contained in your motherboard's firmware) loads the Bootmanager entry from the RW NVRAM inside your motherboard.
 +
#  UEFI loads the Linux kernel STUB and initramfs directly, and runs the Linux kernel to start Funtoo Linux.

Revision as of 11:56, January 23, 2013

This page describes the various methods that can be used to set up a disk to boot Funtoo Linux. If you have more than one disk, choose a single disk to serve as your boot disk.

Pure MBR + GRUB

This option is the "classic" way to boot Funtoo Linux and uses traditional MBR partitions, which have existed since the origin of the PC. Here is the typical disk layout:

  • MBR at beginning of boot disk
  • MBR partition 1, /dev/sda1 is the /boot filesystem (typically ext2)
  • MBR partition 2, /dev/sda2 is swap.
  • MBR partition 3, /dev/sda3 is the / (root) filesystem.

Here's how the boot process works:

  1. The system BIOS loads the MBR from your boot disk (containing stage1 of the GRUB boot loader) and runs it.
  2. Extra boot-related code is loaded by the GRUB stage1 from the /boot filesystem on the disk.

Now, the boot loader is able to run and load the Linux kernel and initramfs, and start Funtoo Linux.

GPT + GRUB

This is a more modern way to boot Linux. It uses MBR for booting but uses the more modern GPT partition scheme. Here's the disk layout:

  • no MBR is installed or required
  • GPT partition 1, /dev/sda1 is the /boot filesystem (typically ext2)
  • GPT partition 2 type 0xEF02, /dev/sda2 is the boot loader partition (this contains a fake MBR).
  • GPT partition 3, /dev/sda3 is swap.
  • GPT partition 4, /dev/sda4 is the / (root) filesystem.

Here's how this hybrid scheme works:

  1. The system BIOS loads the fake MBR from your boot disk(/dev/sda2) (containing stage1 of the GRUB boot loader) and runs it.
  2. Extra boot-related code is loaded by the GRUB stage1 from a small (a few MB) GPT partition on the disk.

Now, the boot loader is able to run and load the Linux kernel and initramfs, and start Funtoo Linux.

UEFI + GRUB

UEFI is a new-style firmware that is used for booting. It is generally available on all new PCs (2012 and newer) and may be available on older systems as well. Here's the disk layout:

  • no MBR is installed or required
  • GPT partition 1, /dev/sda1 is the /boot filesystem (vfat aka "FAT32").
  • GPT partition 2, /dev/sda2 is swap.
  • GPT partition 3, /dev/sda3 is the / (root) filesystem.

Here's how this boot scheme works:

  1. UEFI (contained in your motherboard's firmware) loads the Bootmanager entry from the RW NVRAM inside your motherboard.
  2. If there's a valid entry that contains Grub, then the GRUB boot loader code from your /boot filesystem will be loaded.
  3. UEFI can read from vfat partitions directly, which is why we use vfat instead of the normal ext2 for /boot.

Now, the boot loader is able to run and load the Linux kernel and initramfs from the vfat /boot filesystem, and start Funtoo Linux.

Pure UEFI

A Pure UEFI boot is also possible. The partitioning scheme is the same as the UEFI + GRUB scheme, above.

Here's how this boot scheme works:

  1. UEFI (contained in your motherboard's firmware) loads the Bootmanager entry from the RW NVRAM inside your motherboard.
  2. UEFI loads the Linux kernel STUB and initramfs directly, and runs the Linux kernel to start Funtoo Linux.