Difference between revisions of "Directives/append"

From Syslinux Wiki
Jump to: navigation, search
m (Add Category. Add TOC. Wiki formatting.)
m (Minor misc. changes.)
 
Line 2: Line 2:
 
[[Category:Examples]]
 
[[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 20: Line 19:
 
Take the following simple configuration:
 
Take the following simple configuration:
  
<pre>
 
 
   DEFAULT mykernel
 
   DEFAULT mykernel
 
   APPEND root=/dev/sda2
 
   APPEND root=/dev/sda2
</pre>
 
  
 
Note that the APPEND line here is a ''global'' directive,  
 
Note that the APPEND line here is a ''global'' directive,  
Line 39: Line 36:
 
For the above example, the configuration could be re-written as:
 
For the above example, the configuration could be re-written as:
  
<pre>
 
 
   DEFAULT mykernel root=/dev/sda2
 
   DEFAULT mykernel root=/dev/sda2
</pre>
 
  
 
or even better as:
 
or even better as:
  
 
<pre>
 
<pre>
  DEFAULT mylabel
+
DEFAULT mylabel
  LABEL mylabel
+
LABEL mylabel
  KERNEL mykernel
+
KERNEL mykernel
  APPEND root=/dev/sda2
+
APPEND root=/dev/sda2
 
</pre>
 
</pre>
  
Line 64: Line 59:
 
|
 
|
 
<pre>
 
<pre>
  # The following is a global directive:
+
# The following is a global directive:
  APPEND root=/dev/sda2
+
APPEND root=/dev/sda2
 
+
  # default non-label command; global append ignored:
+
# default non-label command; global append ignored:
  DEFAULT mykernel
+
DEFAULT mykernel
 
+
 
+
  # Specific append present; global append ignored:
+
# Specific append present; global append ignored:
  LABEL some_label
+
LABEL some_label
  KERNEL mykernel
+
KERNEL mykernel
  APPEND some_additional_options
+
APPEND some_additional_options
 
+
  # No specific append; global append used:
+
# No specific append; global append used:
  LABEL mylabel
+
LABEL mylabel
  KERNEL mykernel
+
KERNEL mykernel
 
+
  # Specific append present; global append ignored:
+
# Specific append present; global append ignored:
  LABEL mylabel_alone
+
LABEL mylabel_alone
  KERNEL mykernel
+
KERNEL mykernel
  APPEND -
+
APPEND -
 
</pre>
 
</pre>
 
|}
 
|}
Line 109: Line 104:
 
|
 
|
 
<pre>
 
<pre>
  # The following is a global directive:
+
# The following is a global directive:
  APPEND vga=normal
+
APPEND vga=normal
 
+
  DEFAULT no_append_and_no_initrd
+
DEFAULT no_append_and_no_initrd
 
+
 
+
  # No specific append; global append used:
+
# No specific append; global append used:
  LABEL no_append_and_no_initrd
+
LABEL no_append_and_no_initrd
  KERNEL mykernel
+
KERNEL mykernel
 
+
  # Specific append present; global append ignored:
+
# Specific append present; global append ignored:
  LABEL with_append_and_no_initrd
+
LABEL with_append_and_no_initrd
  KERNEL mykernel
+
KERNEL mykernel
  APPEND some_additional_options
+
APPEND some_additional_options
 
+
 
+
  # Similar entries follow, but with an additional INITRD directive.
+
# Similar entries follow,  
 
+
# but with an additional INITRD directive.
  # No specific append; global append used:
+
  LABEL no_append_and_with_initrd
+
# No specific append; global append used:
  KERNEL mykernel
+
LABEL no_append_and_with_initrd
  INITRD myinitrd
+
KERNEL mykernel
 
+
INITRD myinitrd
  # Specific append present; global append ignored:
+
  LABEL with_append_and_with_initrd
+
# Specific append present; global append ignored:
  KERNEL mykernel
+
LABEL with_append_and_with_initrd
  INITRD myinitrd
+
KERNEL mykernel
  APPEND some_additional_options
+
INITRD myinitrd
 +
APPEND some_additional_options
 
</pre>
 
</pre>
 
|}
 
|}
  
 
Normally, the following directive:  
 
Normally, the following directive:  
<pre>  INITRD myinitrd </pre>
+
 
 +
  INITRD myinitrd
 +
 
 
would be considered equivalent to  
 
would be considered equivalent to  
 
{{nowrap|1="<code>APPEND initrd=myinitrd</code>".}}  
 
{{nowrap|1="<code>APPEND initrd=myinitrd</code>".}}  
Line 165: Line 163:
 
But what about non-label commands?  
 
But what about non-label commands?  
 
<strong>
 
<strong>
'''Since 5.00, when typing in {{nowrap|non-label}} commands''',  
+
'''Since 5.00, when {{nowrap|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.
Line 186: Line 184:
 
|
 
|
 
<pre>
 
<pre>
  # The following is a global directive:
+
# The following is a global directive:
  APPEND global_append
+
APPEND global_append
 
+
  DEFAULT mylabel
+
DEFAULT mylabel
 
+
  # Specific append present; global append ignored:
+
# Specific append present; global append ignored:
  LABEL mylabel
+
LABEL mylabel
  KERNEL mykernel
+
KERNEL mykernel
  APPEND myappend
+
APPEND myappend
 
+
  # No specific append; global append used:
+
# No specific append; global append used:
  LABEL mylabel_2
+
LABEL mylabel_2
  KERNEL mykernel myappend
+
KERNEL mykernel myappend
 
</pre>
 
</pre>
 
|}
 
|}
  
 
The effective result for ''mylabel'' is:
 
The effective result for ''mylabel'' is:
<pre>  mykernel myappend </pre>
+
 
 +
  mykernel myappend
 +
 
 
The effective result for ''mylabel_2'' is:
 
The effective result for ''mylabel_2'' is:
<pre>  mykernel myappend global_append </pre>
+
 
 +
  mykernel myappend global_append
  
 
Note that with this last syntax, the ''latest'' arguments in the  
 
Note that with this last syntax, the ''latest'' arguments in the  
Line 233: Line 234:
 
   # 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 <span style="color: maroon;">global_append</span>
+
   # APPEND <span style="color: maroon; ">global_append</span>
 
    
 
    
   DEFAULT <span style="color: green;">mylabel</span>
+
   DEFAULT <span style="color: green; ">mylabel</span>
 
    
 
    
 
   # Specific append present; global append ignored:
 
   # Specific append present; global append ignored:
   LABEL <span style="color: green;">mylabel</span>
+
   LABEL <span style="color: green; ">mylabel</span>
   KERNEL <span style="color: olive;">mykernel</span>
+
   KERNEL <span style="color: olive; ">mykernel</span>
   APPEND <span style="color: navy;">myappend</span>
+
   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 <span style="color: purple;">mykernel_plus_global</span>
+
   LABEL <span style="color: purple; ">mykernel_plus_global</span>
   KERNEL <span style="color: olive;">mykernel</span>
+
   KERNEL <span style="color: olive; ">mykernel</span>
   APPEND <span style="color: maroon;">global_append</span>
+
   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 <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>
 
|}  
 
|}  
 
<!-- -->
 
<!-- -->

Latest revision as of 05:39, 15 June 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