Difference between pages "Funtoo:Metro/Data Model" and "Package:Boot-Update"

From Funtoo
< Funtoo:Metro(Difference between pages)
Jump to navigation Jump to search
 
 
Line 1: Line 1:
== Goals ==
{{Ebuild
|Summary=Funtoo Core Boot Framework for global boot loader configuration
|CatPkg=sys-boot/boot-update
|Maintainer=Drobbins
|Repository=Funtoo Overlay
|Organization=Funtoo Technologies
|Overlay=Funtoo
}}
Funtoo boot-update provides a unified mechanism for configuring the GRUB 1.9x ({{Package|sys-boot/grub}}) and GRUB 0.97 ({{Package|sys-boot/grub-legacy}}) boot loaders. It is the recommended, official way to configure Funtoo Linux systems for booting.


The Metro Data Model has been designed to provide you with an optimal way to organize build data.
== Current Version ==


Here are the primary goals for the data model:
* {{Package|sys-boot/boot-update}}


# Provide useful ways to organize data
== Man Pages ==
# Use mechanisms and syntax that maximize maintainability of the data over time
Consult the following man pages for detailed, up-to-date information on configuration file settings and command-line arguments:
# Reduce and (ideally) eliminate side-effects at every opportunity


To attain these goals, I've used a functional data model, where an element (variable) can be defined only once, and cannot be redefined.
* boot-update(8)
* boot.conf(5)


''By default, the Metro parser operates in &quot;strict&quot; mode, which means that it will throw an error if a variable has been referenced that has not been defined. This &quot;strict&quot; mode is actually very useful in catching errors that might otherwise go unnoticed and result in broken builds.''
{{:Install/BootLoader}}


In addition, the Metro parser was designed so that the order in which data elements are defined is not important, even if they reference one another. This was done to eliminate side-effects related to data ordering, where changing the order in which things are defined in a file can change the behavior of or break your code.
=== GRUB 0.97 (grub-legacy) Quick Start ===


Versions of Metro prior to 1.4 contained limited support for conditional logic. After some experimentation, I've decided that the conditional support is not necessary, and it is not used by Metro 1.4. However, support for conditionals still exist in the parser, but will be removed when the parser is rewritten.
If using <code>sys-boot/grub-legacy-0.97</code>, perform the following steps:


* Partition disk using MBR partitions '''(GPT not supported)'''
* Install kernel/initrd to <code>/boot</code>


== First Look ==
<console>
###i## emerge sys-boot/boot-update
###i## emerge ">=sys-boot/grub-legacy-0.97-r11"
###i## grub-install-legacy /dev/sda
</console>
Due to an issue with <code>grub-legacy</code>, you may see the following message:
<console>
###i## grub-install-legacy /dev/sda
The file /boot/grub-legacy/stage1 not read correctly.
</console>
Should you receive this message, you will have to install <code>grub-legacy</code> from the grub shell.
Assuming <code>/boot</code> is the partition <code>/dev/sda1</code> and you want to install grub to the MBR, you would run the following:
<console>
###i## grub-legacy
root (hd0,0)
setup (hd0)
quit
</console>
When adjusting to fit your setup, remember 'root' is the location of your boot partition, 'setup' is where you want to install grub, and don't forget about grub's unique naming conventions for hard drives / partitions. For more information run:
<console>
###i## info grub-legacy
</console>


Here is some sample Metro data:
Ensure that <code>/etc/fstab</code> is correct, and edit <code>/etc/boot.conf</code> to reflect your installation.
Ensure a <code>generate grub-legacy</code> setting in the <code>boot</code> section. Then run:


