Difference between pages "Emerge" and "Coding Standards"

From Funtoo
(Difference between pages)
Jump to: navigation, search
 
 
Line 1: Line 1:
== Getting started with emerge ==
+
== Basic Coding Standards In A Nutshell ==
Emerge is the front-end for funtoo's portage package manager. With emerge it is easy to install, update or remove packages.
+
  
=== Update package database ===
+
* word wrap at 160 characters
'''Sync local package database. This will update your local Portage tree with the latest Funtoo ebuilds.'''
+
* use tabs, not spaces, for indentation
<console>
+
* use a tab size of 4 characters (tab size can be adjusted but it affects when you reach the magic 160 char wrap limit)
###i## emerge --sync
+
* comments on separate lines, at same indent level as code (sections can be marked by 'outdented' comments)
</console>
+
  
=== Search packages ===
+
== Word Wrap ==
'''Search packages by name.'''
+
<console>
+
###i## emerge -s firefox
+
###i## emerge --search firefox
+
</console>
+
  
'''Search packages by description.'''
+
Modern editors do a good job of displaying very long lines of text, and modern displays have sufficient resolution for displaying much more than 80 characters per line, even at 1024x768 resolution. You should definitely not split an elegant single-line piece of code into multiple lines just for the sake of keeping the whole thing under 80 characters. It's especially bad if you take, say, a 100-character line and split it into ''more'' than two lines just for the sake of keeping it under 80 characters in length. But you need or want to use multiple lines to keep your code readable, more power to you. Don't just do it to maintain "Apple IIe with 80-column card compatibility" for any reason. That's just silly.
<console>
+
###i## emerge -S web browser
+
###i## emerge --searchdesc web browser
+
</console>
+
  
=== Install packages ===
+
== Tabs vs. Spaces ==
'''Install package.'''
+
<console>
+
###i## emerge firefox
+
</console>
+
  
'''Install multiple packages.'''
+
Tabs and spaces had a fight. Tabs won. They're easier to deal with and allow configurable indentation for those who require it. I don't care what some other group or organization says the convention is. If you don't want to use tabs because you want all your end-of-line comments to line up beautifully, then I have a solution: don't use end-of-line comments (see the next section) and you'll be fine.
<console>
+
###i## emerge firefox thunderbird
+
</console>
+
  
'''Install package. Ask for confirmation before performing any changes. Show verbose output.'''
+
== Comments ==
<console>
+
###i## emerge -av firefox
+
###i## emerge --ask firefox
+
</console>
+
  
=== Remove packages ===
+
Add comments that provide some insight into your code, and that help to provide context. Also, because we use tabs, place comments on their own lines, separate from source code, ideally separated by a blank line above and below unless you are verbosely commenting every line of code. This also encourages longer, more descriptive comments that may span multiple lines. If you span multiple lines, use a consistent right margin of 160 characters. Comments help you understand your code when you come back to it a year later, so you are adding descriptive comments for yourself as much as for others. Include information you would find helpful if you had a sudden case of amnesia. They are especially important for free/open source software that needs to be maintained by various people over the years.
'''Remove package.'''
+
<console>
+
###i## emerge -C firefox
+
###i## emerge --unmerge firefox
+
</console>
+
  
'''Remove package. Ask for confirmation before performing any changes.'''
+
== Profanity ==
<console>
+
###i## emerge -aC firefox
+
</console>
+
  
'''Remove orphaned packages. Ask for confirmation before performing any changes.'''
+
Do not place any profanity in source code comments or variable names. It just makes you look unprofessional, silly and incompetent.
<console>
+
###i## emerge -a --depclean
+
</console>
+
  
=== Update packages ===
 
'''Update all packages.'''
 
<console>
 
###i## emerge -uDN @world
 
</console>
 
  
'''Update all packages. Ask for confirmation before performing any changes. Show verbose output.'''
+
[[Category:QA]]
<console>
+
###i## emerge -uavDN @world
+
</console>
+
 
+
== Emerge options ==
+
 
+
; --sync
+
: Updates the portage tree that is located in /usr/portage by default.
+
 
+
; --search -s
+
: Searches  for  matches  of  the  supplied  string in the portage tree.
+
 
+
; --searchdesc -S
+
: Matches the search string against the description field as well as the package name.
+
 
+
; --ask -a
+
: Ask for confirmation before performing any changes.
+
 
+
; --pretend -p
+
: Instead of actually performing the merge, simply display what *would* have been installed if --pretend weren't used.
+
 
+
; --unmerge -C
+
: Removes all matching packages.
+
 
+
; --update -u
+
: Updates  packages to the best version available, which may not always be the  highest version number due to masking for testing and development.
+
 
