Difference between pages "Building a Kernel from Source" and "Help:Funtoo Editing Guidelines"

From Funtoo
(Difference between pages)
Jump to navigation Jump to search
 
 
Line 1: Line 1:
Setting up a proper kernel yourself - lean, mean and tailored to your hardware,  is the challenge by which a linux user can graduate to becoming a Funtoo knight ;-)
'''Thanks for your potential interest in contribution the the Funtoo wiki!'''
__NOTOC__
== Types of Edits ==


Even though many of us are using enterprise-ready kernels in datacenters, there is almost nobody who hasn't at least considered building a kernel for his laptop / PC.
Before we get started, let's review what changes are okay to make, and what changes are not okay:
We are showing here how an intermediate Linux user can use an alternative to the standard beginners "genkernel" approach,  to compile a custom kernel, in a relatively speedy and easy set up.


== Minimum Requirements ==
{{TableStart}}
* '''Understand the command line'''
<tr class="active"><th>Type of Change</th><th>Okay?</th></tr>
* '''Know where the kernel files are located'''
<tr><td>Grammar/spelling fixes</td><td>Yes</td></tr>
<tr><td>New wiki content</td><td>Yes</td></tr>
<tr><td>New package information</td><td>Yes</td></tr>
<tr><td>Adding to existing article</td><td>Maybe -- see below</td></tr>
<tr><td>Adding missing/incomplete information</td><td>Yes</td></tr>
<tr><td>Making corrections</td><td>Yes</td></tr>
<tr class="danger"><td>Adding work-arounds to problems experienced</td><td>No - open bug first on [http://bugs.funtoo.org bug tracker].</td></tr>
{{TableEnd}}


== Assumptions ==
{{fancyimportant|Note that if you experience some problem with Funtoo Linux, during installation or otherwise, the proper course of action is to not add a work-around to our documentation, but to ''open a bug on our bug tracker.'' This is important because the problem you experienced may be a legitimate bug and the solution may be to fix the bug rather than add a work-around to our documentation. We may end up fixing a bug, making a documentation fix, or possibly both.}}
You start from an installed Funtoo system on the disk, or at least, you are on stage3 in a chrooted environment from a live cd, following somehow the Funto [[Installation (Tutorial)|Installation Tutorial]].


== Less advanced version ==
== Basics ==
=== Emerging the kernel sources ===
To begin, we have to figure out which kernel sources we will use. If you are unsure about which sources are available and what their benefits and drawbacks are, check out the [[Funtoo_Linux_Kernels| Kernels]] page.


After you have made a decsion as to which kernel you want to install, emerge it:
Here is a list of basic wiki information that you will need to know to get started:
<console>
 
###i## emerge vanilla-sources
* First, to perform edits on the wiki, you must {{CreateAccount}} and log in.
</console>
* You can create a new page by navigating to http://www.funtoo.org/New_Page_Name. Underscores are the equivalent of spaces. Then select "Create" under the "Actions" menu.
Portage will now go about installing the sources to ''/usr/src''. It will also symlink the kernel-version directory to a directory called ''linux''.
* Whether creating a new page or editing an existing page by clicking "Edit", you will be presented with Web-based text editor that allows you to modify the ''wikitext'' of the page. The wikitext is rendered to produce the document you see when you view the page normally.
* This wiki uses the [http://www.mediawiki.org/wiki/Extension:Approved_Revs ApprovedRevs Extension], which means that any changes you make to a page will need to be approved by an Editor before they are displayed. Editors can visit the [[Special:ApprovedRevs]] page to approve edits made on pages (click "Pages whose approved revision is not their latest" or "Unapproved pages".)
* Until your edits are approved, you can continue to edit the page and your changes will be displayed in the page's History -- click "History" under the "Actions" menu to view the page's history. You will see that the approved version of a page has a star next to it.
* Another fun thing you can do is click on your name under the "Account" menu once you have logged in. This will bring you to your "User" page. Then click "Create with Form" unde the "Actions" menu and enter your geographic and other information. This will allow you to be displayed on our [[Usermap]] and will also allow your full name to be displayed on [[:Category:Ebuilds|Ebuild pages]] for which you are an author. It's generally a good idea to do this.
 
{{fancytip|The following sections document how to use wikitext and Funtoo templates on the Funtoo wiki.}}
 
== Paragraphs ==
 
To create a new paragraph, insert a blank line between two lines of text. If a blank line doesn't exist between two lines of wikitext, they will be combined into a single flowing paragraph.
 
If you leave leading whitespace at the beginning of a line, MediaWiki will render it as pre-formatted text. Beware of this. Here's an example:
 
foobar
 
This can rear its ugly head when specifying template parameters, so you will get this:
 
{{fancynote| ugh!}}
 
...instead of this:
 
{{fancynote|This looks much better!}}
 
== Page and Section Capitalization ==
 
In general, capitalize all words in page names and section heading except:
* Articles: a, an, the
* Coordinating Conjunctions: and, but, or, for, nor, etc.
* Prepositions (fewer than five letters): on, at, to, from, by, etc.
 
== Document Heirarchy ==
 
Use section headings to create a document heirarchy for your page. These will define the table of contents that appears at the top of the wiki page. Create chapters, sections and sub-sections as follows:
 
<pre>= Page Title =
 
== Chapter Title ==
 
=== Section Title ===
 
==== SubSection Title ====
 
</pre>
 
== Links ==


=== Configuring the kernel ===
Internal links to other wiki pages can be specified as <tt><nowiki>[[pagename]]</nowiki></tt>. To specify an alternate name for the link, use <tt><nowiki>[[pagename|my link name]]</nowiki></tt>.
Now that the kernel sources are on your system, you should configure them. To do this, change your directory to ''/usr/src/linux''
<console>
###i## cd /usr/src/linux
</console>
As we are now in the kernel sources directory, we can run a script that allows us to modify them. Run:
<console>
###i## make menuconfig
</console>


While you edit the sources, keep the following in mind:
For external links, use <tt><nowiki>[http://funtoo.org my link]</nowiki></tt> to specify a URL. If you want the URL to appear in the wikitext, you can specify it without brackets: http://forums.funtoo.org.
* To build something into your kernel, press y when you have it selected.
* To exclude something from your kernel, press n when you have it selected.
* To build something as a module, press m.  


== Lists ==


Things that you may need to include in your kernel:
MediaWiki supports a number of list formats:


as '''modules''':
* Unordered List
* Unordered Item 2
** Unordered sub-item


* Wireless/LAN drivers
# Ordered List
* Support for your graphics card
# Ordered Item 2
* Support for your audio card
## Ordered sub-item
* Support for USB devices


;Term: This is called a "definition list". It is used when defining various terms.


as '''built in''':
If you need to quote a portion of text from another site, use <tt><nowiki><blockquote></nowiki></tt> as follows:
* scsi sata & or ata controllers
* file system used


{{fancynote|1=
<blockquote>
Many pages on the wiki will tell you the kernel requirements for the application that they are about. Keep your eyes open for the blue background, white text sections of pages. Like on this one: [[uvesafb| uvesafb]]}}
Wikipedia (ˌwɪkɨˈpiːdiə/ or wɪkiˈpiːdiə/ wik-i-pee-dee-ə) is a collaboratively edited, multilingual, free-access, free content Internet encyclopedia that is supported and hosted by the non-profit Wikimedia Foundation. Volunteers worldwide collaboratively write Wikipedia's 30 million articles in 287 languages, including over 4.5 million in the English Wikipedia. Anyone who can access the site can edit almost any of its articles, which on the Internet comprise[4] the largest and most popular general reference work.[5][6][7][8][9] In February 2014, The New York Times reported that Wikipedia is ranked fifth globally among all websites stating, "With 18 billion page views and nearly 500 million unique visitors a month..., Wikipedia trails just Yahoo, Facebook, Microsoft and Google, the largest with 1.2 billion unique visitors."[10]
</blockquote>


=== Building and installing the kernel sources ===
== Literal Text and HTML Symbols ==
After you finish configuring your kernel sources, you will need to build them. To build your sources, run the following:
<console>
###i## make
</console>
{{fancytip|1=
You can add -j<number of processing cores + 1> after make to build the kernel more quickly.}}


When the kernel and its modules finish building, install them:
Here is wikitext for the section above, which I am displaying by placing the literal wikitext between a &#60;pre&#62; and &#60;/pre&#62; tag. If you want to disable wikitext processing for an inline span of text, use &#60;nowiki&#62; and &#60;/nowiki&#62;. If you want to print out a tag literally, use &amp;#60; and &amp;#62; (In the wikitext, I used &amp;amp;#60; and &amp;amp;#62 to display these!)
<console>
###i## make modules_install && make install
</console>
Now that you have installed your kernel and modules, it is a good idea to install an [[Building_a_Kernel_from_Source#Initramfs| Initramfs]].
* If your system has a separate ''/usr'' partition, is encrypted, or uses some other non-standard configuration, it will probably not boot without an initramfs.
* If your system is unencrypted, with file system, and hard drive controllers compiled in rather than as modules, it will not need an initramfs.


== Advanced version ==
<pre>
=== Getting ready to start ===
* Unordered List
* Unordered Item 2
** Unordered sub-item


{{fancynote|In this case we are building a kernel that is booting root in LVM over encrypted LUKS container.
# Ordered List
If you don't have this setup, don't worry, you just don't need all the modules, but everything else is similar.}}
# Ordered Item 2
First, there is the decision which linux kernel sources we need.
## Ordered sub-item
There are plenty of them in the repositories around, often it is not easy to distinguish between them.


I would always trust my distribution of choice and take what is has to offer - and funtoo has a lot to offer!
;Term: This is called a "definition list". It is used when defining various terms.


I really do recommend (especially if it is your first time) to build a debian-sourced genkernel like described in chapter 5 "Using Debian-Sources with Genkernel" in the [[Funtoo_Linux_Kernels| Funtoo Kernels Tutorial]].
If you need to quote a portion of text from another site, use <tt><nowiki><blockquote></nowiki></tt> as follows:


From there you should have a running system booting nicely from your own build (just little bit bloated) kernel. This is more than you can expect from any other ready to go distribution.
<blockquote>
Wikipedia (ˌwɪkɨˈpiːdiə/ or wɪkiˈpiːdiə/ wik-i-pee-dee-ə) is a collaboratively edited, multilingual, free-access,
free content Internet encyclopedia that is supported and hosted by the non-profit Wikimedia Foundation. Volunteers
worldwide collaboratively write Wikipedia's 30 million articles in 287 languages, including over 4.5 million in the
English Wikipedia. Anyone who can access the site can edit almost any of its articles, which on the Internet
comprise[4] the largest and most popular general reference work.[5][6][7][8][9] In February 2014, The New York
Times reported that Wikipedia is ranked fifth globally among all websites stating, "With 18 billion page views
and nearly 500 million unique visitors a month..., Wikipedia trails just Yahoo, Facebook, Microsoft and Google,
the largest with 1.2 billion unique visitors."[10]
</blockquote>
</pre>


{{fancynote|1=
== Displaying Source Code ==
We are using Red Hat's dracut in order to build a nice initramfs (containing all the necessary tools and extra drivers our kernel might need to start the system). Although dracut is the way to go, more sophisticated and not as buggy as gentoo's genkernel approach, more and more funtoo geeks start using slashbeast's better-initramfs, which we will cover at the end of this howto! So after having set up a genkernel from debian or gentoo sources we are going to build a kernel with either (or both) dracut or/and better-initramfs. So gentoo sources with genkernel is always my backup if anything is not working correctly on my system. For the slightly more geeky approach with my own initram I am using pf-sources, ck-sources or any other more or less heavily patched sources.}}


Let's go!
To display source code, use the <tt>&#60;syntaxhighlight&#62;</tt> tag, which has the ability to perform syntax highlighting on the source code for easier reading:
<pre>
<syntaxhighlight lang="python">
import system
</syntaxhighlight>
</pre>


=== Kernel Sources ===
This will produce the following output:
The source you use on your system is up to you. For a laptop or desktop system, the following are recommended:
* '''{{Package|sys-kernel/pf-sources}}'''
* '''{{Package|sys-kernel/ck-sources}}'''
* '''{{Package|sys-kernel/gentoo-sources}}'''
* '''{{Package|sys-kernel/git-sources}}'''
* '''{{Package|sys-kernel/sysrescue-std-sources}}'''
* '''{{Package|sys-kernel/debian-sources}}'''
{{fancynote|If you are unsure of which sources you would like to use, emerge <code>gentoo-sources</code>. That's always a safe bet for a general system. For more information on available kernels, check out: [[Funtoo Linux Kernels]]}}


=== Prerequisites ===
<syntaxhighlight lang="python">
import system
</syntaxhighlight>


Regardless of the tools you already have installed, it is recommended to follow the steps below, even if you find them to be redundant.
Alternatively, if you need a caption, use can use the file template, specifying a <tt>lang=</tt> parameter:
First, we edit our <code>/etc/portage/make.conf</code>:


<pre>
<pre>
#These compiler flags are just tweaking (optimazation) and NOT necessary:
{{file|name=foobar|lang=python|desc=foobarosity|body=
CFLAGS="-O2 -pipe -march=native -ftracer -fforce-addr"
import system
CXXFLAGS="${CFLAGS} -fpermissive -fomit-frame-pointer"
}}
KDIR=/usr/src/linux
KERNEL="symlink build"
USE="$KERNEL ....here are your use flags...."
## These modules are available:
## DRACUT_MODULES="dracut_modules_biosdevname dracut_modules_btrfs dracut_modules_caps dracut_modules_crypt dracut_modules_crypt-gpg dracut_modules_dmraid dracut_modules_dmsquash-live dracut_modules_gensplash dracut_modules_iscsi dracut_modules_livenet dracut_modules_lvm dracut_modules_mdraid dracut_modules_multipath dracut_modules_nbd dracut_modules_nfs dracut_modules_plymouth dracut_modules_ssh-client dracut_modules_syslog"
## We will use these modules for LVM / LUKS:
DRACUT_MODULES="crypt lvm plymouth biosdevname dmraid crypt-gpg dmsquash-live ssh-client syslog"
</pre>
</pre>


Next, we set the package keywords by adding the following to <code>/etc/portage/package.use</code>:
This will produce:
 
{{file|name=foobar|lang=python|desc=foobarosity|body=
import system
}}
 
{{fancyimportant|If you need to display the pipe ("{{!}}") character within the body of a file template, replace each "{{!}}" with <nowiki>{{!}}</nowiki> -- otherwise your file contents will not display properly. This is necessary because <nowiki>{{file}}</nowiki> is a template and the "{{!}}" character is used as a delimiter for arguments to the template.}}
 
Note that the language should be specified in the <tt>lang</tt> attribute. For a list of supported languages, see [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages this list].
 
== Displaying Text File Contents ==
 
For displaying the contents of non-programming language text files (like config files), you have two options. You can enclose your lines within <tt>&#60;pre&#62;</tt> tags, or use the new [[Template:File|file template]]. The file template is used like so:


<pre>
<pre>
sys-kernel/dracut dm net device-mapper crypt lvm
{{file|name=/etc/foo.conf|desc=My foo.conf file|body=
# /etc/host.conf:
# $Header: /var/cvsroot/gentoo/src/patchsets/glibc/extra/etc/host.conf,v 1.1 2006/09/29
}}
</pre>
</pre>


{{fancynote|If you don't have lvm over encrypted LUKS you just add the "net" keyword here, or "selinux".}}
This will produce:


{{file|name=/etc/foo.conf|desc=My foo.conf file|body=
# /etc/host.conf:
# $Header: /var/cvsroot/gentoo/src/patchsets/glibc/extra/etc/host.conf,v 1.1 2006/09/29
}}


Next, we build our packages:
== Console ==
To display console output, use the <tt>&#60;console&#62;</tt> tag:
 
For a root console:
<pre>
<console>
<console>
###i## emerge -av app-portage/gentoolkit sys-kernel/pf-sources sys-kernel/dracut sys-boot/plymouth sys-boot/plymouth-openrc-plugin
###i## run a command as root
</console>
</pre>
Produces:
<console>
###i## run a command as root
</console>
</console>


=== Preparing the kernel ===
For a non-root console:
 
<pre>
We go now to the sources directory and enter the following commands to update the kernel's  .config  file:
<console>
$ ##i##run a command as user
</console>
</pre>
Produces:
<console>
<console>
###i## cd /usr/src/linux/
$ ##i##run a command as user
###i## make clean
  CLEAN  .
  CLEAN  arch/x86/kernel/acpi/realmode
  CLEAN  arch/x86/kernel/cpu
  CLEAN  arch/x86/kernel
  CLEAN  arch/x86/vdso
  CLEAN  arch/x86/lib
  CLEAN  drivers/gpu/drm/radeon
  CLEAN  drivers/net/wan
  CLEAN  drivers/scsi/aic7xxx
  CLEAN  drivers/tty/vt
  CLEAN  drivers/video/logo
  CLEAN  firmware
  CLEAN  kernel
  CLEAN  lib/raid6
  CLEAN  lib
  CLEAN  security/apparmor
  CLEAN  security/selinux
  CLEAN  usr
  CLEAN  arch/x86/boot/compressed
  CLEAN  arch/x86/boot
  CLEAN  .tmp_versions
  CLEAN  vmlinux System.map .tmp_kallsyms2.S .tmp_kallsyms1.o .tmp_kallsyms2.o .tmp_kallsyms1.S .tmp_vmlinux1 .tmp_vmlinux2 .tmp_System.map
###i## zcat /proc/config.gz > /usr/src/linux/.config
</console>
</console>


Next, we run <tt>make localmodconfig</tt>. You will get some questions which you can answer mostly with either M (compiled as a module) or Y (compiled directly into the kernel). If you are not sure what to choose, press enter, and the default option will be selected.
{{fancyimportant|1=
<console>
Note that we use a <tt>#</tt> prompt for <tt>root</tt> and a <tt>$</tt> prompt to denote a non-root user.}}
###i## make localmodconfig
 
Enable different security models (SECURITY) [Y/n/?] y
{{Fancyimportant|The <tt>##i##</tt> text tags the rest of the line as being ''user input'' ("i" is for "input"). It is then highlighted in a noticeable color so it stands out from text that is not typed in by the user.}}
Enable the securityfs filesystem (SECURITYFS) [Y/?] y
 
Socket and Networking Security Hooks (SECURITY_NETWORK) [Y/?] y
If you need to end highlighting of user input prior to the end of a line, use <code>##!i##</code> to mark the end of the highlighted area.
Security hooks for pathname based access control (SECURITY_PATH) [Y/?] y
 
Low address space for LSM to protect from user allocation (LSM_MMAP_MIN_ADDR) [65536] 65536
The following special character sequences are also available:
NSA SELinux Support (SECURITY_SELINUX) [Y/n/?] y
* <code>##g##</code> - Green
  NSA SELinux boot parameter (SECURITY_SELINUX_BOOTPARAM) [N/y/?] n
* <code>##y##</code> - Yellow
  NSA SELinux runtime disable (SECURITY_SELINUX_DISABLE) [N/y/?] n
* <code>##bl##</code> - Blue
  NSA SELinux Development Support (SECURITY_SELINUX_DEVELOP) [Y/n/?] y
* <code>##r##</code> - Red
  NSA SELinux AVC Statistics (SECURITY_SELINUX_AVC_STATS) [Y/n/?] y
* <code>##b##</code> - Bold
  NSA SELinux checkreqprot default value (SECURITY_SELINUX_CHECKREQPROT_VALUE) [1] 1
 
  NSA SELinux maximum supported policy format version (SECURITY_SELINUX_POLICYDB_VERSION_MAX) [Y/n/?] y
Please use the above coloring options sparingly. It is sometimes nice to use them to get wiki console output to match the colors that are displayed on a Linux console. Also note that for every color above, there is a matching <code>##!(colorcode)##</code> option to turn color off prior to end of line.
    NSA SELinux maximum supported policy format version value (SECURITY_SELINUX_POLICYDB_VERSION_MAX_VALUE) [19] 19
 
TOMOYO Linux Support (SECURITY_TOMOYO) [Y/n/?] y
Here is an example of its use:<console>
  Default maximal count for learning mode (SECURITY_TOMOYO_MAX_ACCEPT_ENTRY) [2048] 2048
# ##i##bluetoothctl
  Default maximal count for audit log (SECURITY_TOMOYO_MAX_AUDIT_LOG) [1024] 1024
[##g##NEW##!g##] Controller 00:02:72:C9:62:65 antec [default]
  Activate without calling userspace policy loader. (SECURITY_TOMOYO_OMIT_USERSPACE_LOADER) [Y/n/?] y
##bl##[bluetooth]##!bl###power on
AppArmor support (SECURITY_APPARMOR) [Y/n/?] y
Changing power on succeeded
  AppArmor boot parameter default value (SECURITY_APPARMOR_BOOTPARAM_VALUE) [1] 1
##bl##[bluetooth]##!bl### ##i##agent on
Integrity Measurement Architecture(IMA) (IMA) [Y/n/?] y
Agent registered
EVM support (EVM) [N/y/?] (NEW)
##bl##[bluetooth]##!bl### ##i##scan on
Default security module
Discovery started
  1. SELinux (DEFAULT_SECURITY_SELINUX)
##bl##[bluetooth]##!bl### ##i##devices
  2. TOMOYO (DEFAULT_SECURITY_TOMOYO)
Device 00:1F:20:3D:1E:75 Logitech K760
  3. AppArmor (DEFAULT_SECURITY_APPARMOR)
##bl##[bluetooth]##!bl### ##i##pair 00:1F:20:3D:1E:75
> 4. Unix Discretionary Access Controls (DEFAULT_SECURITY_DAC)
Attempting to pair with 00:1F:20:3D:1E:75
choice[1-4?]: 4
[##y##CHG##!y##] Device 00:1F:20:3D:1E:75 Connected: yes
warning: (ACPI_HOTPLUG_CPU) selects ACPI_CONTAINER which has unmet direct dependencies (ACPI && EXPERIMENTAL)
##r##[agent]##!r## Passkey: 454358
warning: (MEDIA_TUNER) selects MEDIA_TUNER_TEA5761 which has unmet direct dependencies (MEDIA_SUPPORT && VIDEO_MEDIA && I2C && EXPERIMENTAL)
##r##[agent]##!r## Passkey: ##i##4##!i##54358
##r##[agent]##!r## Passkey: ##i##45##!i##4358
##r##[agent]##!r## Passkey: ##i##454##!i##358
##r##[agent]##!r## Passkey: ##i##4543##!i##58
##r##[agent]##!r## Passkey: ##i##45435##!i##8
##r##[agent]##!r## Passkey: ##i##454358##!i##
[##y##CHG##!y##] Device 00:1F:20:3D:1E:75 Paired: yes
Pairing successful
[##y##CHG##!y##] Device 00:1F:20:3D:1E:75 Connected: no
##bl##[bluetooth]##!bl### ##i##connect 00:1F:20:3D:1E:75
Attempting to connect to 00:1F:20:3D:1E:75
[##y##CHG##!y##] Device 00:1F:20:3D:1E:75 Connected: yes
Connection successful
##bl##[bluetooth]##!bl### ##i##quit
[##r##DEL##!r##] Controller 00:02:72:C9:62:65 antec [default]
#
#
# configuration written to .config
#
warning: (GFS2_FS) selects DLM which has unmet direct dependencies (EXPERIMENTAL && INET && SYSFS && CONFIGFS_FS && (IPV6 || IPV6=n))
warning: (IMA) selects TCG_TPM which has unmet direct dependencies (HAS_IOMEM && EXPERIMENTAL)
warning: (MEDIA_TUNER) selects MEDIA_TUNER_TEA5761 which has unmet direct dependencies (MEDIA_SUPPORT && VIDEO_MEDIA && I2C && EXPERIMENTAL)
warning: (ACPI_HOTPLUG_CPU) selects ACPI_CONTAINER which has unmet direct dependencies (ACPI && EXPERIMENTAL)
</console>
</console>


Now comes the most adventurous part!
== Fancy Notes ==
notes, warnings, tips, and important templates will help bring emphasis to articles drawn up.
<pre>{{fancynote|this is a fancy note}}</pre><br />
{{fancynote|this is a fancy note}}<br />
 
<pre>{{fancyimportant|this is a fancy important}}</pre><br />
{{fancyimportant|this is a fancy important}}<br />
 
<pre>{{fancywarning|this is a fancy warning}}</pre><br />
{{fancywarning|this is a fancy warning}}<br />
 
<pre>{{fancytip|this is a fancy tip}}</pre><br />
{{fancytip|this is a fancy tip}}<br />
 
== Kernelop ==
To display kernel configuration options, we encourage you to use the <tt>kernelop</tt> template. To use the <tt>kernelop</tt> template, create an entry similar to the following example:
<pre>
{{kernelop|title=foo,bar|desc=
kernel options pasted from "make menuconfig"
}}
</pre>
 
{{fancynote|Kernelop is colored blue to slightly resemble the blueish background from <tt>make menuconfig</tt>.}}
 
Adding this entry will give you the following output:
{{kernelop|title=foo,bar|desc=
kernel options
}}
 
Here's a more concrete example:
{{kernelop|title=File systems|desc=
<M> Second extended fs support         
[ ]  Ext2 extended attributes         
[ ]  Ext2 execute in place support   
<M> Ext3 journalling file system support
}}
 
Examples of usage:
* [[Package:AMD Catalyst Video Drivers]]
* [[Package:ACPI Daemon]]
* [[Microcode]]
 


=== Building the Kernel ===
== Marking Pages as Needing Updates ==
<console>
 
###i## make -j8  bzImage
If you find outdated wiki content, but you don't have the time or ability to update it, add one of the following templates to the wikitext of the page. This will add the page to the [[:Category:Needs Updates|Needs Updates Category]] so we can identify pages that need updating:
###i## make -j8 modules
 
###i## make modules_install
<pre>
###i## make install
{{PageNeedsUpdates}}
</console>
{{SectionNeedsUpdates}}
</pre>
 
 
Examples of usage:
* [[UEFI Install Guide]]
* [[Package:MediaWiki]]
* [[Clang]]
 
== Inline Code ==
 
To emphasize filenames, commands, and other technical jargon when they appear inline in a paragraph, use the <tt>&#60;code&#62;</tt> element. Follow the example below:
 
<pre>
The <code>/etc/fstab</code> file is an important one. Another important file is <code>/boot/grub/grub.cfg</code>.
</pre>
 
This example produces the following output:
 
The <code>/etc/fstab</code> file is an important one. Another important file is <code>/boot/grub/grub.cfg</code>.


== Initramfs ==
{{fancyimportant|1=
{{fancywarning|Make sure that you have built and installed your kernel sources / modules before building an initramfs.}}
The &#60;tt&#62; tag has been deprecated for the purpose of tagging inline code, to conform with HTML5.}}
To get your initramfs up and running, check out the [http://www.funtoo.org/Initramfs Initramfs] page. After following all the directions on the page to get your initramfs set up, continue following the ones here.


Update the <tt>grub.cfg</tt> with boot update, then reboot and see how it works!
== Screencasting ==
<console>
screencasting is an easy method to explain complex tasks.  take for instance youtu.be/5KDei5mBfSg we chop off the id and insert it into the following syntax to produce a video example.<br />
###i## boot-update -v
tiny:
###i## reboot
<pre>{{#widget:YouTube|id=5KDei5mBfSg|width=320|height=180}}</pre>
</console>
standard:
<pre>{{#widget:YouTube|id=5KDei5mBfSg|width=700|height=420}}</pre>
{{#widget:YouTube|id=5KDei5mBfSg|width=700|height=420}}


[[Category:HOWTO]]
[[Category:Wiki Development]]
[[Category:Featured]]
[[Category:Kernel]]

Revision as of 19:27, September 23, 2014

Thanks for your potential interest in contribution the the Funtoo wiki!

Types of Edits

Before we get started, let's review what changes are okay to make, and what changes are not okay:

Type of ChangeOkay?
Grammar/spelling fixesYes
New wiki contentYes
New package informationYes
Adding to existing articleMaybe -- see below
Adding missing/incomplete informationYes
Making correctionsYes
Adding work-arounds to problems experiencedNo - open bug first on bug tracker.
   Important

Note that if you experience some problem with Funtoo Linux, during installation or otherwise, the proper course of action is to not add a work-around to our documentation, but to open a bug on our bug tracker. This is important because the problem you experienced may be a legitimate bug and the solution may be to fix the bug rather than add a work-around to our documentation. We may end up fixing a bug, making a documentation fix, or possibly both.

Basics

Here is a list of basic wiki information that you will need to know to get started:

  • First, to perform edits on the wiki, you must Create a Funtoo account and log in.
  • You can create a new page by navigating to http://www.funtoo.org/New_Page_Name. Underscores are the equivalent of spaces. Then select "Create" under the "Actions" menu.
  • Whether creating a new page or editing an existing page by clicking "Edit", you will be presented with Web-based text editor that allows you to modify the wikitext of the page. The wikitext is rendered to produce the document you see when you view the page normally.
  • This wiki uses the ApprovedRevs Extension, which means that any changes you make to a page will need to be approved by an Editor before they are displayed. Editors can visit the Special:ApprovedRevs page to approve edits made on pages (click "Pages whose approved revision is not their latest" or "Unapproved pages".)
  • Until your edits are approved, you can continue to edit the page and your changes will be displayed in the page's History -- click "History" under the "Actions" menu to view the page's history. You will see that the approved version of a page has a star next to it.
  • Another fun thing you can do is click on your name under the "Account" menu once you have logged in. This will bring you to your "User" page. Then click "Create with Form" unde the "Actions" menu and enter your geographic and other information. This will allow you to be displayed on our Usermap and will also allow your full name to be displayed on Ebuild pages for which you are an author. It's generally a good idea to do this.
   Tip

The following sections document how to use wikitext and Funtoo templates on the Funtoo wiki.

Paragraphs

To create a new paragraph, insert a blank line between two lines of text. If a blank line doesn't exist between two lines of wikitext, they will be combined into a single flowing paragraph.

If you leave leading whitespace at the beginning of a line, MediaWiki will render it as pre-formatted text. Beware of this. Here's an example:

foobar

This can rear its ugly head when specifying template parameters, so you will get this:

   Note
ugh!

...instead of this:

   Note

This looks much better!

Page and Section Capitalization

In general, capitalize all words in page names and section heading except:

  • Articles: a, an, the
  • Coordinating Conjunctions: and, but, or, for, nor, etc.
  • Prepositions (fewer than five letters): on, at, to, from, by, etc.

Document Heirarchy

Use section headings to create a document heirarchy for your page. These will define the table of contents that appears at the top of the wiki page. Create chapters, sections and sub-sections as follows:

= Page Title =

== Chapter Title ==

=== Section Title ===

==== SubSection Title ====

Links

Internal links to other wiki pages can be specified as [[pagename]]. To specify an alternate name for the link, use [[pagename|my link name]].

For external links, use [http://funtoo.org my link] to specify a URL. If you want the URL to appear in the wikitext, you can specify it without brackets: http://forums.funtoo.org.

Lists

MediaWiki supports a number of list formats:

  • Unordered List
  • Unordered Item 2
    • Unordered sub-item
  1. Ordered List
  2. Ordered Item 2
    1. Ordered sub-item
Term
This is called a "definition list". It is used when defining various terms.

If you need to quote a portion of text from another site, use <blockquote> as follows:

Wikipedia (ˌwɪkɨˈpiːdiə/ or wɪkiˈpiːdiə/ wik-i-pee-dee-ə) is a collaboratively edited, multilingual, free-access, free content Internet encyclopedia that is supported and hosted by the non-profit Wikimedia Foundation. Volunteers worldwide collaboratively write Wikipedia's 30 million articles in 287 languages, including over 4.5 million in the English Wikipedia. Anyone who can access the site can edit almost any of its articles, which on the Internet comprise[4] the largest and most popular general reference work.[5][6][7][8][9] In February 2014, The New York Times reported that Wikipedia is ranked fifth globally among all websites stating, "With 18 billion page views and nearly 500 million unique visitors a month..., Wikipedia trails just Yahoo, Facebook, Microsoft and Google, the largest with 1.2 billion unique visitors."[10]

Literal Text and HTML Symbols

Here is wikitext for the section above, which I am displaying by placing the literal wikitext between a <pre> and </pre> tag. If you want to disable wikitext processing for an inline span of text, use <nowiki> and </nowiki>. If you want to print out a tag literally, use &#60; and &#62; (In the wikitext, I used &amp;#60; and &amp;#62 to display these!)

* Unordered List
* Unordered Item 2
** Unordered sub-item

# Ordered List
# Ordered Item 2
## Ordered sub-item

;Term: This is called a "definition list". It is used when defining various terms.

If you need to quote a portion of text from another site, use <tt><blockquote></tt> as follows:

<blockquote>
Wikipedia (ˌwɪkɨˈpiːdiə/ or wɪkiˈpiːdiə/ wik-i-pee-dee-ə) is a collaboratively edited, multilingual, free-access, 
free content Internet encyclopedia that is supported and hosted by the non-profit Wikimedia Foundation. Volunteers
worldwide collaboratively write Wikipedia's 30 million articles in 287 languages, including over 4.5 million in the 
English Wikipedia. Anyone who can access the site can edit almost any of its articles, which on the Internet 
comprise[4] the largest and most popular general reference work.[5][6][7][8][9] In February 2014, The New York 
Times reported that Wikipedia is ranked fifth globally among all websites stating, "With 18 billion page views 
and nearly 500 million unique visitors a month..., Wikipedia trails just Yahoo, Facebook, Microsoft and Google, 
the largest with 1.2 billion unique visitors."[10]
</blockquote>

Displaying Source Code

To display source code, use the <syntaxhighlight> tag, which has the ability to perform syntax highlighting on the source code for easier reading:

<syntaxhighlight lang="python">
import system
</syntaxhighlight>

This will produce the following output:

import system

Alternatively, if you need a caption, use can use the file template, specifying a lang= parameter:

{{file|name=foobar|lang=python|desc=foobarosity|body=
import system
}}

This will produce:

   foobar (python source code) - foobarosity
import system
   Important

If you need to display the pipe ("|") character within the body of a file template, replace each "|" with {{!}} -- otherwise your file contents will not display properly. This is necessary because {{file}} is a template and the "|" character is used as a delimiter for arguments to the template.

Note that the language should be specified in the lang attribute. For a list of supported languages, see this list.

Displaying Text File Contents

For displaying the contents of non-programming language text files (like config files), you have two options. You can enclose your lines within <pre> tags, or use the new file template. The file template is used like so:

{{file|name=/etc/foo.conf|desc=My foo.conf file|body=
# /etc/host.conf:
# $Header: /var/cvsroot/gentoo/src/patchsets/glibc/extra/etc/host.conf,v 1.1 2006/09/29
}}

This will produce:

   /etc/foo.conf - My foo.conf file
# /etc/host.conf:
# $Header: /var/cvsroot/gentoo/src/patchsets/glibc/extra/etc/host.conf,v 1.1 2006/09/29

Console

To display console output, use the <console> tag:

For a root console:

<console>
###i## run a command as root
</console>

Produces:

root # run a command as root

For a non-root console:

<console>
$ ##i##run a command as user
</console>

Produces:

user $ run a command as user
   Important

Note that we use a # prompt for root and a $ prompt to denote a non-root user.

   Important

The ##i## text tags the rest of the line as being user input ("i" is for "input"). It is then highlighted in a noticeable color so it stands out from text that is not typed in by the user.

If you need to end highlighting of user input prior to the end of a line, use ##!i## to mark the end of the highlighted area.

The following special character sequences are also available:

  • ##g## - Green
  • ##y## - Yellow
  • ##bl## - Blue
  • ##r## - Red
  • ##b## - Bold

Please use the above coloring options sparingly. It is sometimes nice to use them to get wiki console output to match the colors that are displayed on a Linux console. Also note that for every color above, there is a matching ##!(colorcode)## option to turn color off prior to end of line.

Here is an example of its use:

root # bluetoothctl 
[NEW] Controller 00:02:72:C9:62:65 antec [default]
root ##bl##[bluetooth]##!bl###power on
Changing power on succeeded
root ##bl##[bluetooth]##!bl### agent on
Agent registered
root ##bl##[bluetooth]##!bl### scan on
Discovery started
root ##bl##[bluetooth]##!bl### devices
Device 00:1F:20:3D:1E:75 Logitech K760
root ##bl##[bluetooth]##!bl### pair 00:1F:20:3D:1E:75
Attempting to pair with 00:1F:20:3D:1E:75
[CHG] Device 00:1F:20:3D:1E:75 Connected: yes
root ##r##[agent]##!r## Passkey: 454358
root ##r##[agent]##!r## Passkey: 454358
root ##r##[agent]##!r## Passkey: 454358
root ##r##[agent]##!r## Passkey: 454358
root ##r##[agent]##!r## Passkey: 454358
root ##r##[agent]##!r## Passkey: 454358
root ##r##[agent]##!r## Passkey: 454358
[CHG] Device 00:1F:20:3D:1E:75 Paired: yes
Pairing successful
[CHG] Device 00:1F:20:3D:1E:75 Connected: no
root ##bl##[bluetooth]##!bl### connect 00:1F:20:3D:1E:75
Attempting to connect to 00:1F:20:3D:1E:75
[CHG] Device 00:1F:20:3D:1E:75 Connected: yes
Connection successful
root ##bl##[bluetooth]##!bl### quit
[DEL] Controller 00:02:72:C9:62:65 antec [default]
root #

Fancy Notes

notes, warnings, tips, and important templates will help bring emphasis to articles drawn up.

{{fancynote|this is a fancy note}}


   Note

this is a fancy note


{{fancyimportant|this is a fancy important}}


   Important

this is a fancy important


{{fancywarning|this is a fancy warning}}


   Warning

this is a fancy warning


{{fancytip|this is a fancy tip}}


   Tip

this is a fancy tip


Kernelop

To display kernel configuration options, we encourage you to use the kernelop template. To use the kernelop template, create an entry similar to the following example:

{{kernelop|title=foo,bar|desc=
kernel options pasted from "make menuconfig"
}} 
   Note

Kernelop is colored blue to slightly resemble the blueish background from make menuconfig.

Adding this entry will give you the following output: Under foo-->bar:

kernel options

Here's a more concrete example: Under File systems:

<M> Second extended fs support          
[ ]   Ext2 extended attributes          
[ ]   Ext2 execute in place support     
<M> Ext3 journalling file system support

Examples of usage:


Marking Pages as Needing Updates

If you find outdated wiki content, but you don't have the time or ability to update it, add one of the following templates to the wikitext of the page. This will add the page to the Needs Updates Category so we can identify pages that need updating:

{{PageNeedsUpdates}}
{{SectionNeedsUpdates}}


Examples of usage:

Inline Code

To emphasize filenames, commands, and other technical jargon when they appear inline in a paragraph, use the <code> element. Follow the example below:

The <code>/etc/fstab</code> file is an important one. Another important file is <code>/boot/grub/grub.cfg</code>.

This example produces the following output:

The /etc/fstab file is an important one. Another important file is /boot/grub/grub.cfg.

   Important

The <tt> tag has been deprecated for the purpose of tagging inline code, to conform with HTML5.

Screencasting

screencasting is an easy method to explain complex tasks. take for instance youtu.be/5KDei5mBfSg we chop off the id and insert it into the following syntax to produce a video example.
tiny:

{{#widget:YouTube|id=5KDei5mBfSg|width=320|height=180}}

standard:

{{#widget:YouTube|id=5KDei5mBfSg|width=700|height=420}}