<pre>path: /usr/bin</pre>
<console>
Above, we have defined the element <tt>path</tt> to have the value <tt>/usr/bin</tt>. <tt>path</tt> is a single-line element, and the Metro parser takes care of trimming any trailing whitespace that may be on the line. You can also define single-line elements that have values that consist of multiple whitespace-separated values:
###i## boot-update
</console>
This will auto-generate the <code>/boot/grub-legacy/grub.conf</code> required for booting. Note that <code>grub-legacy-0.97-r11</code> and later stores <code>grub.conf</code> in the <code>/boot/grub-legacy</code> directory.


<pre>options: ccache replace</pre>
Re-run <code>boot-update</code> every time your available kernels / initrds or <code>/etc/boot.conf</code> configuration changes.
Sometimes, you need to define an element but leave it blank. To do this, don't specify any values after the colon:


<pre>options:</pre>
[[Category:Projects]]
In Metro, the <tt>/</tt> character is used to delineate various classes of elements, as follows:
[[Category:Funtoo features]]
 
{{EbuildFooter}}
<pre>path/mirror: /home/mirror/linux
path/mirror/snapshot: /home/mirror/linux/snapshots
path/metro: /usr/lib/metro</pre>
Above, we see the proper Metro convention for specifying paths. Each path has a prefix of <tt>path/</tt>. We have a <tt>path/mirror</tt> element but also have a <tt>path/mirror/snapshot</tt> element. The <tt>/</tt> is used to organize our data into logical groups. This is not enforced by Metro but is presented here as a best practice.
 
The data above could also be represented using a ''section annotation'', as follows:
 
<pre>[section path]
 
mirror: /home/mirror/linux
mirror/snapshot: /home/mirror/linux/snapshots
metro: /usr/lib/metro</pre>
Above, the <tt>[section path]</tt> line is a section annotation, and it tells the Metro parser that the <tt>path/</tt> prefix should be applied to all following data elements. A section annotation is in effect until another section annotation is encountered by the parser.
 
While our data above is getting more organized, there is some redundancy in our data, which generally isn't a good thing. Here's an example of how to make our data a bit more compact:
 
<pre>[section path]
 
mirror: /home/mirror/linux
mirror/snapshot: $[path/mirror]/snapshots
metro: /usr/lib/metro</pre>
Above, we have used an ''element reference'' of <tt>$[path/mirror]</tt> to reference our <tt>path/mirror</tt> element. What this means is that <tt>path/snapshot</tt> will have a value of <tt>/home/mirror/linux/snapshots</tt>.
 
Also, it's worth pointing out that we could just have well written:
 
 
<pre>[section path]
 
mirror/snapshot: $[path/mirror]/snapshots
mirror: /home/mirror/linux
metro: /usr/lib/metro</pre>
In other words, it's perfectly OK to use the element reference of <tt>$[path/mirror]</tt> on a line ''before'' the actual definition of <tt>path/mirror</tt>. Metro doesn't care about the order in which data is defined.
 
Metro provides another way to organize your data in an efficient way. Supposing that you had a lot of <tt>path/mirror</tt>-related data, then it might be useful to organize your data as follows:
 
<pre>[section path]
 
metro: /usr/lib/metro
 
[section path/mirror]
 
: /home/mirror/linux
snapshot: $[]/snapshot
source: $[]/$[source/subarch]/funtoo-$[source/subarch]-$[source/version]/$[source/name].tar.bz2</pre>
Above, we have used two new parser features. Inside <tt>[section path/mirror]</tt>, we can define the <tt>path/mirror</tt> element itself by using a blank element name, followed by a <tt>:</tt>. The next parser feature we see above is that we can use <tt>$[]</tt> to reference the value of the <tt>path/mirror</tt> value. <tt>$[]</tt> will always reference the value of the element specified in the section annotation. Also note that as of Metro 1.1, <tt>$[:]</tt> can be used as an alternate form of <tt>$[]</tt>. In addition, as of Metro 1.2.4, <tt>$[:foo]</tt> can be used as an alternate form of <tt>$[section-name/foo]</tt>.
 
== Collect Annotations ==
 
