|
|
|
Re: [PULL] Docs (trivial): README: Cleanup | |
| [Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] | |
[ adding linux-doc@, once I get their Ack, I'll apply it ]
On Tue, 3 Apr 2012, Michael Witten wrote:
> The following changes since commit f52b69f86e27903d6896ed5fa7cd280fec8de532:
>
> Merge tag 'sh-for-linus' of git://github.com/pmundt/linux-sh (2012-03-30 00:09:17 -0700)
>
> are available in the git repository at:
>
> git://github.com/mfwitten/linux.git trivial/docs/README
>
> for you to fetch changes up to 86e1d222688102d99ceb20ffcf857868c983020e:
>
> Docs (trivial): README: Remove sporadic tabs (2012-04-03 19:20:25 +0000)
>
> It will be significantly easier to review the patches separately, but a
> the overall changes have been inlined as a giant patch in this email
> in case that too is useful.
>
> Sincerely,
> Michael Witten
>
> ----------------------------------------------------------------
> Michael Witten (8):
>
> Docs (trivial): README: Use `X' and `x' consistently
> Docs (trivial): README: Grammar: `me has' -> `I have'
> Docs (trivial): README: Better comma usage
> Docs (trivial): README: `Alternately' -> `Alternatively'
> Docs (trivial): README: More consistent and readable white space
> Docs (trivial): README: Capitalize start of sentence
> Docs (trivial): README: Consolidate discussions of -stable patches
> Docs (trivial): README: Remove sporadic tabs
>
> README | 222 ++++++++++++++++++++++++++++++++++------------------------------
> 1 file changed, 118 insertions(+), 104 deletions(-)
>
> diff --git a/README b/README
> index 0d5a7dd..9beaed0 100644
> --- a/README
> +++ b/README
> @@ -1,4 +1,4 @@
> - Linux kernel release 3.x <http://kernel.org/>
> + Linux kernel release 3.x <http://kernel.org/>
>
> These are the release notes for Linux version 3. Read them carefully,
> as they tell you what this is all about, explain how to install the
> @@ -62,13 +62,13 @@ INSTALLING the kernel source:
> directory where you have permissions (eg. your home directory) and
> unpack it:
>
> - gzip -cd linux-3.X.tar.gz | tar xvf -
> + gzip -cd linux-3.X.tar.gz | tar xvf -
>
> or
> - bzip2 -dc linux-3.X.tar.bz2 | tar xvf -
>
> + bzip2 -dc linux-3.X.tar.bz2 | tar xvf -
>
> - Replace "XX" with the version number of the latest kernel.
> + Replace "X" with the version number of the latest kernel.
>
> Do NOT use the /usr/src/linux area! This area has a (usually
> incomplete) set of kernel headers that are used by the library header
> @@ -78,49 +78,43 @@ INSTALLING the kernel source:
> - You can also upgrade between 3.x releases by patching. Patches are
> distributed in the traditional gzip and the newer bzip2 format. To
> install by patching, get all the newer patch files, enter the
> - top level directory of the kernel source (linux-3.x) and execute:
> + top level directory of the kernel source (linux-3.X) and execute:
>
> - gzip -cd ../patch-3.x.gz | patch -p1
> + gzip -cd ../patch-3.x.gz | patch -p1
>
> or
> - bzip2 -dc ../patch-3.x.bz2 | patch -p1
>
> - (repeat xx for all versions bigger than the version of your current
> - source tree, _in_order_) and you should be ok. You may want to remove
> - the backup files (xxx~ or xxx.orig), and make sure that there are no
> - failed patches (xxx# or xxx.rej). If there are, either you or me has
> - made a mistake.
> + bzip2 -dc ../patch-3.x.bz2 | patch -p1
> +
> + Replace "x" for all versions bigger than the version "X" of your current
> + source tree, _in_order_, and you should be ok. You may want to remove
> + the backup files (some-file-name~ or some-file-name.orig), and make sure
> + that there are no failed patches (some-file-name# or some-file-name.rej).
> + If there are, either you or I have made a mistake.
>
> Unlike patches for the 3.x kernels, patches for the 3.x.y kernels
> (also known as the -stable kernels) are not incremental but instead apply
> - directly to the base 3.x kernel. Please read
> - Documentation/applying-patches.txt for more information.
> + directly to the base 3.x kernel. For example, if your base kernel is 3.0
> + and you want to apply the 3.0.3 patch, you must not first apply the 3.0.1
> + and 3.0.2 patches. Similarly, if you are running kernel version 3.0.2 and
> + want to jump to 3.0.3, you must first reverse the 3.0.2 patch (that is,
> + patch -R) _before_ applying the 3.0.3 patch. You can read more on this in
> + Documentation/applying-patches.txt
>
> Alternatively, the script patch-kernel can be used to automate this
> process. It determines the current kernel version and applies any
> patches found.
>
> - linux/scripts/patch-kernel linux
> + linux/scripts/patch-kernel linux
>
> The first argument in the command above is the location of the
> kernel source. Patches are applied from the current directory, but
> an alternative directory can be specified as the second argument.
>
> - - If you are upgrading between releases using the stable series patches
> - (for example, patch-3.x.y), note that these "dot-releases" are
> - not incremental and must be applied to the 3.x base tree. For
> - example, if your base kernel is 3.0 and you want to apply the
> - 3.0.3 patch, you do not and indeed must not first apply the
> - 3.0.1 and 3.0.2 patches. Similarly, if you are running kernel
> - version 3.0.2 and want to jump to 3.0.3, you must first
> - reverse the 3.0.2 patch (that is, patch -R) _before_ applying
> - the 3.0.3 patch.
> - You can read more on this in Documentation/applying-patches.txt
> -
> - Make sure you have no stale .o files and dependencies lying around:
>
> - cd linux
> - make mrproper
> + cd linux
> + make mrproper
>
> You should now have the sources correctly installed.
>
> @@ -137,21 +131,23 @@ SOFTWARE REQUIREMENTS
>
> BUILD directory for the kernel:
>
> - When compiling the kernel all output files will per default be
> + When compiling the kernel, all output files will per default be
> stored together with the kernel source code.
> Using the option "make O=output/dir" allow you to specify an alternate
> place for the output files (including .config).
> Example:
> - kernel source code: /usr/src/linux-3.N
> - build directory: /home/name/build/kernel
>
> - To configure and build the kernel use:
> - cd /usr/src/linux-3.N
> - make O=/home/name/build/kernel menuconfig
> - make O=/home/name/build/kernel
> - sudo make O=/home/name/build/kernel modules_install install
> + kernel source code: /usr/src/linux-3.X
> + build directory: /home/name/build/kernel
> +
> + To configure and build the kernel, use:
>
> - Please note: If the 'O=output/dir' option is used then it must be
> + cd /usr/src/linux-3.X
> + make O=/home/name/build/kernel menuconfig
> + make O=/home/name/build/kernel
> + sudo make O=/home/name/build/kernel modules_install install
> +
> + Please note: If the 'O=output/dir' option is used, then it must be
> used for all invocations of make.
>
> CONFIGURING the kernel:
> @@ -163,61 +159,78 @@ CONFIGURING the kernel:
> new version with minimal work, use "make oldconfig", which will
> only ask you for the answers to new questions.
>
> - - Alternate configuration commands are:
> - "make config" Plain text interface.
> - "make menuconfig" Text based color menus, radiolists & dialogs.
> - "make nconfig" Enhanced text based color menus.
> - "make xconfig" X windows (Qt) based configuration tool.
> - "make gconfig" X windows (Gtk) based configuration tool.
> - "make oldconfig" Default all questions based on the contents of
> - your existing ./.config file and asking about
> - new config symbols.
> - "make silentoldconfig"
> - Like above, but avoids cluttering the screen
> - with questions already answered.
> - Additionally updates the dependencies.
> - "make defconfig" Create a ./.config file by using the default
> - symbol values from either arch/$ARCH/defconfig
> - or arch/$ARCH/configs/${PLATFORM}_defconfig,
> - depending on the architecture.
> - "make ${PLATFORM}_defconfig"
> - Create a ./.config file by using the default
> - symbol values from
> - arch/$ARCH/configs/${PLATFORM}_defconfig.
> - Use "make help" to get a list of all available
> - platforms of your architecture.
> - "make allyesconfig"
> - Create a ./.config file by setting symbol
> - values to 'y' as much as possible.
> - "make allmodconfig"
> - Create a ./.config file by setting symbol
> - values to 'm' as much as possible.
> - "make allnoconfig" Create a ./.config file by setting symbol
> - values to 'n' as much as possible.
> - "make randconfig" Create a ./.config file by setting symbol
> - values to random values.
> + - Alternative configuration commands are:
> +
> + "make config" Plain text interface.
> +
> + "make menuconfig" Text based color menus, radiolists & dialogs.
> +
> + "make nconfig" Enhanced text based color menus.
> +
> + "make xconfig" X windows (Qt) based configuration tool.
> +
> + "make gconfig" X windows (Gtk) based configuration tool.
> +
> + "make oldconfig" Default all questions based on the contents of
> + your existing ./.config file and asking about
> + new config symbols.
> +
> + "make silentoldconfig"
> + Like above, but avoids cluttering the screen
> + with questions already answered.
> + Additionally updates the dependencies.
> +
> + "make defconfig" Create a ./.config file by using the default
> + symbol values from either arch/$ARCH/defconfig
> + or arch/$ARCH/configs/${PLATFORM}_defconfig,
> + depending on the architecture.
> +
> + "make ${PLATFORM}_defconfig"
> + Create a ./.config file by using the default
> + symbol values from
> + arch/$ARCH/configs/${PLATFORM}_defconfig.
> + Use "make help" to get a list of all available
> + platforms of your architecture.
> +
> + "make allyesconfig"
> + Create a ./.config file by setting symbol
> + values to 'y' as much as possible.
> +
> + "make allmodconfig"
> + Create a ./.config file by setting symbol
> + values to 'm' as much as possible.
> +
> + "make allnoconfig" Create a ./.config file by setting symbol
> + values to 'n' as much as possible.
> +
> + "make randconfig" Create a ./.config file by setting symbol
> + values to random values.
>
> You can find more information on using the Linux kernel config tools
> in Documentation/kbuild/kconfig.txt.
>
> - NOTES on "make config":
> - - having unnecessary drivers will make the kernel bigger, and can
> - under some circumstances lead to problems: probing for a
> - nonexistent controller card may confuse your other controllers
> - - compiling the kernel with "Processor type" set higher than 386
> - will result in a kernel that does NOT work on a 386. The
> - kernel will detect this on bootup, and give up.
> - - A kernel with math-emulation compiled in will still use the
> - coprocessor if one is present: the math emulation will just
> - never get used in that case. The kernel will be slightly larger,
> - but will work on different machines regardless of whether they
> - have a math coprocessor or not.
> - - the "kernel hacking" configuration details usually result in a
> - bigger or slower kernel (or both), and can even make the kernel
> - less stable by configuring some routines to actively try to
> - break bad code to find kernel problems (kmalloc()). Thus you
> - should probably answer 'n' to the questions for
> - "development", "experimental", or "debugging" features.
> + - NOTES on "make config":
> +
> + - Having unnecessary drivers will make the kernel bigger, and can
> + under some circumstances lead to problems: probing for a
> + nonexistent controller card may confuse your other controllers
> +
> + - Compiling the kernel with "Processor type" set higher than 386
> + will result in a kernel that does NOT work on a 386. The
> + kernel will detect this on bootup, and give up.
> +
> + - A kernel with math-emulation compiled in will still use the
> + coprocessor if one is present: the math emulation will just
> + never get used in that case. The kernel will be slightly larger,
> + but will work on different machines regardless of whether they
> + have a math coprocessor or not.
> +
> + - The "kernel hacking" configuration details usually result in a
> + bigger or slower kernel (or both), and can even make the kernel
> + less stable by configuring some routines to actively try to
> + break bad code to find kernel problems (kmalloc()). Thus you
> + should probably answer 'n' to the questions for "development",
> + "experimental", or "debugging" features.
>
> COMPILING the kernel:
>
> @@ -230,7 +243,7 @@ COMPILING the kernel:
> possible to do "make install" if you have lilo installed to suit the
> kernel makefiles, but you may want to check your particular lilo setup first.
>
> - To do the actual install you have to be root, but none of the normal
> + To do the actual install, you have to be root, but none of the normal
> build should require that. Don't take the name of root in vain.
>
> - If you configured any of the parts of the kernel as `modules', you
> @@ -238,13 +251,13 @@ COMPILING the kernel:
>
> - Verbose kernel compile/build output:
>
> - Normally the kernel build system runs in a fairly quiet mode (but not
> + Normally, the kernel build system runs in a fairly quiet mode (but not
> totally silent). However, sometimes you or other kernel developers need
> to see compile, link, or other commands exactly as they are executed.
> For this, use "verbose" build mode. This is done by inserting
> "V=1" in the "make" command. E.g.:
>
> - make V=1 all
> + make V=1 all
>
> To have the build system also tell the reason for the rebuild of each
> target, use "V=2". The default is "V=0".
> @@ -256,6 +269,7 @@ COMPILING the kernel:
> are installing a new kernel with the same version number as your
> working kernel, make a backup of your modules directory before you
> do a "make modules_install".
> +
> Alternatively, before compiling, use the kernel config option
> "LOCALVERSION" to append a unique suffix to the regular kernel version.
> LOCALVERSION can be set in the "General Setup" menu.
> @@ -267,7 +281,7 @@ COMPILING the kernel:
> - Booting a kernel directly from a floppy without the assistance of a
> bootloader such as LILO, is no longer supported.
>
> - If you boot Linux from the hard drive, chances are you use LILO which
> + If you boot Linux from the hard drive, chances are you use LILO, which
> uses the kernel image as specified in the file /etc/lilo.conf. The
> kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or
> /boot/bzImage. To use the new kernel, save a copy of the old image
> @@ -306,21 +320,21 @@ IF SOMETHING GOES WRONG:
>
> - If the bug results in a message like
>
> - unable to handle kernel paging request at address C0000010
> - Oops: 0002
> - EIP: 0010:XXXXXXXX
> - eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx
> - esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx
> - ds: xxxx es: xxxx fs: xxxx gs: xxxx
> - Pid: xx, process nr: xx
> - xx xx xx xx xx xx xx xx xx xx
> + unable to handle kernel paging request at address C0000010
> + Oops: 0002
> + EIP: 0010:XXXXXXXX
> + eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx
> + esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx
> + ds: xxxx es: xxxx fs: xxxx gs: xxxx
> + Pid: xx, process nr: xx
> + xx xx xx xx xx xx xx xx xx xx
>
> or similar kernel debugging information on your screen or in your
> system log, please duplicate it *exactly*. The dump may look
> incomprehensible to you, but it does contain information that may
> help debugging the problem. The text above the dump is also
> important: it tells something about why the kernel dumped code (in
> - the above example it's due to a bad kernel pointer). More information
> + the above example, it's due to a bad kernel pointer). More information
> on making sense of the dump is in Documentation/oops-tracing.txt
>
> - If you compiled the kernel with CONFIG_KALLSYMS you can send the dump
> @@ -328,7 +342,7 @@ IF SOMETHING GOES WRONG:
> sense of the dump (but compiling with CONFIG_KALLSYMS is usually preferred).
> This utility can be downloaded from
> ftp://ftp.<country>.kernel.org/pub/linux/utils/kernel/ksymoops/ .
> - Alternately you can do the dump lookup by hand:
> + Alternatively, you can do the dump lookup by hand:
>
> - In debugging dumps like the above, it helps enormously if you can
> look up what the EIP value means. The hex value as such doesn't help
> @@ -342,7 +356,7 @@ IF SOMETHING GOES WRONG:
> the file 'linux/vmlinux'. To extract the namelist and match it against
> the EIP from the kernel crash, do:
>
> - nm vmlinux | sort | less
> + nm vmlinux | sort | less
>
> This will give you a list of kernel addresses sorted in ascending
> order, from which it is simple to find the function that contains the
> @@ -361,7 +375,7 @@ IF SOMETHING GOES WRONG:
> kernel image or similar), telling me as much about your setup as
> possible will help. Please read the REPORTING-BUGS document for details.
>
> - - Alternately, you can use gdb on a running kernel. (read-only; i.e. you
> + - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you
> cannot change values or set break points.) To do this, first compile the
> kernel with -g; edit arch/i386/Makefile appropriately, then do a "make
> clean". You'll also need to enable CONFIG_PROC_FS (via "make config").
>
--
Jiri Kosina
SUSE Labs
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
[Site Home] [Kernel Newbies] [Share Photos] [Security] [Netfilter] [Bugtraq] [Linux FS] [Photo] [Yosemite] [Yosemite News] [MIPS Linux] [ARM Linux] [Linux Security] [Linux RAID] [Samba] [Video 4 Linux] [Device Mapper] [Linux Resources]
|