diff options
author | peter <peter@FreeBSD.org> | 2005-11-07 17:37:27 +0000 |
---|---|---|
committer | peter <peter@FreeBSD.org> | 2005-11-07 17:37:27 +0000 |
commit | 89671b139b8fb4bf5863bb89483c824bbba7c5ee (patch) | |
tree | 30be9723292845d94ade4aa02bf0c73dd8e5bd2c /usr.sbin | |
parent | 72f875157d57c8a301cd37d2b204cba4cb7a3b5e (diff) | |
download | FreeBSD-src-89671b139b8fb4bf5863bb89483c824bbba7c5ee.zip FreeBSD-src-89671b139b8fb4bf5863bb89483c824bbba7c5ee.tar.gz |
Add some rationale about when to bump and not bump the config version.
Clarify that it is not like the shlib versions, and not like param.h's
__FreeBSD_version/osreldate either.
When config(8) was actively changing a while back, the interface between
config and the build system (eg: /sys/conf/files.* and Makefile.*) was
changing rapidly. configvers is a version number of that interface.
User specified config files do not have a version number. The decision
about whether a user supplied config file is syntactically valid or not
belongs to the parser and sanity checks, not an arbitary number.
Diffstat (limited to 'usr.sbin')
-rw-r--r-- | usr.sbin/config/configvers.h | 40 |
1 files changed, 37 insertions, 3 deletions
diff --git a/usr.sbin/config/configvers.h b/usr.sbin/config/configvers.h index b4906e3..0871bf2 100644 --- a/usr.sbin/config/configvers.h +++ b/usr.sbin/config/configvers.h @@ -1,11 +1,45 @@ /* * 6 digits of version. The most significant are branch indicators * (eg: RELENG_2_2 = 22, -current presently = 60 etc). The least - * significant digits are incremented for each incompatible change. + * significant digits are incremented as needed. * - * The numbering scheme is inspired by the sys/conf/newvers.sh RELDATE - * and <osreldate.h> system. + * DO NOT CASUALLY BUMP THIS NUMBER! The rules are not the same as shared + * libs or param.h/osreldate. + * + * It is the version number of the protocol between config(8) and the + * sys/conf/* Makefiles (the kernel build system). + * + * It is now also used to trap certain problems that the syntax parser cannot + * detect. + * + * Unfortunately, there is no version number for user supplied config files. + * + * Once, config(8) used to silently report errors and continue anyway. This + * was a huge problem for 'make buildkernel' which was run with the installed + * /usr/sbin/config, not a cross built one. We started bumping the version + * number as a way to trap cases where the previous installworld was not + * compatable with the new buildkernel. The buildtools phase and much more + * comprehensive error code returns solved this original problem. + * + * Most end-users will use buildkenel and the build tools from buildworld. + * The people that are inconvenienced by gratuitous bumps are developers + * who run config by hand. * * $FreeBSD$ */ #define CONFIGVERS 600003 + +/* + * Examples of when there should NOT be a bump: + * - Adding a new keyword + * - Changing the syntax of a keyword such that old syntax will break config. + * - Changing the syntax of a keyword such that new syntax will break old + * config binaries. + * + * Examples of when there should be a bump: + * - When files generated in sys/$mach/compile/NAME are changed and the + * Makefile.$mach rules might not handle it correctly. + * - When there are incompatable changes to the way sys/conf/files.* or the + * other associated files are parsed such that they will be interpreted + * incorrectly rather than fail outright. + */ |