Many scripting languages have the notion of an &quot;include&quot; file, or &quot;importing&quot; additional data from a remote file. Metro has this concept as well, but it is implemented in a somewhat different way. You can tell Metro to include data from another file by using a ''collect annotation''.
 
A collect annotation looks like this:
 
<pre>[collect $[path/metro]/myfile.txt]</pre>
Now, we called these things &quot;collect annotations&quot; for a reason - in Metro, they work slightly differently than most languages implement <tt>include</tt> and <tt>import</tt>. The main difference is that in Metro, a collect annotation does not happen right away. Instead, Metro will add the file to be collected (in this case, that would be the file <tt>/usr/lib/metro/myfile.txt</tt>, or whatever <tt>$[path/metro]/myfile.txt</tt> evaluates to) to a ''collection queue''. This means that Metro will read in the contents of the file at some point in time, and the data in the file will be available to you by the time the parsing is complete. But because Metro doesn't care about the order in which data is defined, it doesn't have the same concept of &quot;read in the data - right now!&quot; that an include or import statement does in other languages.
 
=== Conditional Collect Annotations ===
 
Metro no longer officially supports conditional collect annotations; however, simple collect annotations can be used to make conditional decisions in Metro, as follows:
 
<pre>[collect ./snapshots/$[snapshot/type]]</pre>
Above, Metro will collect from a file based on the value of the <tt>$[snapshot/type]</tt> element. This allows for varying definitions of elements to exist dependent on the value of <tt>$[snapshot/type]</tt>.
 
Above, Metro will raise an exception if <tt>$[snapshot/type]</tt> is undefined or has a value that does not map to a file on disk. If it is possible that <tt>$[snapshot/type]</tt> may not be defined, use the following format:
 
<pre>[collect ./snapshots/$[snapshot/type:zap]]</pre>
Using the <tt>:zap</tt> modifier, the entire collect argument will be replaced with the empty string if <tt>$[snapshot/type]</tt> is undefined. If Metro is asked to collect an empty string, it will not throw an exception. So this is a handy way to conditionally disable collection of a file. But please note that for all non-null values of <tt>$[snapshot/type]</tt>, a corresponding file must exist on disk in <tt>./snapshots/</tt> or Metro will throw an exception. <tt>:zap</tt> is explained in more detail in the &quot;Special Variable Expansion&quot; section, below.
 
== Multi-line elements ==
 
Metro supports multi-line elements and they are the foundation of Metro's ''template'' engine. A multi-line element can be defined as follows, by using square brackets to delimit multi-line data:
 
<pre>myscript: [
#!/bin/bash
echo $*
]</pre>
The terminating closing square bracket should be on a line all by itself.
 
One of the very useful things about multi-line elements is that they support Metro element references:
 
<pre>myscript: [
#!/bin/bash
echo Metro's path/metro setting is $[path/metro].
]</pre>
In the above multi-line element, the <tt>$[path/metro]</tt> reference will be expanded to contain the appropriate value of the element. It is possible to expand single-line elements inside multi-line elements simply by referencing them using a dollar sign and square brackets.
 
Metro also allows you to expand multi-line elements inside other multi-line elements. Here's an example of how that works:
 
<pre>myscript: [
#!/bin/bash
$[[steps/setup]]
echo Hi There :)
]</pre>
 
[[Category:Metro]]

Revision as of 18:18, January 11, 2015

Boot-Update

   Tip

We welcome improvements to this page. To edit this page, Create a Funtoo account. Then log in and then click here to edit this page. See our editing guidelines to becoming a wiki-editing pro.

Funtoo boot-update provides a unified mechanism for configuring the GRUB 1.9x (No results) and GRUB 0.97 (No results) boot loaders. It is the recommended, official way to configure Funtoo Linux systems for booting.

Current Version

Man Pages

Consult the following man pages for detailed, up-to-date information on configuration file settings and command-line arguments:

  • boot-update(8)
  • boot.conf(5)

