Directives/append

From Syslinux Wiki
Jump to: navigation, search

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