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

(Difference between pages)
(Initramfs)
 
(Paragraphs)
 
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
+
</console>
+
Portage will now go about installing the sources to ''/usr/src''. It will also symlink the kernel-version directory to a directory called ''linux''.
+
  
=== Configuring the kernel ===
+
* First, to perform edits on the wiki, you must {{CreateAccount}} and log in.
Now that the kernel sources are on your system, you should configure them. To do this, change your directory to ''/usr/src/linux''
+
* 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.
<console>
+
* 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.
###i## cd /usr/src/linux
+
* 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".)
</console>
+
* 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.
As we are now in the kernel sources directory, we can run a script that allows us to modify them. Run:
+
* 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.
<console>
+
###i## make menuconfig
+
</console>
+
  
While you edit the sources, keep the following in mind:
+
{{fancytip|The following sections document how to use wikitext and Funtoo templates on the Funtoo wiki.}}
* 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.  
+
  
 +
== Paragraphs ==
  
Things that you may need to include in your kernel:
+
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.
  
as '''modules''':
+
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:
  
* Wireless/LAN drivers
+
foobar
* Support for your graphics card
+
* Support for your audio card
+
* Support for USB devices
+
  
 +
This can rear its ugly head when specifying template parameters, so you will get this:
  
as '''built in''':
+
{{fancynote| ugh!}}
* scsi sata & or ata controllers
+
* file system used
+
  
{{fancynote|1=
+
...instead of this:
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]]}}
+
  
=== Building and installing the kernel sources ===
+
{{fancynote|This looks much better!}}
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:
+
== Page and Section Capitalization ==
<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 ==
+
In general, capitalize all words in page names and section heading except:
=== Getting ready to start ===
+
* Articles: a, an, the
 +
* Coordinating Conjunctions: and, but, or, for, nor, etc.
 +
* Prepositions (fewer than five letters): on, at, to, from, by, etc.
  
{{fancynote|In this case we are building a kernel that is booting root in LVM over encrypted LUKS container.
+
== Document Heirarchy ==
If you don't have this setup, don't worry, you just don't need all the modules, but everything else is similar.}}
+
First, there is the decision which linux kernel sources we need.
+
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!
+
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:
  
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]].
+
<pre>= Page Title =
  
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.
+
== Chapter Title ==
  
