Difference between revisions of "Directives/append"

From Syslinux Wiki
Jump to: navigation, search
m (Edit internal link.)
m (Wiki formatting.)
Line 1: Line 1:
 
[[Category:Directives]]
 
[[Category:Directives]]
For a basic explanation of the APPEND directive see  
+
For a basic explanation of the APPEND directive see [[Config#APPEND]].
[[Config#APPEND]].
+
__TOC__
+
  
 
<!-- Potential additional sections could be added, such as -->
 
<!-- Potential additional sections could be added, such as -->
Line 15: Line 13:
 
<!-- Keywords: -->
 
<!-- Keywords: -->
 
<!-- global APPEND directive -->
 
<!-- global APPEND directive -->
<!-- so to append boot options to the DEFAULT command. -->
+
<!-- so as to append boot options to the DEFAULT command. -->
 
<!-- APPEND options to the DEFAULT command -->
 
<!-- APPEND options to the DEFAULT command -->
  
Line 25: Line 23:
 
</pre>
 
</pre>
  
Note that the APPEND line here is a ''global'' directive, as it is  
+
Note that the APPEND line here is a ''global'' directive,  
not part of any LABEL entry.
+
as it is not part of any LABEL entry.
  
For Syslinux 4.xx and older, the above simple configuration works as  
+
For Syslinux 4.xx and older,  
(it used to be) expected.
+
the above simple configuration works as (it used to be) expected.
  
 
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 ''root=/dev/sda2'' argument is not parsed, which will lead to  
+
that the {{nowrap|1="<tt>root=/dev/sda2</tt>"}} argument is not parsed,  
unexpected results, most probably with some kind of failure to boot  
+
which will lead to unexpected results,  
the OS. In other words, the ''global'' APPEND is ignored by the DEFAULT  
+
most probably with some kind of failure to boot the OS.  
directive.
+
In other words, the ''global'' APPEND is ignored by the DEFAULT directive.
  
 
For the above example, the configuration could be re-written as:
 
For the above example, the configuration could be re-written as:
Line 93: Line 91:
  
 
Similarly, when using the DEFAULT directive with a label (as  
 
Similarly, when using the DEFAULT directive with a label (as  
opposed to using it with a non-label command), the behavior is the  
+
opposed to using it with a {{nowrap|non-label}} command),  
same as with the corresponding label entry.
+
the behavior is the same as with the corresponding label entry.
  
  
Line 140: Line 138:
 
</pre>
 
</pre>
  
Normally, the following directive
+
 
 +
Normally, the following directive:
 
<pre>  INITRD myinitrd  </pre>
 
<pre>  INITRD myinitrd  </pre>
would be considered equivalent to <tt>APPEND initrd=myinitrd</tt>. But
+
would be considered equivalent to  
when using ''global'' APPEND, a separate INITRD directive has a  
+
{{nowrap|1="<tt>APPEND initrd=myinitrd</tt>".}}
 +
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 152: Line 152:
 
<!-- CLI command line interface -->
 
<!-- CLI command line interface -->
 
<strong>
 
<strong>
'''Since 5.00, the ''global'' APPEND affects (some) LABEL entries only.  
+
'''Since 5.00, the ''global'' APPEND affects (some) LABEL entries only'''.  
 
Specifically, the ''global'' APPEND affects those LABEL entries with no  
 
Specifically, the ''global'' APPEND affects those LABEL entries with no  
particular APPEND line,'''
+
particular APPEND line,
 
</strong>  
 
</strong>  
 
as shown in the [[#per-label]] section.
 
as shown in the [[#per-label]] section.
  
When entering a label from the ''boot:'' prompt (or from a Syslinux
+
When entering a label from the {{nowrap|''boot:''}} prompt (or from a  
boot menu), the resulting command is executed according to the  
+
Syslinux boot menu),  
aforementioned rules.
+
the resulting command is executed according to the aforementioned rules.
  
 
But what about non-label commands?  
 
But what about non-label commands?  
 
<strong>
 
<strong>
'''Since 5.00, when typing in non-label commands,  
+
'''Since 5.00, when typing in {{nowrap|non-label}} commands''',  
 
the ''global'' APPEND is ignored, just as it happens with  
 
the ''global'' APPEND is ignored, just as it happens with  
the DEFAULT directive.'''
+
the DEFAULT directive.
 
</strong>
 
</strong>
  
Line 172: Line 172:
 
on each and every command typed in, and there was no method to avoid  
 
on each and every command typed in, and there was no method to avoid  
 
it, sometimes producing unexpected results. This type of behavior was  
 
it, sometimes producing unexpected results. This type of behavior was  
one reason to avoid using the ''global'' APPEND directive at all. With  
+
a reason to avoid using the ''global'' APPEND directive at all. With  
 
the changed behavior since version 5.00, the ''global'' APPEND  
 
the changed behavior since version 5.00, the ''global'' APPEND  
directive is now flexible enough so to be actually usable.
+
directive is now flexible enough so as to be actually usable.
  
  
Line 216: Line 216:
 
=== alternative ===
 
=== alternative ===
  
The [[Cmd.c32]] module combines a basic command together with some  
+
The [[cmd.c32]] module combines a basic command together with some  
 
additional parameters; thus providing an alternative to the  
 
additional parameters; thus providing an alternative to the  
''global'' APPEND. See [[Cmd.c32]] for more details.
+
''global'' APPEND.
  
 
The following is one of many possible combinations.
 
The following is one of many possible combinations.
<pre>
+
 
 +
<!-- Do NOT use "pre" tags in the following few lines, -->
 +
<!-- as "pre" does not parse wiki markup. -->
 +
<!-- 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:
   # APPEND global_append
+
   # APPEND <span style="color: maroon;">global_append</span>
 
    
 
    
   DEFAULT mylabel
+
   DEFAULT <span style="color: green;">mylabel</span>
 
    
 
    
 
   # Specific append present; global append ignored:
 
   # Specific append present; global append ignored:
   LABEL mylabel
+
   LABEL <span style="color: green;">mylabel</span>
   KERNEL mykernel
+
   KERNEL <span style="color: olive;">mykernel</span>
   APPEND myappend
+
   APPEND <span style="color: navy;">myappend</span>
 
    
 
    
 
   # Specific append present; global append ignored:
 
   # Specific append present; global append ignored:
 
   # Same mykernel but with "global_append" options.
 
   # Same mykernel but with "global_append" options.
 
   # The original "myappend" options not included.
 
   # The original "myappend" options not included.
   LABEL mykernel_plus_global
+
   LABEL <span style="color: purple;">mykernel_plus_global</span>
   KERNEL mykernel
+
   KERNEL <span style="color: olive;">mykernel</span>
   APPEND global_append
+
   APPEND <span style="color: maroon;">global_append</span>
 
    
 
    
 
   # Specific append present; global append ignored:
 
   # Specific append present; global append ignored:
 
   LABEL mykernel_plus_global_plus_myappend
 
   LABEL mykernel_plus_global_plus_myappend
   KERNEL cmd.c32
+
   KERNEL '''cmd.c32'''
   APPEND mykernel_plus_global myappend
+
   APPEND <span style="color: purple;">mykernel_plus_global</span> <span style="color: navy;">myappend</span>
 
    
 
    
</pre>
+
<!-- -->
  
 
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'' <tt>APPEND global_append</tt> line is not being used by any  
+
''global'' {{nowrap|"<tt>APPEND global_append</tt>"}} line is not being  
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 <tt>mykernel global_append myappend</tt>  
+
the effective result is the  
command.
+
{{nowrap|"<tt>mykernel global_append myappend</tt>"}} command.
  
 
See [[Cmd.c32]] for more examples.
 
See [[Cmd.c32]] for more examples.
Line 266: Line 270:
 
* [[Doc/syslinux#APPEND_options]]
 
* [[Doc/syslinux#APPEND_options]]
 
* [[Cmd.c32]]
 
* [[Cmd.c32]]
 +
<!-- -->
 
<!-- <nowiki> * [[Comboot/menu.c32]] </nowiki> -->
 
<!-- <nowiki> * [[Comboot/menu.c32]] </nowiki> -->
 
<!-- Intead of "Comboot/menu.c32", -->
 
<!-- Intead of "Comboot/menu.c32", -->

Revision as of 19:59, 24 February 2017

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