CML2 Transition Guide

You need to read this guide if you are a maintainer of configuration code in the Linux kernel. Linus has scheduled this work to be incorporated in the tree during the 2.5.1/2.5.2 series. It will explain the plan for transitioning from the old system to the new one, what I'm planning to do, and what I need you to do.

I have made every effort to minimize the amount of work anybody but me has to do, but some is unavoidable. I don't think anybody will have more than maybe two hours' work to do, and it will save all of us a lot of future grief.

How to transition your code

Step 1: Get the background

Release 1.0.0 announcement

Goals of the project. Why it's worthwhile. What you will gain.

Recent news

Project release history.

The CML2 Language

Overview of CML2. Design philosophy, language semantics, implementation.

CML2 Reference

A complete description of CML2.

Step 2: Install the CML2 tools and rules files

You can untar the source distribution anywhere. Run the install-cml2 utility to install it in a Linux source directory on your system. The install-cml2 script will make sure your build environment is adequate, prompt you for a source tree location if there is more than one, and install the CML2 files there.

The installer has been carefully designed not to step on or interfere with the existing config system, except that it will modify the configuration productions in the top-level makefile. (The old ones will remain available under different names.)

Step 3: Take a look at the menu map

Change directory to your source tree. Do:

This will generate a map of the menu hierarchy defined by the rules file. Notice that it first compiles the rules file using cmlcompile. All the configuration productions will do this when necessary (which is only when configuration rules change).

For a more verbose result, including default values and requirements, add the -v debugging option to the command that make generates. (If this doesn't match what you remeber, it's OK; the debugging option was -d in pre-1.0.0 versions of CML2.) You can do it this way:

Step 4: Run the interpreter in interactive mode

Next, try `make ttyconfig' to see the line-oriented mode. The line-oriented mode is intended to be used as a configuration debugger; adding the -v option to the command (with `make CONFIGOPTS=-v ttyconfig') will tell you a lot about what the interpreter is doing.

You can try via `make menuconfig' to test the curses mode. This is the one I expect people will use the most.

Run via `make xconfig' to test the Tkinter mode.

Step 5: Take a harder look at the configuration parts you own

The rules files (.cml extension) will be distributed through your kernel tree near the code and drivers they configure. One or more of them is yours. Find them and try to grok what's going on with them.

Step 6: Now get serious and try to break it

Do a bunch of configurations. Try weird stuff -- stress-test the constraint machinery. Use the line-oriented `make ttyconfig' mode for this; it makes the debugging output easiest to read.

Remember that you can write out partial configurations with `s' and read them back in with the `i' command, so you don't have to re-do your boilerplate multiple times. Also remember the `g' command that lets you go straight to your piece after you've set up stuff like architecture and system buses (possibly with an `i').

Finally, be aware of the (undocumented) `e' command in the curses and tty modes, with which you can examine the state of any symbol at any time.

You can run the curses mode with 2>LOG to capture debug output from it.

Step 7: Tell me what you found

Step 8: Do your bit to keep CML2 in sync

Until CML1 is scrapped and the CML2 rules files owned by different maintainers, I'll need you to keep me up to date on the changes you're making to your CML1 files so I can keep the CML2 rulebase current.

State of the maintainers

certified

Maintainer has certified that configuration behavior is correct for his subystem.

testing

Maintainer is testing CML2's behavior.

confirmed

Maintainer has acknowledged responsibility for the subsystem, but not yet reported on CML2's behavior.

-

Maintainer not yet confirmed.

Here is the current state of the transition:

There are 48 identified configuration subsystems. 5 have been certified. Maintainers for 19 others have confirmed and 3 others are testing. The table below covers every nonempty configuration file in the CML1 corpus at the time of the most recent CML2 release.