{{fancynote|1=
+
=== Section Title ===
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!
+
==== SubSection Title ====
  
=== Kernel Sources ===
+
</pre>
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 ===
+
== Links ==
  
Regardless of the tools you already have installed, it is recommended to follow the steps below, even if you find them to be redundant.
+
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>.
First, we edit our <code>/etc/portage/make.conf</code>:
+
 
 +
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.
 +
 
 +
== Lists ==
 +
 
 +
MediaWiki supports a number of list formats:
 +
 
 +
* 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><nowiki><blockquote></nowiki></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>
 +
 
 +
== Literal Text and HTML Symbols ==
 +
 
 +
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!)
  
 
<pre>
 
<pre>
#These compiler flags are just tweaking (optimazation) and NOT necessary:
+
* Unordered List
CFLAGS="-O2 -pipe -march=native -ftracer -fforce-addr"
+
* Unordered Item 2
CXXFLAGS="${CFLAGS} -fpermissive -fomit-frame-pointer"
+
** Unordered sub-item
KDIR=/usr/src/linux
+
 
KERNEL="symlink build"
+
# Ordered List
USE="$KERNEL ....here are your use flags...."
+
# Ordered Item 2
## These modules are available:
+
## Ordered sub-item
## 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:
+
;Term: This is called a "definition list". It is used when defining various terms.
DRACUT_MODULES="crypt lvm plymouth biosdevname dmraid crypt-gpg dmsquash-live ssh-client syslog"
+
 
 +
If you need to quote a portion of text from another site, use <tt><nowiki><blockquote></nowiki></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>
 
</pre>
 
</pre>
  
Next, we set the package keywords by adding the following to <code>/etc/portage/package.use</code>:
+
== Displaying Source Code ==
  
 +
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>
 
<pre>
sys-kernel/dracut dm net device-mapper crypt lvm
+
<syntaxhighlight lang="python">
 +
import system
 +
</syntaxhighlight>
 
</pre>
 
</pre>
  
{{fancynote|If you don't have lvm over encrypted LUKS you just add the "net" keyword here, or "selinux".}}
+
This will produce the following output:
  
 +
<syntaxhighlight lang="python">
 +
import system
 +
</syntaxhighlight>
  
Next, we build our packages:
+
Alternatively, if you need a caption, use can use the file template, specifying a <tt>lang=</tt> parameter:
<console>
+
###i## emerge -av app-portage/gentoolkit sys-kernel/pf-sources sys-kernel/dracut sys-boot/plymouth sys-boot/plymouth-openrc-plugin
+
</console>
+
  
=== Preparing the kernel ===
+
<pre>
 +
{{file|name=foobar|lang=python|desc=foobarosity|body=
 +
import system
 +
}}
 +
</pre>
  
We go now to the sources directory and enter the following commands to update the kernel's  .config file:
+
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>
 +
{{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>
 +
 
 +
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
 +
}}
 +
 
 +
== Console ==
 +
To display console output, use the <tt>&#60;console&#62;</tt> tag:
 +
 
 +
For a root console:
 +
<pre>
 
<console>
 
<console>
###i## cd /usr/src/linux/
+
###i## run a command as root
###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>
 
+
</pre>
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.
+
Produces:
 
<console>
 
<console>
###i## make localmodconfig
+
###i## run a command as root
Enable different security models (SECURITY) [Y/n/?] y
+
Enable the securityfs filesystem (SECURITYFS) [Y/?] y
+
Socket and Networking Security Hooks (SECURITY_NETWORK) [Y/?] y
+
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
+
NSA SELinux Support (SECURITY_SELINUX) [Y/n/?] y
+
  NSA SELinux boot parameter (SECURITY_SELINUX_BOOTPARAM) [N/y/?] n
+
  NSA SELinux runtime disable (SECURITY_SELINUX_DISABLE) [N/y/?] n
+
  NSA SELinux Development Support (SECURITY_SELINUX_DEVELOP) [Y/n/?] y
+
  NSA SELinux AVC Statistics (SECURITY_SELINUX_AVC_STATS) [Y/n/?] y
+
  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
+
    NSA SELinux maximum supported policy format version value (SECURITY_SELINUX_POLICYDB_VERSION_MAX_VALUE) [19] 19
+
TOMOYO Linux Support (SECURITY_TOMOYO) [Y/n/?] y
+
  Default maximal count for learning mode (SECURITY_TOMOYO_MAX_ACCEPT_ENTRY) [2048] 2048
+
  Default maximal count for audit log (SECURITY_TOMOYO_MAX_AUDIT_LOG) [1024] 1024
+
  Activate without calling userspace policy loader. (SECURITY_TOMOYO_OMIT_USERSPACE_LOADER) [Y/n/?] y
+
AppArmor support (SECURITY_APPARMOR) [Y/n/?] y
+
  AppArmor boot parameter default value (SECURITY_APPARMOR_BOOTPARAM_VALUE) [1] 1
+
Integrity Measurement Architecture(IMA) (IMA) [Y/n/?] y
+
EVM support (EVM) [N/y/?] (NEW)
+
Default security module
+
  1. SELinux (DEFAULT_SECURITY_SELINUX)
+
  2. TOMOYO (DEFAULT_SECURITY_TOMOYO)
+
  3. AppArmor (DEFAULT_SECURITY_APPARMOR)
+
> 4. Unix Discretionary Access Controls (DEFAULT_SECURITY_DAC)
+
choice[1-4?]: 4
+
warning: (ACPI_HOTPLUG_CPU) selects ACPI_CONTAINER which has unmet direct dependencies (ACPI && EXPERIMENTAL)
+
warning: (MEDIA_TUNER) selects MEDIA_TUNER_TEA5761 which has unmet direct dependencies (MEDIA_SUPPORT && VIDEO_MEDIA && I2C && EXPERIMENTAL)
+
#
+
# 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!
+
For a non-root console:
 
+
<pre>
=== Building the Kernel ===
+
 
<console>
 
<console>
###i## make -j8  bzImage
+
$ ##i##run a command as user
###i## make -j8 modules
+
</console>
###i## make modules_install
+
</pre>
###i## make install
+
Produces:
 +
<console>
 +
$ ##i##run a command as user
 
</console>
 
</console>
  
== Initramfs ==
+
{{fancyimportant|1=
{{fancywarning|Make sure that you have built and installed your kernel sources / modules before building an initramfs.}}
+
Note that we use a <tt>#</tt> prompt for <tt>root</tt> and a <tt>$</tt> prompt to denote a non-root user.}}
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!
+
{{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.}}
<console>
+
 
###i## boot-update -v
+
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.
###i## reboot
+
 
 +
The following special character sequences are also available:
 +
* <code>##g##</code> - Green
 +
* <code>##y##</code> - Yellow
 +
* <code>##bl##</code> - Blue
 +
* <code>##r##</code> - Red
 +
* <code>##b##</code> - 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 <code>##!(colorcode)##</code> option to turn color off prior to end of line.
 +
 
 +
Here is an example of its use:<console>
 +
# ##i##bluetoothctl
 +
[##g##NEW##!g##] Controller 00:02:72:C9:62:65 antec [default]
 +
##bl##[bluetooth]##!bl###power on
 +
Changing power on succeeded
 +
##bl##[bluetooth]##!bl### ##i##agent on
 +
Agent registered
 +
##bl##[bluetooth]##!bl### ##i##scan on
 +
Discovery started
 +
##bl##[bluetooth]##!bl### ##i##devices
 +
Device 00:1F:20:3D:1E:75 Logitech K760
 +
##bl##[bluetooth]##!bl### ##i##pair 00:1F:20:3D:1E:75
 +
Attempting to pair with 00:1F:20:3D:1E:75
 +
[##y##CHG##!y##] Device 00:1F:20:3D:1E:75 Connected: yes
 +
##r##[agent]##!r## Passkey: 454358
 +
##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]
 +
#
 
</console>
 
</console>
  
[[Category:HOWTO]]
+
== Fancy Notes ==
[[Category:Featured]]
+
notes, warnings, tips, and important templates will help bring emphasis to articles drawn up.
[[Category:Kernel]]
+
<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]]
 +
 
 +
 
 +
== 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 [[:Category:Needs Updates|Needs Updates Category]] so we can identify pages that need updating:
 +
 
 +
<pre>
 +
{{PageNeedsUpdates}}
 +
{{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>.
 +
 
 +
{{fancyimportant|1=
 +
The &#60;tt&#62; 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.<br />
 +
tiny:
 +
<pre>{{#widget:YouTube|id=5KDei5mBfSg|width=320|height=180}}</pre>
 +
standard:
 +
<pre>{{#widget:YouTube|id=5KDei5mBfSg|width=700|height=420}}</pre>
 +
{{#widget:YouTube|id=5KDei5mBfSg|width=700|height=420}}
 +
 
 +
[[Category:Wiki Development]]

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: foobarosity (python source code)
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:

# run a command as root

For a non-root console:

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

Produces:

$ 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:
# bluetoothctl 
[NEW] Controller 00:02:72:C9:62:65 antec [default]
[bluetooth]#power on
Changing power on succeeded
[bluetooth]# agent on
Agent registered
[bluetooth]# scan on
Discovery started
[bluetooth]# devices
Device 00:1F:20:3D:1E:75 Logitech K760
[bluetooth]# 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
[agent] Passkey: 454358
[agent] Passkey: 454358
[agent] Passkey: 454358
[agent] Passkey: 454358
[agent] Passkey: 454358
[agent] Passkey: 454358
[agent] Passkey: 454358
[CHG] Device 00:1F:20:3D:1E:75 Paired: yes
Pairing successful
[CHG] Device 00:1F:20:3D:1E:75 Connected: no
[bluetooth]# 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
[bluetooth]# quit
[DEL] Controller 00:02:72:C9:62:65 antec [default]
#

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}}