View source for Directives/append

[[Category:Directives]]
[[Category:Examples]]
For a basic explanation of the APPEND directive see [[Config#APPEND]].

<!-- Potential additional sections could be added, such as -->
<!-- notes on label-specific APPEND directives -->
<!-- (as oppose to global append) -->
== global append ==
<!-- Based on "global append changes since version 5" -->
<!-- http://www.syslinux.org/archives/2014-March/021930.html -->


=== default ===
<!-- Keywords: -->
<!-- global APPEND directive -->
<!-- so as to append boot options to the DEFAULT command. -->
<!-- APPEND options to the DEFAULT command -->

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 {{nowrap|1="<code>root=/dev/sda2</code>"}} 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:

<pre>
 DEFAULT mylabel
 LABEL mylabel
 KERNEL mykernel
 APPEND root=/dev/sda2
</pre>

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.
{|
|
<pre>
 # 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 -
</pre>
|}

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 {{nowrap|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.
{|
|
<pre>
 # 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
</pre>
|}

Normally, the following directive: 

  INITRD myinitrd

would be considered equivalent to 
{{nowrap|1="<code>APPEND initrd=myinitrd</code>".}} 
But when using ''global'' APPEND, a separate INITRD directive has a 
different effect, as shown in the above examples.


=== command line ===

<!-- Keywords: -->
<!-- CLI command line interface -->
<strong>
'''Since 5.00, the ''global'' APPEND affects (some) LABEL entries only'''. 
Specifically, the ''global'' APPEND affects those LABEL entries with no 
particular APPEND line,
</strong> 
as shown in the [[#per-label]] section.

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

But what about non-label commands? 
<strong>
'''Since 5.00, when {{nowrap|typing-in}} {{nowrap|non-label}} commands''', 
the ''global'' APPEND is ignored, just as it happens with 
the DEFAULT directive.
</strong>

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:
{|
|
<pre>
 # 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
</pre>
|}

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.
<!--  -->
<!-- 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,
  # but it is commented out:
  # APPEND <span style="color: maroon; ">global_append</span>
  
  DEFAULT <span style="color: green; ">mylabel</span>
  
  # Specific append present; global append ignored:
  LABEL <span style="color: green; ">mylabel</span>
  KERNEL <span style="color: olive; ">mykernel</span>
  APPEND <span style="color: navy; ">myappend</span>
  
  # Specific append present; global append ignored:
  # Same mykernel but with "global_append" options.
  # The original "myappend" options not included.
  LABEL <span style="color: purple; ">mykernel_plus_global</span>
  KERNEL <span style="color: olive; ">mykernel</span>
  APPEND <span style="color: maroon; ">global_append</span>
  
  # Specific append present; global append ignored:
  LABEL mykernel_plus_global_plus_myappend
  KERNEL '''cmd.c32'''
  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. 
When using 5.00 or newer, in fact the initial 
''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).

When executing the <tt>mykernel_plus_global_plus_myappend</tt> label, 
the effective result is the 
{{nowrap|"<code>mykernel global_append myappend</code>"}} command.

See [[Cmd.c32]] for more examples.


== See Also ==

* [[Config#APPEND|APPEND options...]]
* [[Doc/syslinux#CONFIGURATION_FILE]]
* [[Doc/syslinux#APPEND_options]]
* [[Cmd.c32]]
<!-- -->
<!-- <nowiki> * [[Comboot/menu.c32]] </nowiki> -->
<!-- Instead of "Comboot/menu.c32", -->
<!-- the [[Menu]] page is more up-to-date and easier to link-to, -->
<!-- including linking to its sections. -->
* [[Menu]]