[syslinux] global append changes since version 5

[Ady]

In Syslinux 5-6.02, the "global append" directive is being 
(unintentionally) ignored in some cases.

Updating Syslinux from prior versions, when using a "global append" 
directive, will cause unexpected results.

For example, take the following simple configuration file:

 *** 
 DEFAULT mykernel
 APPEND root=/dev/sda2
 *** 

Note that the 'append' line is a global directive here, 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.

The result for the above sample configuration in versions 5-6.02 is 
that the 'root=/dev/sda2' parameter is not parsed, which will lead to 
unexpected results, most probably with some kind of failure to boot 
the OS.

For users seeing strange behaviors after updating Syslinux to 
version(s) 5-6.02, a potential workaround could be achieved by 
re-writing the configuration file without using a "global append" 
directive.

Other than repeating the "global append" parameters for each 
individual 'label' entry, in some cases the cmd.c32 module might help 
too.

For the prior 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. 
This is, of course, a simplified case just to show the problem.

There is one case in which the "global append" is *not* ignored in 
versions 5-6.02:

 *** 
 # The following is a global directive
 APPEND root=/dev/sda2
 DEFAULT mykernel

 # The following entry includes an append line
 LABEL some_label
 KERNEL mykernel
 APPEND some_additional_options

 # The following entry does not include an append line
 LABEL mylabel
 KERNEL mykernel
 *** 

In the above example, the "global append" is ignored by the 'default' 
command and by 'label' entries that already have an 'append' 
directive, but it is correctly 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 respective label entry.

Additionally, the special "append -" case seems to be working as 
expected.


In other words, in Syslinux 5-6.02 a specified 'append' line 
*overrides* the _whole_ "global append", and a 'default non-label' 
directive ignores it. A command that has been typed in CLI also 
ignores the "global append".

These behaviors break the one seen in prior versions, which is not 
necessarily such a bad thing in the case of "global append".

In my opinion, there is at least one advantage of ignoring the 
"global append": when typing in CLI some command, it is executed 
"as-is", without automatically inserting the "global append" line in 
every single case.


Now, breaking prior behaviors is usually seen as a bad thing. One 
reason I am writing this is for users updating from prior versions 
and using a "global append" directive. They might probably see 
different behaviors, and simple modifications to the configuration 
file will solve the issue. Documenting this change should reduce 
surprises.

Despite breaking the behavior of the "global append" directive in 
comparison with prior versions (which sounds as a bad thing), after 
performing some tests I have to say I am in favor of this change, as 
it brings more flexibility and less unexpected results. With 
documentation in mind, I'll try to make the case for this change.

1_ In older versions, the "global append" was "always imposed" when 
typing in a command in CLI. In CLI, there was no way to override or 
avoid the "global append" arguments. In addition, if the user was not 
aware that a "global append" was part of the configuration file, 
typing a command in CLI would result in an unexpected behavior from 
the point of view of the user.

In Syslinux 5+, the CLI allows the possibility to execute commands 
exactly as typed in, whether there is a "global append" directive or 
not.


2_ In prior versions, a specific entry was executed as follows:
 <mykernel> <global_append> <myappend_options>
corresponding to:

 *** 
 # The following is the global append, not part of a label entry.
 APPEND <global_append>

 #The following is a sample entry
 LABEL <mylabel>
 KERNEL <mykernel>
 APPEND <myappend_options>
 *** 

In Syslinux 5+, the same entry will ignore the "global append", 
resulting in:
 <mykernel>  <myappend_options>

The old command:
 <mykernel> <global_append> <myappend_options>
can still be achieved by using the cmd.c32 module (see Syslinux 
wiki).


3_ The following entry:
 *** 
 # The following is the global append, not part of a label entry.
 APPEND <global_append>

 #The following is a sample entry
 LABEL <mylabel>
 KERNEL <mykernel> <myappend_options>
 *** 

used to result in prior versions as:
 <mykernel> <myappend_options> <global_append>

In Syslinux 5+ this behavior has not changed.


4_ We have one particular sub-case here; when <myappend_options> do 
not exist.
 *** 
 # The following is the global append, not part of a label entry.
 APPEND <global_append>

 #The following is a sample entry
 LABEL <mylabel>
 KERNEL <mykernel>
 *** 

resulting in:
 <mykernel> <global_append>
in both older and in newer versions.


5_ When combined with labels, the 'default' directive follows the 
above examples:

 *** 
 DEFAULT <mylabel>
 # The following is the global append, not part of a label entry.
 APPEND <global_append>
 *** 
Syslinux 5+ will execute the command depending on the specific 
<mylabel> entry, as shown in the above examples.


6_ The 'default' directive, when combined with non-label commands:
 *** 
 DEFAULT <non-label_command>
 # The following is the global append, not part of a label entry.
 APPEND <global_append>
 *** 

used to execute:
 <non-label_command> <global_append>
in prior versions of Syslinux.

In Syslinux 5+, this syntax ignores the "global append". See the next 
example for a workaround.


7_ The 'default' directive, when combined with non-label commands:
 *** 
 DEFAULT <non-label_command> <same_arguments_as_global_append>
 *** 

used to execute:
 <non-label_command> <same_arguments_as_global_append>
in prior versions of Syslinux.

In Syslinux 5+ this behavior has not changed.


8_ In addition to breaking the prior behavior (which might be seen as 
a negative point by some users), part of the new behavior might 
require in some cases for kernel options to be included in the KERNEL 
directive instead of using the APPEND directive. Although there are 
some scripts (which retrieve the KERNEL line and the APPEND line 
separately for further utilization of their contents) that could be 
impacted by such syntax, I would tend to think that such scripts 
would also need additional adaptations if a "global append" were to 
be used, whether using older or newer versions of Syslinux.

Without the usage of the "global append" directive, there is no need 
for kernel options to be included in the KERNEL directive line. So, 
either such scripts would require additional adaptations, or no 
changes at all. I could be wrong though.


In conclusion

 _ Each time a user experiences a different behavior when updating 
Syslinux, the whole configuration file should be provided for 
troubleshooting, without ever assuming that the configuration is OK 
just because it was working as expected before the update.

 _ The usage of the 'default <mylabel>' syntax is usually favored 
over the 'default <non-label>' commands.

 _ Yes, the current behavior in Syslinux 5-6.02 breaks the behavior 
in comparison to prior versions regarding "global append". This is 
not necessarily a negative point.

 _ The new behavior, when combined with some alternatives, is more 
flexible and provides better control.

 _ The "global append" directive is still useful in some cases, but 
other 
alternatives are usually favored.

 _ The changed behavior for the "global append" directive should be 
officially 
documented.

 _ Independently of its changes, the "global append" directive should 
be better 
documented. Hopefully this email is helpful.

Regards,
Ady.