Installing a Bootloader

These install instructions show you how to use GRUB to boot using BIOS (old-school) or UEFI (new-school). As of boot-update-1.7.2, now in Portage, the steps are very similar.

First, emerge boot-update. This will also cause grub-2 and efibootmgr to be merged, since they are dependencies: 

(chroot) # emerge boot-update

Then, edit /etc/boot.conf using nano and specify "Funtoo Linux genkernel" as the default setting at the top of the file, replacing "Funtoo Linux".

/etc/boot.conf should now look like this:

   /etc/boot.conf 
boot {
	generate grub
	default "Funtoo Linux genkernel" 
	timeout 3 
}

"Funtoo Linux" {
	kernel bzImage[-v]
}

"Funtoo Linux genkernel" {
	kernel kernel[-v]
	initrd initramfs[-v]
	params += real_root=auto 
} 

"Funtoo Linux better-initramfs" {
	kernel vmlinuz[-v]
	initrd /initramfs.cpio.gz
}

If you are booting a custom or non-default kernel, please read man boot.conf for information on the various options available to you.

Old School (BIOS) MBR

When using "old school" BIOS booting, run the following command to install GRUB to your MBR, and generate the /boot/grub/grub.cfg configuration file that GRUB will use for booting: 

(chroot) # grub-install --target=i386-pc --no-floppy /dev/sda
(chroot) # boot-update

New School (UEFI) Boot Entry

If you're using "new school" UEFI booting, run of the following sets of commands, depending on whether you are installing a 64-bit or 32-bit system. This will add GRUB as a UEFI boot entry.

For x86-64bit systems: 

(chroot) # grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id="Funtoo Linux [GRUB]" --recheck /dev/sda
(chroot) # boot-update

For x86-32bit systems: 

(chroot) # grub-install --target=i386-efi --efi-directory=/boot --bootloader-id="Funtoo Linux [GRUB]" --recheck /dev/sda
(chroot) # boot-update

First Boot, and in the future...

OK -- you are ready to boot!

You only need to run grub-install when you first install Funtoo Linux, but you need to re-run boot-update every time you modify your /etc/boot.conf file or add new kernels to your system. This will regenerate /boot/grub/grub.cfg so that you will have new kernels available in your GRUB boot menu, the next time you reboot.

GRUB 0.97 (grub-legacy) Quick Start

If using sys-boot/grub-legacy-0.97, perform the following steps:

  • Partition disk using MBR partitions (GPT not supported)
  • Install kernel/initrd to /boot
root # emerge sys-boot/boot-update
root # emerge ">=sys-boot/grub-legacy-0.97-r11"
root # grub-install-legacy /dev/sda

Due to an issue with grub-legacy, you may see the following message: 

root # grub-install-legacy /dev/sda
The file /boot/grub-legacy/stage1 not read correctly.

Should you receive this message, you will have to install grub-legacy from the grub shell. Assuming /boot is the partition /dev/sda1 and you want to install grub to the MBR, you would run the following: 

root # grub-legacy
root (hd0,0)
setup (hd0)
quit

When adjusting to fit your setup, remember 'root' is the location of your boot partition, 'setup' is where you want to install grub, and don't forget about grub's unique naming conventions for hard drives / partitions. For more information run: 

root # info grub-legacy

Ensure that /etc/fstab is correct, and edit /etc/boot.conf to reflect your installation. Ensure a generate grub-legacy setting in the boot section. Then run: 

root # boot-update

This will auto-generate the /boot/grub-legacy/grub.conf required for booting. Note that grub-legacy-0.97-r11 and later stores grub.conf in the /boot/grub-legacy directory.

Re-run boot-update every time your available kernels / initrds or /etc/boot.conf configuration changes.


Retrieved from "https://www.funtoo.org/index.php?title=Funtoo:Metro/Data_Model&oldid=8582"