+
; --deep [DEPTH] -D
+
: force  emerge  to  consider  the  entire  dependency tree of packages, instead of checking only the immediate dependencies of the packages.
+
 
+
; --newuse -N
+
: Tells emerge to include installed packages where USE flags have changed since compilation.
+
 
+
; --depclean -c
+
: Remove orphaned packages. Cleans the system by removing packages that are not associated with explicitly merged packages.
+
 
+
; --autounmask-write
+
: Automatically write package.use settings as necessary to satisfy dependencies.
+
 
+
; --resume -r
+
: Resumes  the  most recent merge list that has been aborted due to an error.
+
 
+
; --jobs[=JOBS] -j [JOBS]
+
: Specifies the number of packages to build simultaneously.
+
 
+
; --load-average [LOAD]
+
: Specifies  that  no  new  builds should be started if there are other builds running and the load average is at least LOAD (a floating-point number).
+
 
+
== Configuration ==
+
=== make.conf ===
+
Emerge can be configured with <code>/etc/portage/make.conf</code>
+
 
+
 
+
<pre>
+
CFLAGS="-march=native -O2 -pipe"
+
CXXFLAGS="-march=native -O2 -pipe"
+
 
+
MAKEOPTS="-j2"
+
EMERGE_DEFAULT_OPTS="--jobs 2 --load-average 2"
+
INPUT_DEVICES="evdev synaptics"
+
VIDEO_CARDS="intel i965"
+
LINGUAS="en en_US en_GB"
+
ACCEPT_LICENSE="*"
+
 
+
USE="mmx mmxext sse sse2 sse3 ssse3 threads alsa X gtk xcb dri opengl vaapi udev \
+
    svg x264 xvid gstreamer webm vpx icu bash-completion vim-pager \
+
    -gnome -xscreensaver -cups -fortran -deprecated -iptables -ipv6 -geoloc \
+
    -mta -sendmail -kmod -tiff -live -quicktime -real -gpm -themes"
+
</pre>
+
 
+
=== package.use ===
+
Per-package use flags can be configured in <code>/etc/portage/package.use</code>:
+
 
+
 
+
<pre>
+
x11-wm/dwm savedconfig
+
x11-drivers/ati-drivers qt4
+
media-sound/ncmpcpp visualizer clock taglib
+
</pre>
+
 
+
=== package.accept_keywords ===
+
If you want to install a package that has not been tested on your architecture you need to edit <code>/etc/portage/package.accept_keywords</code>:
+
 
+
 
+
<pre>
+
=app-misc/screenfetch-9999 **
+
</pre>
+
 
+
== Other Resources ==
+
For more info see the emerge man page.
+
<console>
+
$##i## man emerge
+
</console>
+
 
+
[[Category:Portage]]
+
[[Category:HOWTO]]
+
[[Category:Tutorial]]
+
[[Category:System]]
+
[[Category:First Steps]]
+

Latest revision as of 01:26, 18 January 2011

Basic Coding Standards In A Nutshell

  • word wrap at 160 characters
  • use tabs, not spaces, for indentation
  • use a tab size of 4 characters (tab size can be adjusted but it affects when you reach the magic 160 char wrap limit)
  • comments on separate lines, at same indent level as code (sections can be marked by 'outdented' comments)

Word Wrap

Modern editors do a good job of displaying very long lines of text, and modern displays have sufficient resolution for displaying much more than 80 characters per line, even at 1024x768 resolution. You should definitely not split an elegant single-line piece of code into multiple lines just for the sake of keeping the whole thing under 80 characters. It's especially bad if you take, say, a 100-character line and split it into more than two lines just for the sake of keeping it under 80 characters in length. But you need or want to use multiple lines to keep your code readable, more power to you. Don't just do it to maintain "Apple IIe with 80-column card compatibility" for any reason. That's just silly.

Tabs vs. Spaces

Tabs and spaces had a fight. Tabs won. They're easier to deal with and allow configurable indentation for those who require it. I don't care what some other group or organization says the convention is. If you don't want to use tabs because you want all your end-of-line comments to line up beautifully, then I have a solution: don't use end-of-line comments (see the next section) and you'll be fine.

Comments

Add comments that provide some insight into your code, and that help to provide context. Also, because we use tabs, place comments on their own lines, separate from source code, ideally separated by a blank line above and below unless you are verbosely commenting every line of code. This also encourages longer, more descriptive comments that may span multiple lines. If you span multiple lines, use a consistent right margin of 160 characters. Comments help you understand your code when you come back to it a year later, so you are adding descriptive comments for yourself as much as for others. Include information you would find helpful if you had a sudden case of amnesia. They are especially important for free/open source software that needs to be maintained by various people over the years.

Profanity

Do not place any profanity in source code comments or variable names. It just makes you look unprofessional, silly and incompetent.