Difference between revisions of "Directives/append"

From Syslinux Wiki
Jump to: navigation, search
m (Remove blank empty unnecessary lines.)
m (Add Category. Add TOC. Wiki formatting.)
Line 1: Line 1:
 
[[Category:Directives]]
 
[[Category:Directives]]
 +
[[Category:Examples]]
 
For a basic explanation of the APPEND directive see [[Config#APPEND]].
 
For a basic explanation of the APPEND directive see [[Config#APPEND]].
 +
__TOC__
  
 
<!-- Potential additional sections could be added, such as -->
 
<!-- Potential additional sections could be added, such as -->
Line 30: Line 32:
  
 
Since version 5.00, the result for the above sample configuration is  
 
Since version 5.00, the result for the above sample configuration is  
that the {{nowrap|1="<tt>root=/dev/sda2</tt>"}} argument is not parsed,  
+
that the {{nowrap|1="<code>root=/dev/sda2</code>"}} argument is not parsed,  
 
which will lead to unexpected results,  
 
which will lead to unexpected results,  
 
most probably with some kind of failure to boot the OS.  
 
most probably with some kind of failure to boot the OS.  
Line 59: Line 61:
 
The effect of the global APPEND on the resulting command depends on  
 
The effect of the global APPEND on the resulting command depends on  
 
whether the particular LABEL entry includes its own specific APPEND.
 
whether the particular LABEL entry includes its own specific APPEND.
 
+
{|
 +
|
 
<pre>
 
<pre>
 
 
 
   # The following is a global directive:
 
   # The following is a global directive:
 
   APPEND root=/dev/sda2
 
   APPEND root=/dev/sda2
Line 82: Line 84:
 
   KERNEL mykernel
 
   KERNEL mykernel
 
   APPEND -
 
   APPEND -
 
 
 
</pre>
 
</pre>
 +
|}
  
 
In the above example, the ''global'' APPEND is ignored by the DEFAULT  
 
In the above example, the ''global'' APPEND is ignored by the DEFAULT  
Line 104: Line 106:
 
entry has no influence on whether a ''global'' APPEND is effectively  
 
entry has no influence on whether a ''global'' APPEND is effectively  
 
used when executing such LABEL.
 
used when executing such LABEL.
 
+
{|
 +
|
 
<pre>
 
<pre>
 
 
 
   # The following is a global directive:
 
   # The following is a global directive:
 
   APPEND vga=normal
 
   APPEND vga=normal
Line 135: Line 137:
 
   INITRD myinitrd
 
   INITRD myinitrd
 
   APPEND some_additional_options
 
   APPEND some_additional_options
 
 
 
</pre>
 
</pre>
 +
|}
  
 
Normally, the following directive:  
 
Normally, the following directive:  
 
<pre>  INITRD myinitrd  </pre>
 
<pre>  INITRD myinitrd  </pre>
 
would be considered equivalent to  
 
would be considered equivalent to  
{{nowrap|1="<tt>APPEND initrd=myinitrd</tt>".}}  
+
{{nowrap|1="<code>APPEND initrd=myinitrd</code>".}}  
 
But when using ''global'' APPEND, a separate INITRD directive has a  
 
But when using ''global'' APPEND, a separate INITRD directive has a  
 
different effect, as shown in the above examples.
 
different effect, as shown in the above examples.
Line 181: Line 183:
 
entry together with a ''global'' APPEND would seem not possible.  
 
entry together with a ''global'' APPEND would seem not possible.  
 
One potential workaround would be:
 
One potential workaround would be:
 
+
{|
 +
|
 
<pre>
 
<pre>
 
   # The following is a global directive:
 
   # The following is a global directive:
Line 197: Line 200:
 
   KERNEL mykernel myappend
 
   KERNEL mykernel myappend
 
</pre>
 
</pre>
 +
|}
  
 
The effective result for ''mylabel'' is:
 
The effective result for ''mylabel'' is:
Line 225: Line 229:
 
<!-- Instead, start each line with a space character -->
 
<!-- Instead, start each line with a space character -->
 
<!--  -->
 
<!--  -->
 
+
{|
 +
|
 
   # The following would be a global directive,
 
   # The following would be a global directive,
 
   # but it is commented out:
 
   # but it is commented out:
Line 248: Line 253:
 
   KERNEL '''cmd.c32'''
 
   KERNEL '''cmd.c32'''
 
   APPEND <span style="color: purple;">mykernel_plus_global</span> <span style="color: navy;">myappend</span>
 
   APPEND <span style="color: purple;">mykernel_plus_global</span> <span style="color: navy;">myappend</span>
 
+
|}
 
<!-- -->
 
<!-- -->
  
 
In the above example, all LABEL entries have their own APPEND line.  
 
In the above example, all LABEL entries have their own APPEND line.  
 
When using 5.00 or newer, in fact the initial  
 
When using 5.00 or newer, in fact the initial  
''global'' {{nowrap|"<tt>APPEND global_append</tt>"}} line is not being  
+
''global'' {{nowrap|"<code>APPEND global_append</code>"}} line is not being  
 
used by any entry (that's why it is already commented out in the example).
 
used by any entry (that's why it is already commented out in the example).
  
 
When executing the <tt>mykernel_plus_global_plus_myappend</tt> label,  
 
When executing the <tt>mykernel_plus_global_plus_myappend</tt> label,  
 
the effective result is the  
 
the effective result is the  
{{nowrap|"<tt>mykernel global_append myappend</tt>"}} command.
+
{{nowrap|"<code>mykernel global_append myappend</code>"}} command.
  
 
See [[Cmd.c32]] for more examples.
 
See [[Cmd.c32]] for more examples.
Line 271: Line 276:
 
<!-- -->
 
<!-- -->
 
<!-- <nowiki> * [[Comboot/menu.c32]] </nowiki> -->
 
<!-- <nowiki> * [[Comboot/menu.c32]] </nowiki> -->
<!-- Intead of "Comboot/menu.c32", -->
+
<!-- Instead of "Comboot/menu.c32", -->
 
<!-- the [[Menu]] page is more up-to-date and easier to link-to, -->
 
<!-- the [[Menu]] page is more up-to-date and easier to link-to, -->
 
<!-- including linking to its sections. -->
 
<!-- including linking to its sections. -->
 
* [[Menu]]
 
* [[Menu]]

Revision as of 19:02, 15 February 2019

For a basic explanation of the APPEND directive see Config#APPEND.

global append

default

Take the following simple configuration:

  DEFAULT mykernel
  APPEND root=/dev/sda2

Note that the APPEND line here is a global directive, as it is not part of any LABEL entry.

For Syslinux 4.xx and older, the above simple configuration works as (it used to be) expected.

Since version 5.00, the result for the above sample configuration is that the "root=/dev/sda2" argument is not parsed, which will lead to unexpected results, most probably with some kind of failure to boot the OS. In other words, the global APPEND is ignored by the DEFAULT directive.

For the above example, the configuration could be re-written as:

  DEFAULT mykernel root=/dev/sda2

or even better as:

  DEFAULT mylabel
  LABEL mylabel
  KERNEL mykernel
  APPEND root=/dev/sda2

which "moves" the global APPEND line into the new LABEL entry.

Generally speaking, it is recommended to have at least one LABEL entry.


per-label

The effect of the global APPEND on the resulting command depends on whether the particular LABEL entry includes its own specific APPEND.

  # The following is a global directive:
  APPEND root=/dev/sda2
  
  # default non-label command; global append ignored:
  DEFAULT mykernel
  
  
  # Specific append present; global append ignored:
  LABEL some_label
  KERNEL mykernel
  APPEND some_additional_options
  
  # No specific append; global append used:
  LABEL mylabel
  KERNEL mykernel
  
  # Specific append present; global append ignored:
  LABEL mylabel_alone
  KERNEL mykernel
  APPEND -

In the above example, the global APPEND is ignored by the DEFAULT command and by label entries that already have an APPEND directive, and it is effectively parsed when executing a label entry that has no APPEND line of its own.

Similarly, when using the DEFAULT directive with a label (as opposed to using it with a non-label command), the behavior is the same as with the corresponding label entry.


initrd

As pointed out in the #per-label section, the effect of the global APPEND depends on whether an APPEND line is used on a particular LABEL entry.

Since 5.00, the presence of an INITRD directive in a particular LABEL entry has no influence on whether a global APPEND is effectively used when executing such LABEL.

  # The following is a global directive:
  APPEND vga=normal
  
  DEFAULT no_append_and_no_initrd
  
  
  # No specific append; global append used:
  LABEL no_append_and_no_initrd
  KERNEL mykernel
  
  # Specific append present; global append ignored:
  LABEL with_append_and_no_initrd
  KERNEL mykernel
  APPEND some_additional_options
  
  
  # Similar entries follow, but with an additional INITRD directive.
  
  # No specific append; global append used:
  LABEL no_append_and_with_initrd
  KERNEL mykernel
  INITRD myinitrd
  
  # Specific append present; global append ignored:
  LABEL with_append_and_with_initrd
  KERNEL mykernel
  INITRD myinitrd
  APPEND some_additional_options

Normally, the following directive:

  INITRD myinitrd  

would be considered equivalent to "APPEND initrd=myinitrd". But when using global APPEND, a separate INITRD directive has a different effect, as shown in the above examples.


command line

Since 5.00, the global APPEND affects (some) LABEL entries only. Specifically, the global APPEND affects those LABEL entries with no particular APPEND line, as shown in the #per-label section.

When entering a label from the boot: prompt (or from a Syslinux boot menu), the resulting command is executed according to the aforementioned rules.

But what about non-label commands? Since 5.00, when typing in non-label commands, the global APPEND is ignored, just as it happens with the DEFAULT directive.

For versions prior to 5.00, the global APPEND was silently imposed on each and every command typed in, and there was no method to avoid it, sometimes producing unexpected results. This type of behavior was a reason to avoid using the global APPEND directive at all. With the changed behavior since version 5.00, the global APPEND directive is now flexible enough so as to be actually usable.


per-label and global

From the above examples, combining a specific APPEND line in a LABEL entry together with a global APPEND would seem not possible. One potential workaround would be:

  # The following is a global directive:
  APPEND global_append
  
  DEFAULT mylabel
  
  # Specific append present; global append ignored:
  LABEL mylabel
  KERNEL mykernel
  APPEND myappend
  
  # No specific append; global append used:
  LABEL mylabel_2
  KERNEL mykernel myappend

The effective result for mylabel is:

  mykernel myappend  

The effective result for mylabel_2 is:

  mykernel myappend global_append  

Note that with this last syntax, the latest arguments in the resulting command come from the global APPEND.

Although some scripts -- which attempt to retrieve the KERNEL line and the APPEND line separately for further utilization of their contents -- could be impacted by this syntax, such scripts would also need additional adaptations if a global APPEND were to be used, whether using older or newer versions of Syslinux.


alternative

The cmd.c32 module combines a basic command together with some additional parameters; thus providing an alternative to the global APPEND.

The following is one of many possible combinations.

 # The following would be a global directive,
 # but it is commented out:
 # APPEND global_append
 
 DEFAULT mylabel
 
 # Specific append present; global append ignored:
 LABEL mylabel
 KERNEL mykernel
 APPEND myappend
 
 # Specific append present; global append ignored:
 # Same mykernel but with "global_append" options.
 # The original "myappend" options not included.
 LABEL mykernel_plus_global
 KERNEL mykernel
 APPEND global_append
 
 # Specific append present; global append ignored:
 LABEL mykernel_plus_global_plus_myappend
 KERNEL cmd.c32
 APPEND mykernel_plus_global myappend

In the above example, all LABEL entries have their own APPEND line. When using 5.00 or newer, in fact the initial global "APPEND global_append" line is not being used by any entry (that's why it is already commented out in the example).

When executing the mykernel_plus_global_plus_myappend label, the effective result is the "mykernel global_append myappend" command.

See Cmd.c32 for more examples.


See Also