https://wiki.archlinux.org/api.php?action=feedcontributions&user=Bhobbit&feedformat=atomArchWiki - User contributions [en]2024-03-29T09:01:09ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Msmtp&diff=112527Msmtp2010-07-23T00:31:50Z<p>Bhobbit: Clarification</p>
<hr />
<div>[[Category:Internet and Email (English)]] [[Category:HOWTOs (English)]] {{DISPLAYTITLE:msmtp}}<br />
[http://msmtp.sourceforge.net/ msmtp] is a very simple and easy to use smtp client with excellent [[sendmail]] compatibility.<br />
<br />
==Installing==<br />
{{package Official|msmtp}} is in the ''extra'' repository.<br />
# pacman -S msmtp<br />
<br />
==Quick start==<br />
The following is an example of a msmtp configuration file for several accounts. If msmtp throws errors when using this file, search for double byte '\xc2\xa0' characters that may have been erroneously inserted.<br />
{{file|name=~/.msmtprc|content=<br />
# Accounts will inherit settings from this section<br />
defaults<br />
auth on<br />
tls on<br />
tls_trust_file /usr/share/ca-certificates/mozilla/Thawte_Premium_Server_CA.crt<br />
<br />
# A first gmail address<br />
account gmail<br />
host smtp.gmail.com<br />
port 587<br />
from username@gmail.com<br />
user username@gmail.com<br />
password password<br />
<br />
# A second gmail address<br />
account gmail2 : gmail<br />
from username2@gmail.com<br />
user username2@gmail.com<br />
password password2<br />
# It looks like Google's in the process of becoming its own certificate<br />
# authority. For some users, they seem to have switched to a "Google<br />
# Certificate Authority" certificate, which is rooted in Equifax.<br />
#tls_trust_file /usr/share/ca-certificates/mozilla/Equifax_Secure_CA.crt<br />
<br />
<br />
# A freemail service<br />
account freemail<br />
host smtp.freemail.example<br />
from joe_smith@freemail.example<br />
user joe.smith<br />
password secret<br />
<br />
# A provider's service<br />
account provider<br />
host smtp.provider.example<br />
<br />
# Set a default account<br />
account default : gmail<br />
}}<br />
<br />
msmtp will refuse to start if ''user'' configuration file is readable and writeable to anyone else but the owner:<br />
$ chmod 600 ~/.msmtprc<br />
<br />
This does not apply to system configuration file in /usr directory.<br />
<br />
==Test msmtp==<br />
The {{codeline|-a}} flag specifies the account to use as sender; {{codeline|<username>@domain.com}} is the recipient.<br />
<br />
Save (with the addresses you want to use)<br />
To: <username>@domain.com<br />
From: username@gmail.com<br />
Subject: A test<br />
<br />
Yadda, yadda, yadda.<br />
<br />
as, say, "test.mail".<br />
<br />
Then execute<br />
<br />
$ cat test.mail | msmtp -a default <username>@domain.com<br />
<br />
Do ''not'' merely use "echo 'Yadda, yadda, yadda.'" instead of "cat test.mail". This causes at least Gmail and Yahoo to deliver the mail incorrectly.<br />
<br />
==Miscellaneous==<br />
<br />
===Practical password management===<br />
The {{codeline|password}} directive may be omitted. In that case, if the account in question has {{codeline|auth}} set to a legitimate value other than {{codeline|off}}, invoking msmtp from an interactive shell will ask for the password before sending mail. msmtp will not prompt if it has been called by another type of application, such as [[Mutt]].<br />
<br />
If this is not desired, an alternative is to place passwords in {{filename|~/.netrc}}, a file that can act as a common pool for msmtp, [[OfflineIMAP]], and associated tools.<br />
<br />
===Using msmtp offline===<br />
{{note|The msmtp source distribution includes msmtpq and msmtpQ in the ./scripts directory, which are updated versions of the msmtpqueue bundle.}}<br />
<br />
Although msmtp is great, it requires that you be online to use it. This isn't ideal for people on laptops with intermittent connections to the Internet or dialup users. Several scripts have been written to remedy this fact, collectively called msmtpqueue.<br />
<br />
The scripts can be downloaded from [http://sourceforge.net/project/showfiles.php?group_id=86651&package_id=96024 SourceForge], the most recent of which is msmtpqueue-0.5.tar.gz.<br />
<br />
Once the scripts have been downloaded extract them using:<br />
$ tar xf msmtpqueue-0.5.tar.gz<br />
<br />
After that, copy the scripts to a convenient location on your computer ({{filename|/usr/local/bin}} is a good choice):<br />
$ cp msmtpqueue-0.5/*.sh /usr/local/bin/<br />
<br />
Finally, change your MUA to use msmtp-enqueue.sh instead of msmtp when sending e-mail. Queued messages will be stored in {{filename|~/.msmtpqueue}}.<br />
<br />
When you want to send any mail that you've created and queued up run:<br />
$ /usr/local/bin/msmtp-runqueue.sh<br />
<br />
Adding {{filename|/usr/local/bin}} to your PATH can save you some keystrokes if you're doing it manually. The README file that comes with the scripts has some handy information, reading it is recommended.<br />
<br />
===Vim syntax highlighting===<br />
The msmtp source distribution includes a {{filename|msmtprc}} highlighting script for [[Vim]]. Install it from {{filename|./scripts/vim/msmtp.vim}}.<br />
<br />
==Troubleshooting==<br />
<br />
===Issues with TLS===<br />
If you see the following message:<br />
msmtp: TLS certificate verification failed: the certificate hasn't got a known issuer<br />
it probably means your tls_trust_file is not right.<br />
<br />
Just follow the [http://msmtp.sourceforge.net/doc/msmtp.html#Transport-Layer-Security fine manual]. It explains you how to find out the server certificate issuer of a given smtp server. Then you can explore the {{filename|/usr/share/ca-certificates/}} directory to find out if by any chance, the certificate you need is there. If not, you will have to get the certificate on your own.<br />
<br />
If you are completely deseperate, but are 100% sure you are communicating with the right server, you can always temporarily disable the cert check:<br />
$ msmtp --tls-certcheck off</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Talk:VirtualBox&diff=102991Talk:VirtualBox2010-04-12T23:11:21Z<p>Bhobbit: </p>
<hr />
<div>I really think this article should be cleaned up and simplified. It is a little confusing- specifically the "Using host interface networking" section. I would atempt to do it myself, but I am not super knowlegable about this topic. Even Breaking this into sections with advice on which way would be best to use would be helpful. ~[[User:meskarune|meskarune]] (Fri, June 26, 2009)<br />
<br />
Anybody, any experience with how to use existing vmware virtual machine in virtualbox? I tried, but without success. I'll retry using: http://liquidat.wordpress.com/2007/11/23/howto-transform-a-qemu-image-to-a-virtualbox-image/ and post my findings.<br />
<br />
The main problem I find with this article is that it is not always clear which parts refer to an archlinux host and which to an archlinux guest. I think ideally the whole article should be re-structured to make this super-clear. [[User:maninalift|maninalift]]<br />
<br />
--<br />
<br />
Could someone please update the wiki with instructions on how to install Guest Additions on an Arch Linux virtual machine? I have been trying to figure this one out for a while now and I can't seem to get the proper daemons/modules to install. ~[[User:Thayer.w|Thayer]] (Thursday, 19 July 2007)<br />
:<strike>I'm bumping this again, because the current instructions don't seem to work.</strike> Nevermind, got it working =) ~[[User:Thayer.w|Thayer]] (Weds, Aug 6, 2008)<br />
<br />
--<br />
<br />
== Corrected USB-problem ==<br />
<br />
The fstab entry contains the group-id 85 which can vary on other PCs. I added a possible solution...<br />
=== More USB ===<br />
Can confirm that you can use mass storage USB passthrough with 3.0.4. But you must mount /proc/bus/usb as described in the article for any other types of USB devices such as mice & Blackberries<br />
<br />
For me an entry in the fstab was also necessary to use my USB flash drive in the WinXP guest. But instead of the line in the wiki article I had to use this one: <br />
none /sys/bus/usb/drivers usbfs devgid=108,devmode=664 0 0 (see this thread: http://bbs.archlinux.org/viewtopic.php?pid=640440)<br />
<br />
== Using host interface networking (the Arch way) & udev rules ==<br />
<br />
the wiki ask to set a file called 60-vboxdrv.rules under the directory /etc/udev/rules.d, but when I've tried, a file named 60-virtualbox.rules is already here, with the same setting. I don't know if the name matter, how from where the file come (virtualbox-ose via pacman ? guest addition ?)<br />
<br />
So I report this.<br />
--[[User:Gkrnours|Gkrnours]] 04:38, 13 May 2009 (EDT)<br />
<br />
== vboxdrv module ==<br />
Since Arch uses MODULES_AUTOLAD=yes by default in /etc/rc.conf, is it still mandatory to add vboxdrv in the MODULES array? I don't think so but I'm not totally sure.<br />
<br />
rent0n<br />
<br />
== vboxusers group ==<br />
It would be nice if someone explained why you might need to add your user to {{Codeline|vboxusers}} group. I did not add my user to this group and everything worked as expected. --[[User:Bhobbit|Bhobbit]] 19:11, 12 April 2010 (EDT)</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Frequently_asked_questions&diff=101536Frequently asked questions2010-03-30T10:38:09Z<p>Bhobbit: Shortened question</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:FAQs (English)]]<br />
{{i18n|FAQ}}<br />
<br />
Besides the questions covered below, you may find [[The Arch Way]] and [[Arch Linux]] helpful. Both of the articles contain a good deal of information about Arch Linux.<br />
<br />
= General =<br />
==Q) What is Arch Linux? ==<br />
'''A)''' From the article entitled [[Arch Linux]]:<br />
<br />
''Arch Linux is an independently developed i686/x86-64 community distribution, based on a rolling-release model and targeted at competent GNU/Linux users which offers large binary repositories and excellent package management as well as a ports-like packaging system. Development focuses on a balance of minimalism, elegance, code correctness and modernity. Version 0.1 (Homer) was released March 11, 2002.''<br />
<br />
==Q) Why would I want to use Arch? ==<br />
'''A)''' If you have read, and agree with [[The Arch Way]] philosophy, embrace the 'do-it-yourself' approach and require or desire a simple, elegant, highly customizable, bleeding edge, general purpose GNU/Linux distribution, chances are you may like Arch.<br />
<br />
==Q) Why wouldn't I want to use Arch?==<br />
'''A)''' If you have read, and disagree with [[The Arch Way]] philosophy, and do not have the ability/time/desire for a 'do-it-yourself' GNU/Linux distribution, chances are Arch may not be for you.<br />
<br />
You may also not want to use Arch if:<br />
* you require support for an architecture other than x86_64 or i686.<br />
* you take a strong stand on using a distribution which only provides free software as defined by GNU.<br />
* you believe an operating system should configure itself, run out of the box, and include a complete default set of software and desktop environment on the installation media.<br />
* you do not want a bleeding edge, rolling release GNU/Linux distribution.<br />
* you are happy with your current OS of choice.<br />
* you want an OS with a different goal targeted at a different userbase.<br />
<br />
==Q) What distro is Arch based on? ==<br />
'''A)''' Arch is independently developed, was built from scratch and is not based on any other GNU/Linux distribution. Before creating Arch, Judd Vinet admired and used <code>CRUX</code>, a great, minimalist distro created by Per Lidén. Originally inspired by ideas in common with <code>CRUX</code>, Arch was built from scratch, and pacman was then coded in C.<br />
<br />
==Q) I am a complete GNU/Linux beginner. Should I use Arch?==<br />
'''A)''' This question has had much debate. Arch is targeted at more-advanced GNU/Linux users, but some people feel "Arch is a good place to start". If you are a beginner and want to use Arch, just be warned that you must be willing to learn as well as accept the fact that Arch is largely a do-it-yourself distribution. It is the user who assembles the system, and controls what it will be. Before asking any question, do your own independent research by googling, searching the Wiki, and searching the forum (and reading past FAQs). If you do that, you should be fine. Also know that many people do not want to answer the same basic questions over and over, so you are exposing yourself to that environment. ''There is a reason these resources were created/made available to you in the first place.'' Many thousands of ''volunteered'' hours have been spent compiling this excellent information.<br />
<br />
Recommended reading: The Arch Linux [[Beginners Guide|Beginners' Guide]].<br />
<br />
==Q) Is Arch designed to be used as a server? A desktop? A workstation?==<br />
'''A)''' Arch is not designed for any particular type of use. Rather, it is designed for a particular type of ''user''. Arch targets competent users who enjoy its do-it-yourself nature, and who further exploit it to shape the system to fit their unique needs. Therefore, in the hands of its target user base, Arch can be used for virtually any purpose. Many use Arch on both their desktops and workstations. And of course, archlinux.org runs on Arch.<br />
<br />
==Q) I really like Arch, except the development team needs to implement ''"feature X"''.==<br />
'''A)''' Before going further, did you read [[The Arch Way]]? Have you provided the feature/solution? Does it conform to the Arch philosophy of ''minimalism'' and ''code-correctness over convenience''? Get involved, contribute your code/solution to the community. If it is well regarded by the community and development team, perhaps it will be merged. The Arch community thrives on contribution and sharing of code and tools.<br />
<br />
==Q) When will the new release be made?==<br />
'''A)''' Arch Linux releases are merely a snapshot of the /core repository, combined with various features or modifications to the installer script itself. The rolling release model keeps every Arch Linux system current and on the bleeding edge by issuing one command.<br />
<br />
For this reason, releases are not terribly important in Arch, because the rolling-release system makes new releases out of date as soon as a package has been updated. If you are looking to obtain the latest Arch Linux release, you do not need to reinstall. You simply run the {{Codeline|pacman -Syu}} command and your system will be identical to what you would get with a brand-new install.<br />
<br />
For this same reason, new Arch Linux releases are not typically full of new and exciting features. New and exciting features are released as needed with the packages that are updated, and can be obtained immediately via {{Codeline|pacman -Syu}}.<br />
<br />
==Q) Is Arch Linux a stable distro? Will I get frequent breakage? ==<br />
'''A)''' The long and short answer is: It is largely as stable as ''you'' make it. <br />
<br />
''You'' assemble your own Arch system, atop the simple base environment, and ''you'' control system upgrades. (Obviously, a larger, more bloated system incorporating multitudes of packages, multiple toolkits and desktop environments would be more likely to experience configuration issues due to upstream changes than a slimmer, more simple system would.) Arch is targeted at capable, proactive users. General UNIX competence and good system maintenance and upgrade practices also play a large role in system stability. Also recall that Arch packages are predominantly unpatched, so most application issues are inherently upstream.<br />
<br />
Therefore, it is ''the user'' who is ultimately responsible for the stability of his own rolling release system. The user decides when to upgrade, and merges necessary changes when required. If the the user reaches out to the community for help, it is often provided in a timely manner. The difference between Arch and other distributions in this regard is that Arch is truly a 'do-it-yourself' distro; complaints of breakage are misguided and unproductive, since upstream changes are not the responsibility of Arch devs.<br />
<br />
==Q) What exactly ''is'' this 'BSD-style' init framework I keep hearing about? ==<br />
Part of BSD's heritage is the simple init framework that it has incorporated. The main difference between a BSD init and a sysV init is that Arch's BSD-style init uses a single line in a single file, {{Filename|/etc/rc.conf}}, to point to scripts within a single directory, {{Filename|etc/rc.d/}}, for all system services, regardless of runlevel.<br />
<br />
A SysV init, on the other hand, would use a system of multiple directories (usually 7 by default), one for each runlevel: {{Filename|/etc/rc.0,1,2,3,4,5,6}}. Each directory contains a gratuitous number of symlinks; one for each service. Each symlink points to a corresponding script in the {{Filename|/etc/init.d/}} directory. Needless to say, the SysV method is more complex, as by default dozens of symlinks reside under each {{Filename|/etc/rc.0,1,2,3,4,5,6}} directory in addition to all the scripts under {{Filename|/etc/init.d/}}. Keeping in line with its simple philosophy, Arch uses the BSD-style init.<br />
<br />
==Q) Arch needs more press (i.e. advertisement)==<br />
'''A)''' Arch gets plenty of press as it is. The goal of Arch Linux is not to be large, but rather, to provide an elegant, minimalist and bleeding edge distribution focused on simplicity and code-correctness. Organic, sustainable growth occurs naturally amongst the target user base.<br />
<br />
==Q) Arch needs more devs==<br />
'''A)''' Possibly so. Feel free to volunteer your time! Visit the [http://bbd.archlinux.org forums], [http://www.archlinux.org/irc/ IRC channels], and [http://mailman.archlinux.org/mailman/listinfo/ mailing lists], and see what needs to be done. Getting involved in the Community Contributions subforum is a good way to start.<br />
<br />
==Q) Why is Arch so slow? Programs open slowly or do not run at all!==<br />
'''A)''' Make sure that your hostname is correctly set in {{Filename|/etc/hosts}} (i.e., that it matches the hostname in {{Filename|/etc/rc.conf}}. Have a look at "Configure the System" in The [[Beginners_Guide#F:_Configure_the_System|Beginners' Guide]]). If the hostnames do not match, applications may start up very slowly.<br />
<br />
==Q) Why is my internet so slow compared to other operating systems?==<br />
'''A)''' Is your network configured correctly? Have you double checked your {{Filename|/etc/rc.conf}} {{Filename|/etc/hosts}} and {{Filename|/etc/resolv.conf}}? Have a look at "Configure the System" in The [[Beginners_Guide#F:_Configure_the_System|Beginners' Guide]].<br />
<br />
==Q) Why is Arch using all my RAM? 2G used while I'm just staring at my desktop?==<br />
'''A)''' Essentially, unused RAM is wasted RAM. <br />
<br />
Many new users notice how the Linux kernel handles memory differently than they are used to. Since accessing data in RAM is much faster than from disk, the kernel caches recently accessed data in memory. The cached data is only cleared when the system begins to run out of unused memory and new data still needs to be loaded.<br />
<br />
Perhaps the most common culprit of this confusion is the {{Codeline|free}} command:<br />
<br />
{{Command|name=free -m|output=$ free -m<br />
total used free shared buffers cached<br />
Mem: 1009 741 267 0 104 359<br />
-/+ buffers/cache: 278 731 <-- NOTE THIS!<br />
Swap: 1537 0 1537}}<br />
<br />
It is important to note the {{Codeline|-/+ buffers/cache:}} line -- a representation of the amount of memory that is actually in "active use" and the amount of "available" memory, rather than "unused".<br />
<br />
In the above example, a laptop with 1G of total RAM appears to be using 741M of it, with naught but a few idling terminals and web browser open! However, upon examining the emphasized line, see that only 278M of it is in "active use", and in fact 731M is "available" for new data. Apparently, 104M of that "used" memory contains buffered data and 359M contains cached data, both of which can be cleared away if needed. Only 267M of the total is truly "free" of the burden of data storage.<br />
<br />
The result of all this? Performance!<br />
<br />
See [http://www.linuxjournal.com/article/2770 this wonderful article] if your curiosity has been piqued!<br />
<br />
=Package Management=<br />
==Q) I've found an error with Package X. What should I do?==<br />
'''A)''' First, you need to figure out if this error is something the Arch team can fix. Sometimes it's not (that Firefox crash may be the fault of the Mozilla team) - this is called an ''upstream error''. If it is an Arch problem, there is a series of steps you can take:<br />
#Search the forums for information. See if anyone else has noticed it.<br />
#Notify the package maintainer. Try a {{Codeline|pacman -Qi}} for this info.<br />
#Post a [[Reporting Bug Guidelines|bug report]] with detailed information at http://bugs.archlinux.org.<br />
#If you'd like, write a forum post detailing the problem and the fact that you have reported it already. This will help prevent a lot of people from reporting the same error.<br />
<br />
==Q) Will Arch have a database for pacman?==<br />
'''A)''' Possibly. There is discussion over the issue. <br><br />
http://bbs.archlinux.org/viewtopic.php?id=11193 <br><br />
http://bbs.archlinux.org/viewtopic.php?id=10898 <br><br />
Look at http://bugs.archlinux.org/task/5328, too.<br />
<br />
==Q) Arch packages need to use a unique naming convention. .pkg.tar.gz and .pkg.tar.xz are too long and/or confusing==<br />
'''A)''' This has been discussed on the Arch mailing list. Some proposed a .pac file extension. As far as is currently known, there is no plan to change the package extension.<br />
As Tobias Kieslich, one of the Arch devs, put it, "A package '''is''' a gzipped [xz] tarball! And it can be opened, investigated and manipulated by any tar-capable application. Moreover, the mime-type is automatically detected correctly by most applications."<br />
<br />
==Q) Pacman needs a library so other applications can easily access package information==<br />
'''A)''' Since version 3.0.0, pacman has been the front-end to libalpm, the "Arch Linux Package Management" library. This library allows alternative front-ends to be written (for instance, a GUI front-end).<br />
<br />
==Q) Why doesn't Pacman have an official GUI front-end?==<br />
'''A)''' Please read [[The Arch Way]] and [[Arch Linux]]. The answer is basically that the Arch dev team will not be providing one. Feel free to use one of those developed by users. There is a nice list of them on the [[UserContributionsPage]] in the links section, and a selective list on [[Pacman GUI Frontends]].<br />
<br />
==Q) Pacman needs ''"feature X!"''==<br />
'''A)''' Please read [[The Arch Way]] and [[Arch Linux]]. The Arch philosophy is "Keep It Simple". If you think the idea has merit, and does not violate this simple litany, then by all means, discuss it on the forum [http://bbs.archlinux.org/ here]. You might also like to check [http://bugs.archlinux.org here]; it's a place for feature requests if you find it is important.<br />
<br />
However, the best way to get a feature added to Pacman or Arch Linux is to implement it yourself. There's no telling whether the patch will be officially accepted, but others will appreciate and test your effort.<br />
<br />
==Q) Arch needs a stable package branch==<br />
'''A)'''<br />
Never say never.<br />
Some of the many discussions on the topic: <br><br />
http://bbs.archlinux.org/viewtopic.php?id=11288<br />
<br />
==Q) What's the difference between all these repositories?==<br />
'''A)''' See [[Official Repositories]].<br />
<br />
==Q) I just installed Package X. How do I start it?==<br />
'''A)''' If you're using a desktop environment like [[KDE]] or [[GNOME]], the program should automatically show up in your menu. If you're trying to run the program from a terminal and don't know the binary name, try executing {{Codeline|pacman -Ql packagename | grep bin}}. A common problem for packages like Firefox or OpenOffice is that they are installed to {{Filename|/opt}}, which is not in your <code>$PATH</code> - you can {{Codeline|source /etc/profile}} or relogin to fix this.<br />
<br />
==Q) Why is there only a single version of each shared library in the official repositories? ==<br />
'''A)''' Several distros, such as Debian, have different versions of shared libraries packaged as different packages: {{Codeline|libfoo1}}, {{Codeline|libfoo2}}, {{Codeline|libfoo3}} and so on. This way it is possible to have apps compiled against different versions of libfoo installed on the same system.<br />
<br />
Unlike Debian, Arch is a rolling-release cutting-edge distribution. The most visible trait of a cutting-edge distribution is availability of latest versions of software in the repositories; in case of Arch it also means that only the latest versions of all packages are officially supported. By dropping support for outdated software, package maintainers are able to spend more time to ensure that newest versions work as expected. As soon as a new version of a shared library becomes available from upstream, it's added to the repositories and affected packages are rebuilt to use the new version.<br />
<br />
==Q) What if I run {{Codeline|pacman -Syu}} and there will be an update for a shared library, but no updates for apps that depend on it? ==<br />
'''A)''' This scenario should not happen at all. Assuming an application called {{Codeline|foobaz}} is in one of the official repositories and builds successfully against a new version of a shared library called {{Codeline|libbaz}}, it will be updated along with {{Codeline|libbaz}}. If, however, it doesn't build successfully, {{Codeline|foobaz}} package will have a versioned dependency, e.g.<br />
libbaz=1.5<br />
and will be removed by pacman during {{Codeline|libbaz}} upgrade due to a conflict.<br />
<br />
If {{Codeline|foobaz}} is a package that you built yourself or installed from AUR, you should try rebuilding {{Codeline|foobaz}} against the new version of {{Codeline|libbaz}}. If the build fails, report the bug to the {{Codeline|foobaz}} developers.<br />
<br />
==Q) Is it possible that there will be a major kernel update in the repository, but some of the driver packages will not have been updated for the latest kernel?==<br />
'''A)''' No, it's not possible. Major kernel updates i.e. {{Codeline|2.6.x}} to {{Codeline|2.6.x+1}} are always accompanied by rebuilds of all supported kernel driver packages. On the other hand, if you have an unsupported package, such as {{Codeline|catalyst}}, installed on your system, then a kernel update might break things for you if you don't rebuild {{Codeline|catalyst}} for the latest kernel. Users are responsible for updating any unsupported packages that they have installed.<br />
<br />
=Installation=<br />
==Q) Arch needs a better installer. Maybe a GUI installer.==<br />
'''A)''' The discussion of a "better" installer is subjective. The best way to deal with these issues is to fit the installer to [[The Arch Way]]. If a suggestion for a better installer is backed with concrete arguments, it might be considered during future development of the installer. Since installation doesn't occur often (see the question above on rolling release), it is not a high priority for developers or users.<br />
However, two unofficial methods exist: [http://archie.dotsrc.org/ Archie Live CD] for [[Xfce|XFCE]] (other desktops in development) and [http://user-contributions.org/wikis/userwiki/index.php?title=Arch_Linux_Office_Install_CD Arch Linux Office Install CD] for KDE.<br />
{{Warning|Development of Archie and it's derivatives and firefly have ceased and they are now out of date. Please consider using [[archiso]] or [[larch]] [http://larch.berlios.de/].}}<br />
<br />
==Q) I installed Arch, and now I am at a bash login! What now?==<br />
'''A)''' Have a look at the Arch Linux [[Beginners' Guide]].<br />
<br />
==Q) Which DE/WM should I use?==<br />
'''A)''' Since many are available to you, use the one you like the most to fit your needs.<br />
<br />
==Q) What makes Arch unique amongst other "minimal" distributions?==<br />
'''A)''' A few distributions may provide minimal installation methods sharing some similar aspects to the Arch installation process. However, a few points must be noted:<br />
# Arch has been ''fundamentally designed'' as a lightweight, minimal base environment upon which to build. <br />
# Whether the Netinstall or Core images are used, the only way to install Arch is by building up from this minimal base.<br />
# The installation, the base system, as well as the entire distribution are inherently a K.I.S.S. design approach, which makes it uniquely suitable for its target base of users.<br />
# The simple Arch installer is designed for a high level of transparency and the base system is manually configured by the user to their needed specifications.<br />
# Arch provides thoroughly complete documentation to guide one through this process of system assembly.<br />
<br />
=Other=<br />
==Q) I get an error every time I use pacman saying 'warning: current locale is invalid; using default "C" locale'. What do I do?==<br />
'''A)''' As the error message says, your locale isn't correctly configured. Have a look at the [[Configuring locales|locale configuration wiki page]].<br />
<br />
==Q) How do I connect to my wireless network?==<br />
'''A)''' See [[Wireless Setup]].<br />
<br />
==Q) How do I connect to my wired network?==<br />
'''A)''' See [[Configuring Network]].<br />
<br />
==Q) What is this AUR thing I keep hearing about?==<br />
'''A)''' See [[Arch User Repository#FAQ]].<br />
<br />
==Q) Why do I get a green screen whenever I try to watch a video?==<br />
'''A)''' Your colour depth is set wrong. It may need to be 24 instead of 16, for example.<br />
<br />
==Q) Spellcheck is marking all of my text as incorrect!==<br />
'''A)''' Have you installed an aspell dictionary? Use {{Codeline|pacman -Ss aspell}} to see available dictionaries for downloading.<br />
<br />
If installing aspell dictionary files did not resolve the problem. It is most likely to be a problem with {{Codeline|enchant}}.<br />
<br />
Firstly, check what dictionary files aspell knows about using the command {{Codeline|aspell dicts}}:<br />
$ aspell dicts<br />
Prints out:<br />
en<br />
en_GB<br />
...etc<br />
<br />
If your respective language dictionary is listed, add the following line to {{Filename|/usr/share/enchant/enchant.ordering}}:<br />
language:aspell<br />
en_GB:aspell # Example</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Frequently_asked_questions&diff=101535Frequently asked questions2010-03-30T10:36:43Z<p>Bhobbit: 3 new q&a in package management section</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:FAQs (English)]]<br />
{{i18n|FAQ}}<br />
<br />
Besides the questions covered below, you may find [[The Arch Way]] and [[Arch Linux]] helpful. Both of the articles contain a good deal of information about Arch Linux.<br />
<br />
= General =<br />
==Q) What is Arch Linux? ==<br />
'''A)''' From the article entitled [[Arch Linux]]:<br />
<br />
''Arch Linux is an independently developed i686/x86-64 community distribution, based on a rolling-release model and targeted at competent GNU/Linux users which offers large binary repositories and excellent package management as well as a ports-like packaging system. Development focuses on a balance of minimalism, elegance, code correctness and modernity. Version 0.1 (Homer) was released March 11, 2002.''<br />
<br />
==Q) Why would I want to use Arch? ==<br />
'''A)''' If you have read, and agree with [[The Arch Way]] philosophy, embrace the 'do-it-yourself' approach and require or desire a simple, elegant, highly customizable, bleeding edge, general purpose GNU/Linux distribution, chances are you may like Arch.<br />
<br />
==Q) Why wouldn't I want to use Arch?==<br />
'''A)''' If you have read, and disagree with [[The Arch Way]] philosophy, and do not have the ability/time/desire for a 'do-it-yourself' GNU/Linux distribution, chances are Arch may not be for you.<br />
<br />
You may also not want to use Arch if:<br />
* you require support for an architecture other than x86_64 or i686.<br />
* you take a strong stand on using a distribution which only provides free software as defined by GNU.<br />
* you believe an operating system should configure itself, run out of the box, and include a complete default set of software and desktop environment on the installation media.<br />
* you do not want a bleeding edge, rolling release GNU/Linux distribution.<br />
* you are happy with your current OS of choice.<br />
* you want an OS with a different goal targeted at a different userbase.<br />
<br />
==Q) What distro is Arch based on? ==<br />
'''A)''' Arch is independently developed, was built from scratch and is not based on any other GNU/Linux distribution. Before creating Arch, Judd Vinet admired and used <code>CRUX</code>, a great, minimalist distro created by Per Lidén. Originally inspired by ideas in common with <code>CRUX</code>, Arch was built from scratch, and pacman was then coded in C.<br />
<br />
==Q) I am a complete GNU/Linux beginner. Should I use Arch?==<br />
'''A)''' This question has had much debate. Arch is targeted at more-advanced GNU/Linux users, but some people feel "Arch is a good place to start". If you are a beginner and want to use Arch, just be warned that you must be willing to learn as well as accept the fact that Arch is largely a do-it-yourself distribution. It is the user who assembles the system, and controls what it will be. Before asking any question, do your own independent research by googling, searching the Wiki, and searching the forum (and reading past FAQs). If you do that, you should be fine. Also know that many people do not want to answer the same basic questions over and over, so you are exposing yourself to that environment. ''There is a reason these resources were created/made available to you in the first place.'' Many thousands of ''volunteered'' hours have been spent compiling this excellent information.<br />
<br />
Recommended reading: The Arch Linux [[Beginners Guide|Beginners' Guide]].<br />
<br />
==Q) Is Arch designed to be used as a server? A desktop? A workstation?==<br />
'''A)''' Arch is not designed for any particular type of use. Rather, it is designed for a particular type of ''user''. Arch targets competent users who enjoy its do-it-yourself nature, and who further exploit it to shape the system to fit their unique needs. Therefore, in the hands of its target user base, Arch can be used for virtually any purpose. Many use Arch on both their desktops and workstations. And of course, archlinux.org runs on Arch.<br />
<br />
==Q) I really like Arch, except the development team needs to implement ''"feature X"''.==<br />
'''A)''' Before going further, did you read [[The Arch Way]]? Have you provided the feature/solution? Does it conform to the Arch philosophy of ''minimalism'' and ''code-correctness over convenience''? Get involved, contribute your code/solution to the community. If it is well regarded by the community and development team, perhaps it will be merged. The Arch community thrives on contribution and sharing of code and tools.<br />
<br />
==Q) When will the new release be made?==<br />
'''A)''' Arch Linux releases are merely a snapshot of the /core repository, combined with various features or modifications to the installer script itself. The rolling release model keeps every Arch Linux system current and on the bleeding edge by issuing one command.<br />
<br />
For this reason, releases are not terribly important in Arch, because the rolling-release system makes new releases out of date as soon as a package has been updated. If you are looking to obtain the latest Arch Linux release, you do not need to reinstall. You simply run the {{Codeline|pacman -Syu}} command and your system will be identical to what you would get with a brand-new install.<br />
<br />
For this same reason, new Arch Linux releases are not typically full of new and exciting features. New and exciting features are released as needed with the packages that are updated, and can be obtained immediately via {{Codeline|pacman -Syu}}.<br />
<br />
==Q) Is Arch Linux a stable distro? Will I get frequent breakage? ==<br />
'''A)''' The long and short answer is: It is largely as stable as ''you'' make it. <br />
<br />
''You'' assemble your own Arch system, atop the simple base environment, and ''you'' control system upgrades. (Obviously, a larger, more bloated system incorporating multitudes of packages, multiple toolkits and desktop environments would be more likely to experience configuration issues due to upstream changes than a slimmer, more simple system would.) Arch is targeted at capable, proactive users. General UNIX competence and good system maintenance and upgrade practices also play a large role in system stability. Also recall that Arch packages are predominantly unpatched, so most application issues are inherently upstream.<br />
<br />
Therefore, it is ''the user'' who is ultimately responsible for the stability of his own rolling release system. The user decides when to upgrade, and merges necessary changes when required. If the the user reaches out to the community for help, it is often provided in a timely manner. The difference between Arch and other distributions in this regard is that Arch is truly a 'do-it-yourself' distro; complaints of breakage are misguided and unproductive, since upstream changes are not the responsibility of Arch devs.<br />
<br />
==Q) What exactly ''is'' this 'BSD-style' init framework I keep hearing about? ==<br />
Part of BSD's heritage is the simple init framework that it has incorporated. The main difference between a BSD init and a sysV init is that Arch's BSD-style init uses a single line in a single file, {{Filename|/etc/rc.conf}}, to point to scripts within a single directory, {{Filename|etc/rc.d/}}, for all system services, regardless of runlevel.<br />
<br />
A SysV init, on the other hand, would use a system of multiple directories (usually 7 by default), one for each runlevel: {{Filename|/etc/rc.0,1,2,3,4,5,6}}. Each directory contains a gratuitous number of symlinks; one for each service. Each symlink points to a corresponding script in the {{Filename|/etc/init.d/}} directory. Needless to say, the SysV method is more complex, as by default dozens of symlinks reside under each {{Filename|/etc/rc.0,1,2,3,4,5,6}} directory in addition to all the scripts under {{Filename|/etc/init.d/}}. Keeping in line with its simple philosophy, Arch uses the BSD-style init.<br />
<br />
==Q) Arch needs more press (i.e. advertisement)==<br />
'''A)''' Arch gets plenty of press as it is. The goal of Arch Linux is not to be large, but rather, to provide an elegant, minimalist and bleeding edge distribution focused on simplicity and code-correctness. Organic, sustainable growth occurs naturally amongst the target user base.<br />
<br />
==Q) Arch needs more devs==<br />
'''A)''' Possibly so. Feel free to volunteer your time! Visit the [http://bbd.archlinux.org forums], [http://www.archlinux.org/irc/ IRC channels], and [http://mailman.archlinux.org/mailman/listinfo/ mailing lists], and see what needs to be done. Getting involved in the Community Contributions subforum is a good way to start.<br />
<br />
==Q) Why is Arch so slow? Programs open slowly or do not run at all!==<br />
'''A)''' Make sure that your hostname is correctly set in {{Filename|/etc/hosts}} (i.e., that it matches the hostname in {{Filename|/etc/rc.conf}}. Have a look at "Configure the System" in The [[Beginners_Guide#F:_Configure_the_System|Beginners' Guide]]). If the hostnames do not match, applications may start up very slowly.<br />
<br />
==Q) Why is my internet so slow compared to other operating systems?==<br />
'''A)''' Is your network configured correctly? Have you double checked your {{Filename|/etc/rc.conf}} {{Filename|/etc/hosts}} and {{Filename|/etc/resolv.conf}}? Have a look at "Configure the System" in The [[Beginners_Guide#F:_Configure_the_System|Beginners' Guide]].<br />
<br />
==Q) Why is Arch using all my RAM? 2G used while I'm just staring at my desktop?==<br />
'''A)''' Essentially, unused RAM is wasted RAM. <br />
<br />
Many new users notice how the Linux kernel handles memory differently than they are used to. Since accessing data in RAM is much faster than from disk, the kernel caches recently accessed data in memory. The cached data is only cleared when the system begins to run out of unused memory and new data still needs to be loaded.<br />
<br />
Perhaps the most common culprit of this confusion is the {{Codeline|free}} command:<br />
<br />
{{Command|name=free -m|output=$ free -m<br />
total used free shared buffers cached<br />
Mem: 1009 741 267 0 104 359<br />
-/+ buffers/cache: 278 731 <-- NOTE THIS!<br />
Swap: 1537 0 1537}}<br />
<br />
It is important to note the {{Codeline|-/+ buffers/cache:}} line -- a representation of the amount of memory that is actually in "active use" and the amount of "available" memory, rather than "unused".<br />
<br />
In the above example, a laptop with 1G of total RAM appears to be using 741M of it, with naught but a few idling terminals and web browser open! However, upon examining the emphasized line, see that only 278M of it is in "active use", and in fact 731M is "available" for new data. Apparently, 104M of that "used" memory contains buffered data and 359M contains cached data, both of which can be cleared away if needed. Only 267M of the total is truly "free" of the burden of data storage.<br />
<br />
The result of all this? Performance!<br />
<br />
See [http://www.linuxjournal.com/article/2770 this wonderful article] if your curiosity has been piqued!<br />
<br />
=Package Management=<br />
==Q) I've found an error with Package X. What should I do?==<br />
'''A)''' First, you need to figure out if this error is something the Arch team can fix. Sometimes it's not (that Firefox crash may be the fault of the Mozilla team) - this is called an ''upstream error''. If it is an Arch problem, there is a series of steps you can take:<br />
#Search the forums for information. See if anyone else has noticed it.<br />
#Notify the package maintainer. Try a {{Codeline|pacman -Qi}} for this info.<br />
#Post a [[Reporting Bug Guidelines|bug report]] with detailed information at http://bugs.archlinux.org.<br />
#If you'd like, write a forum post detailing the problem and the fact that you have reported it already. This will help prevent a lot of people from reporting the same error.<br />
<br />
==Q) Will Arch have a database for pacman?==<br />
'''A)''' Possibly. There is discussion over the issue. <br><br />
http://bbs.archlinux.org/viewtopic.php?id=11193 <br><br />
http://bbs.archlinux.org/viewtopic.php?id=10898 <br><br />
Look at http://bugs.archlinux.org/task/5328, too.<br />
<br />
==Q) Arch packages need to use a unique naming convention. .pkg.tar.gz and .pkg.tar.xz are too long and/or confusing==<br />
'''A)''' This has been discussed on the Arch mailing list. Some proposed a .pac file extension. As far as is currently known, there is no plan to change the package extension.<br />
As Tobias Kieslich, one of the Arch devs, put it, "A package '''is''' a gzipped [xz] tarball! And it can be opened, investigated and manipulated by any tar-capable application. Moreover, the mime-type is automatically detected correctly by most applications."<br />
<br />
==Q) Pacman needs a library so other applications can easily access package information==<br />
'''A)''' Since version 3.0.0, pacman has been the front-end to libalpm, the "Arch Linux Package Management" library. This library allows alternative front-ends to be written (for instance, a GUI front-end).<br />
<br />
==Q) Why doesn't Pacman have an official GUI front-end?==<br />
'''A)''' Please read [[The Arch Way]] and [[Arch Linux]]. The answer is basically that the Arch dev team will not be providing one. Feel free to use one of those developed by users. There is a nice list of them on the [[UserContributionsPage]] in the links section, and a selective list on [[Pacman GUI Frontends]].<br />
<br />
==Q) Pacman needs ''"feature X!"''==<br />
'''A)''' Please read [[The Arch Way]] and [[Arch Linux]]. The Arch philosophy is "Keep It Simple". If you think the idea has merit, and does not violate this simple litany, then by all means, discuss it on the forum [http://bbs.archlinux.org/ here]. You might also like to check [http://bugs.archlinux.org here]; it's a place for feature requests if you find it is important.<br />
<br />
However, the best way to get a feature added to Pacman or Arch Linux is to implement it yourself. There's no telling whether the patch will be officially accepted, but others will appreciate and test your effort.<br />
<br />
==Q) Arch needs a stable package branch==<br />
'''A)'''<br />
Never say never.<br />
Some of the many discussions on the topic: <br><br />
http://bbs.archlinux.org/viewtopic.php?id=11288<br />
<br />
==Q) What's the difference between all these repositories?==<br />
'''A)''' See [[Official Repositories]].<br />
<br />
==Q) I just installed Package X. How do I start it?==<br />
'''A)''' If you're using a desktop environment like [[KDE]] or [[GNOME]], the program should automatically show up in your menu. If you're trying to run the program from a terminal and don't know the binary name, try executing {{Codeline|pacman -Ql packagename | grep bin}}. A common problem for packages like Firefox or OpenOffice is that they are installed to {{Filename|/opt}}, which is not in your <code>$PATH</code> - you can {{Codeline|source /etc/profile}} or relogin to fix this.<br />
<br />
==Q) Why is there only a single version of each shared library in the official repositories? ==<br />
'''A)''' Several distros, such as Debian, have different versions of shared libraries packaged as different packages: {{Codeline|libfoo1}}, {{Codeline|libfoo2}}, {{Codeline|libfoo3}} and so on. This way it is possible to have apps compiled against different versions of libfoo installed on the same system.<br />
<br />
Unlike Debian, Arch is a rolling-release cutting-edge distribution. The most visible trait of a cutting-edge distribution is availability of latest versions of software in the repositories; in case of Arch it also means that only the latest versions of all packages are officially supported. By dropping support for outdated software, package maintainers are able to spend more time to ensure that newest versions work as expected. As soon as a new version of a shared library becomes available from upstream, it's added to the repositories and affected packages are rebuilt to use the new version.<br />
<br />
==Q) What if I run {{Codeline|pacman -Syu}} and there will be an update for a shared library, but no updates for apps that depend on it? ==<br />
'''A)''' This scenario should not happen at all. Assuming an application called {{Codeline|foobaz}} is in one of the official repositories and builds successfully against a new version of a shared library called {{Codeline|libbaz}}, it will be updated along with {{Codeline|libbaz}}. If, however, it doesn't build successfully, {{Codeline|foobaz}} package will have a versioned dependency, e.g.<br />
libbaz=1.5<br />
and will be removed by pacman during {{Codeline|libbaz}} upgrade due to a conflict.<br />
<br />
If {{Codeline|foobaz}} is a package that you built yourself or installed from AUR, you should try rebuilding {{Codeline|foobaz}} against the new version of {{Codeline|libbaz}}. If the build fails, report the bug to the {{Codeline|foobaz}} developers.<br />
<br />
==Q) If Arch is a bleeding edge distro, is it possible that there will be a major kernel update in the repository, but some of the kernel driver packages will not have been updated for the latest kernel?==<br />
'''A)''' No, it's not possible. Major kernel updates i.e. {{Codeline|2.6.x}} to {{Codeline|2.6.x+1}} are always accompanied by rebuilds of all supported kernel driver packages. On the other hand, if you have an unsupported package, such as {{Codeline|catalyst}}, installed on your system, then a kernel update might break things for you if you don't rebuild {{Codeline|catalyst}} for the latest kernel. Users are responsible for updating any unsupported packages that they have installed.<br />
<br />
=Installation=<br />
==Q) Arch needs a better installer. Maybe a GUI installer.==<br />
'''A)''' The discussion of a "better" installer is subjective. The best way to deal with these issues is to fit the installer to [[The Arch Way]]. If a suggestion for a better installer is backed with concrete arguments, it might be considered during future development of the installer. Since installation doesn't occur often (see the question above on rolling release), it is not a high priority for developers or users.<br />
However, two unofficial methods exist: [http://archie.dotsrc.org/ Archie Live CD] for [[Xfce|XFCE]] (other desktops in development) and [http://user-contributions.org/wikis/userwiki/index.php?title=Arch_Linux_Office_Install_CD Arch Linux Office Install CD] for KDE.<br />
{{Warning|Development of Archie and it's derivatives and firefly have ceased and they are now out of date. Please consider using [[archiso]] or [[larch]] [http://larch.berlios.de/].}}<br />
<br />
==Q) I installed Arch, and now I am at a bash login! What now?==<br />
'''A)''' Have a look at the Arch Linux [[Beginners' Guide]].<br />
<br />
==Q) Which DE/WM should I use?==<br />
'''A)''' Since many are available to you, use the one you like the most to fit your needs.<br />
<br />
==Q) What makes Arch unique amongst other "minimal" distributions?==<br />
'''A)''' A few distributions may provide minimal installation methods sharing some similar aspects to the Arch installation process. However, a few points must be noted:<br />
# Arch has been ''fundamentally designed'' as a lightweight, minimal base environment upon which to build. <br />
# Whether the Netinstall or Core images are used, the only way to install Arch is by building up from this minimal base.<br />
# The installation, the base system, as well as the entire distribution are inherently a K.I.S.S. design approach, which makes it uniquely suitable for its target base of users.<br />
# The simple Arch installer is designed for a high level of transparency and the base system is manually configured by the user to their needed specifications.<br />
# Arch provides thoroughly complete documentation to guide one through this process of system assembly.<br />
<br />
=Other=<br />
==Q) I get an error every time I use pacman saying 'warning: current locale is invalid; using default "C" locale'. What do I do?==<br />
'''A)''' As the error message says, your locale isn't correctly configured. Have a look at the [[Configuring locales|locale configuration wiki page]].<br />
<br />
==Q) How do I connect to my wireless network?==<br />
'''A)''' See [[Wireless Setup]].<br />
<br />
==Q) How do I connect to my wired network?==<br />
'''A)''' See [[Configuring Network]].<br />
<br />
==Q) What is this AUR thing I keep hearing about?==<br />
'''A)''' See [[Arch User Repository#FAQ]].<br />
<br />
==Q) Why do I get a green screen whenever I try to watch a video?==<br />
'''A)''' Your colour depth is set wrong. It may need to be 24 instead of 16, for example.<br />
<br />
==Q) Spellcheck is marking all of my text as incorrect!==<br />
'''A)''' Have you installed an aspell dictionary? Use {{Codeline|pacman -Ss aspell}} to see available dictionaries for downloading.<br />
<br />
If installing aspell dictionary files did not resolve the problem. It is most likely to be a problem with {{Codeline|enchant}}.<br />
<br />
Firstly, check what dictionary files aspell knows about using the command {{Codeline|aspell dicts}}:<br />
$ aspell dicts<br />
Prints out:<br />
en<br />
en_GB<br />
...etc<br />
<br />
If your respective language dictionary is listed, add the following line to {{Filename|/usr/share/enchant/enchant.ordering}}:<br />
language:aspell<br />
en_GB:aspell # Example</div>Bhobbithttps://wiki.archlinux.org/index.php?title=DVD_Playing&diff=100124DVD Playing2010-03-15T05:40:27Z<p>Bhobbit: Expanded tip about optical group</p>
<hr />
<div>[[Category:Audio/Video (English)]]<br />
{{i18n|DVD Playing}}<br />
{{Article summary start}}<br />
{{Article summary text|An introduction to playing DVD-Video.}}<br />
{{Article summary heading|Series}}<br />
{{Article summary wiki|DVD Playing}}<br />
{{Article summary wiki|DVD Ripping}}<br />
{{Article summary wiki|DVD Writing}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Codecs}}<br />
{{Article summary wiki|MPlayer}}<br />
{{Article summary end}}<br />
<br />
DVD, also known as Digital Versatile Disc or Digital Video Disc, is an optical disc storage media format used for video and data storage.[http://en.wikipedia.org/wiki/DVD]<br />
<br />
==Requirements==<br />
If you wish to play encrypted DVDs, you must install the libdvd* packages.<br />
# pacman -S libdvdread libdvdcss libdvdnav<br />
<br />
Additionally, you must install player software. Popular DVD players are [[MPlayer]], [[Wikipedia:Xine|xine]] and [[Wikipedia:VLC|VLC]]. xine and VLC support DVD menus.<br />
<br />
{{Tip|Users may need to belong to the [[Groups|'optical' group]] to be able to access the DVD drive:<br />
# gpasswd -a USERNAME optical<br />
Don't forget to re-login the user for the changes to take effect. You can see your user's current groups with {{codeline|groups}} command.<br />
}}<br />
<br />
==DVD players==<br />
See also: [[Common Applications#Video]]<br />
<br />
===MPlayer===<br />
[[MPlayer]] is efficient and supports a wide variety of media formats (i.e. almost everything). To play a DVD with MPlayer:<br />
$ mplayer dvd://N<br />
<br />
...where N is the desired chapter number. Start at 1 and work up if unsure.<br />
<br />
To play a DVD image file:<br />
$ mplayer -dvd-device movie.iso dvd://N<br />
<br />
To find the audio language, start MPlayer with the {{Codeline|-v}} switch to output audio IDs. An audio track is selected with {{Codeline|-aid <audio_id>}}. Set a default audio language by editing {{Filename|~/.mplayer/config}} and adding the line {{Codeline|1=alang=en}} for English. <br />
<br />
With MPlayer, the DVD could be set to a low volume. To increase the maximum volume to 400% use {{Codeline|1=softvol=yes}} and {{Codeline|1=softvol-max=400}}. The startup volume defaults to 100% of software volume and the global mixer levels will remain untouched. Using the 9 and 0 keys, volume can be adjusted between 0 and 400 percent.<br />
alang=en<br />
softvol=yes<br />
softvol-max=400<br />
<br />
[http://www.mplayerhq.hu/ MPlayer home page]<br />
<br />
===VLC===<br />
A capable player with a simple GUI, installed with:<br />
# pacman -S vlc<br />
<br />
[http://www.videolan.org/vlc VLC home page]<br />
<br />
{{Tip|1=To make VLC the default DVD player in GNOME, edit {{Filename|/usr/share/applications/vlc.desktop}} and at the bottom of the file add:<br />
MimeType=video/dv;video/mpeg;video/x-mpeg;video/msvideo;video/quicktime;video/x-anim;video/x-avi;video/x-ms-asf;video/x-ms-wmv;video/x-msvideo;video/x-nsv;video/x-flc;video/x-fli;application/ogg;application/x-ogg;application/x-matroska;audio/x-mp3;audio/x-mpeg;audio/mpeg;audio/x-wav;audio/x-mpegurl;audio/x-scpls;audio/x-m4a;audio/x-ms-asf;audio/x-ms-asx;audio/x-ms-wax;application/vnd.rn-realmedia;audio/x-real-audio;audio/x-pn-realaudio;application/x-flac;audio/x-flac;application/x-shockwave-flash;misc/ultravox;audio/vnd.rn-realaudio;audio/x-pn-aiff;audio/x-pn-au;audio/x-pn-wav;audio/x-pn-windows-acm;image/vnd.rn-realpix;video/vnd.rn-realvideo;audio/x-pn-realaudio-plugin;application/x-extension-mp4;audio/mp4;video/mp4;video/mp4v-es;x-content/video-vcd;x-content/video-svcd;x-content/video-dvd;x-content/audio-cdda;x-content/audio-player;<br />
<br />
Then, as root, run:<br />
# update-desktop-database /usr/share/applications<br />
<br />
Finally, open '''System > Preferences >> File Management >>> Media''' and next to '''DVD Video''' select '''Open VLC media player'''.}}<br />
<br />
===xine===<br />
A lightweight media player supporting DVD menus.<br />
<br />
[http://www.xine-project.org/ xine home page]</div>Bhobbithttps://wiki.archlinux.org/index.php?title=CUPS&diff=100067CUPS2010-03-14T04:53:47Z<p>Bhobbit: moved tip to the end of the section for readability; note on usb printers</p>
<hr />
<div>[[Category:Printers (English)]][[Category:HOWTOs (English)]]<br />
{{i18n|CUPS}}<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Installing and configuring CUPS}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|CUPS printer sharing}}<br />
{{Article summary wiki|CUPS printer-specific problems}}<br />
{{Article summary wiki|Samba}}<br />
{{Article summary end}}<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''CUPS is the standards-based, open source printing system developed by Apple Inc. for Mac OS® X and other UNIX®-like operating systems.''"<br />
Although there are other printing packages such as LPRNG, the ''C''ommon ''U''nix ''P''rinting ''S''ystem is the most popular choice because of its relative ease of use.<br />
<br />
==Installing==<br />
These packages are needed:<br />
# pacman -S cups ghostscript gsfonts<br />
<br />
* '''cups''' - The actual CUPS software<br />
* '''ghostscript''' - Interpreter for the Postscript language<br />
* '''gsfonts''' - GhostScript standard Type1 fonts<br />
* '''hal-cups-utils''' - This package might be needed. Read [http://bbs.archlinux.org/viewtopic.php?pid=655391#p655391 this forum post] for more information<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install Samba:<br />
# pacman -S samba<br />
<br />
===Printer driver===<br />
Here are some of the driver packages. Choosing the right driver depends on the printer:<br />
<br />
* '''gutenprint''' - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostSscript, CUPS, Foomatic, and the [[GIMP]]<br />
* '''foomatic-db, foomatic-db-engine, foomatic-db-nonfree, and foomatic-filters''' - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix. Installing foomatic-filters should solve problems if the cups error_log is reporting "stopped with status 22!".<br />
* '''hplip''' - HP GNU/Linux inkjet driver. Provides support for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models<br />
* '''splix''' - Samsung drivers for SPL (Samsung Printer Language) printers<br />
* '''ufr2''' - Canon UFR2 driver with support for LBP, iR and MF series printers. Package is available in the [[AUR]].<br />
* '''cups-pdf''' - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
<br />
If unsure of what driver package to install or if the current driver is not working, it may be easiest to just install all of drivers, since some of the packages are misleading because printers of other makes may rely on them. For instance, the Brother HL-2140 needs the hplip driver installed.<br />
# pacman -S gutenprint foomatic-db foomatic-db-engine \<br />
foomatic-db-nonfree foomatic-filters \<br />
hplip splix ufr2 cups-pdf<br />
<br />
====Download printer PPD====<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.linuxprinting.org/printer_list.cgi OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{Filename|/usr/share/cups/model/}}}}<br />
<br />
==Configuring==<br />
Now that CUPS is installed, there are a variety of options on how to setup printing solutions. As always, the tried and true command line method is at disposal. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. However, in order to make this process easy for the largest amount of users, this article will focus on the web interface provided by CUPS.<br />
<br />
If you are planning on connecting to a network printer, rather than one that is directly connected to the computer, you might want to read the [[CUPS printer sharing]] page first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
===Kernel modules===<br />
Before using the CUPS web interface, the appropriate kernel modules need to be installed. The following steps are from the Gentoo Printing Guide.<br />
<br />
This section may not be necessary, however, depending on which kernel is being used. The kernel module may load automatically after plugging in the printer. Use the {{Codeline|tail}} command (described below) to see if the printer has already been detected. The {{Codeline|lsmod}} utility can also be used to see what modules have been loaded.<br />
<br />
====USB printers====<br />
USB printer users may need to blacklist the {{codeline|usblp}} module. Keep in mind that there seems to be a lot of [http://bbs.archlinux.org/viewtopic.php?pid=660601 uncertainty] regarding blacklisting {{codeline|usblp}}, as some USB printers, including some Canon printer series, are not recognized without it. To disable the module, edit {{filename|rc.conf}} as shown:<br />
<br />
{{File|name=/etc/rc.conf|content=MODULES=(... '''!usblp''' ...)}}<br />
<br />
Custom kernel users may need to manually load the {{codeline|usbcore}} module before proceeding:<br />
# modprobe usbcore<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
If you're using {{codeline|usblp}}, the output should indicate that the printer has been detected like so:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
If you blacklisted {{codeline|usblp}}, you will see something like:<br />
usb 3-2: new full speed USB device using uhci_hcd and address 3<br />
usb 3-2: configuration #1 chosen from 1 choice<br />
<br />
====Parallel port printers====<br />
If planning on using a parallel port printer, note that the configuration is pretty much the same, except for the modules:<br />
# modprobe lp<br />
# modprobe parport<br />
# modprobe parport_pc<br />
<br />
Once again, check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
====Auto-loading====<br />
It's convenient to have the system automatically load the kernel module every time the it starts up. To do so, use a text editor to open up {{Filename|/etc/[[rc.conf]]}} and add the appropriate module to the <code>MODULES=()</code> line. Here is an example:<br />
MODULES=(!usbserial scsi_mod sd_mod snd-ymfpci snd-pcm-oss '''lp parport parport_pc''' ide-scsi)<br />
<br />
===CUPS daemon===<br />
With the kernel modules installed, the system is now ready to start the actual CUPS daemon. To do this, simply run this command:<br />
# /etc/rc.d/cups start<br />
<br />
For automatically starting CUPS every time the system is powered on, add it to the <code>DAEMONS=()</code> line in the {{Filename|/etc/rc.conf}} file. For example:<br />
DAEMONS=(pcmcia syslogd klogd !fam esd mono network autofs '''cups''' crond gdm)<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{Filename|/etc/hosts}}).<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a user-name and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label ( e.g., next to ''USB Printer #1'' for USB printers). Finally, chose the appropriate drivers and the configuration is complete.<br />
<br />
Now, test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
{{Tip|[[GNOME]] users may be inclined towards installing the GNOME CUPS manager GUI frontend. See: [[#Alternative CUPS interfaces]]}}<br />
{{Note|When setting up a USB printer, you should see your printer listed on ''Add Printer'' page. If you can only see a "SCSI printer" option, it probably means that CUPS has failed to recognize your printer.}}<br />
<br />
==== CUPS administration ====<br />
<br />
A user-name and password will be required when administrating the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default user-name is the one assigned in the ''sys'' group, or root (change this by editing {{Filename|/etc/cups/cupsd.conf}} in the line of ''SystemGroup''). <br />
<br />
If the root account has been locked, it is not possible to log in the CUPS administration interface with the default user-name and password. In this case, it may be needed to change the default SystemGroup in cupsd.conf and read [http://bbs.archlinux.org/viewtopic.php?id=35567 this post].<br />
<br />
====Remote access to web interface====<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{Filename|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
There are three levels of access that can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{codeline|Allow}} statement to that level's section. An {{codeline|Allow}} statement can take one or more of the forms listed below:<br />
Allow all<br />
Allow host.domain.com<br />
Allow *.domain.com<br />
Allow ip-address<br />
Allow ip-address/netmask<br />
<br />
Deny statements can also be used. For example, if wanting to give all hosts on the 192.168.1.0/255.255.255.0 subnet full access, file {{Filename|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
# Encryption disabled by default<br />
#Encryption Required<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
==Troubleshooting==<br />
The best way to get printing working is to set 'LogLevel' in {{Filename|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{Filename|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{Filename|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{Filename|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{Filename|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
===Problems resulting from upgrades===<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
====CUPS stops working====<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" my result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy /etc/cups/cupsd.conf.default to /etc/cups/cupsd.conf (backup the old the configuration if needed):<br />
# cp /etc/cups/cupsd.conf.default /etc/cups/cupsd.conf<br />
and restart CUPS to employ the new settings.<br />
<br />
====Error with gnutls====<br />
If receiving errors such as:<br />
/usr/sbin/cupsd: error while loading shared libraries: libgnutls.so.13: cannot open shared object file: No such file or directory<br />
gnutls may be in need of updating:<br />
# pacman -S gnutls<br />
<br />
After updating, there may be a file named {{Filename|cupsd.conf.pacnew}} in {{Filename|/etc/cups}}. This is the unmodified original configuration file that has been placed as part of the update. Compare it with the currently installed version and adjust to preference.<br />
<br />
====All jobs are "stopped"====<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
====The PPD version is not compatible with gutenprint====<br />
Run:<br />
# /usr/sbin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
===USB printers under CUPS 1.4.x===<br />
New CUPS 1.4.x introduces many changes:<br />
<br />
====Configuration file====<br />
The syntax of the configuration file cupsd.conf changed. Start with a new cupsd.conf file based on /etc/cups/cupsd.conf.default.<br />
<br />
====Blacklisting usblp====<br />
CUPS now uses libusb and printer USB devices (under /dev/bus/usb/) instead of the usblp generated /dev/usb/lpX ones. In order to get USB printers working, the usblp module needs disabling. This can be done by blacklisting it in /etc/rc.conf, or by adding "blacklist usblp" to a configuration file in /etc/modprobe.d. Some users have also reported that they needed to reinstall their printer.<br />
<br />
====Device node permissions====<br />
In addition to usblp not being loaded, CUPS also needs the ownership of the USB device file of the printer to be root:lp, and permissions to be 660. E.g.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
This is supposed to be achieved by two udev rules in /lib/udev/rules.d/50-udev-default.rules:<br />
# hplip and cups 1.4+ use raw USB devices, so permissions should be similar to<br />
# the ones from the old usblp kernel module<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}=="", IMPORT{program}="usb_id --export %p"<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}==":0701*:", GROUP="lp", MODE="660"<br />
<br />
However, for some devices, in particular combined printer/scanner devices, these rules either do not trigger, or are overwritten by rules of the 'sane' package. In these cases a custom udev rule needs to be added. See below.<br />
<br />
=====Device node permission troubleshooting=====<br />
Get the printer's device file and its permissions with: <br />
$ lsusb<br />
...<br />
Bus 003 Device 002: ID 04b8:0841 Seiko Epson Corp.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
If the permissions are not already root:lp 660, enforce it by creating a custom udev rule, e.g<br />
cat /etc/udev/rules.d/10-usbprinter.rules<br />
ATTR{idVendor}=="04b8", ATTR{idProduct}=="0841", MODE:="0660", GROUP:="lp"<br />
<br />
Note that idVendor and idProduct are from the lsusb listing above.<br />
<br />
=====Loading firmware=====<br />
<br />
Some printers and drivers need to load firmware to the printer (such as HP LaserJet 10xx printers using foo2zjs) and do this by writing directly to the lp device, a functionality provided by usblp. A work around until this issue is resolved is to install the usblp module until the firmware is loaded, then remove the module to allow CUPS to work. This can be accomplished by manually running "$ modprobe usblp", waiting for the firmware to load, then "$ rmmod usblp". You can also not blacklist usblp, then put "rmmod usblp" to /etc/rc.local, allowing the firmware to be loaded on boot before rc.local is run, then removing usblp.<br />
<br />
===Other===<br />
<br />
=====CUPS permission errors=====<br />
*Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
*Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
====HPLIP printer sends "/usr/lib/cups/backend/hp failed" error====<br />
Make sure dbus is installed and running, e.g. check DAEMONS in {{Filename|/etc/rc.conf}} or run {{Codeline|ls /var/run/daemons}}.<br />
<br />
====hp-toolbox sends an error, "Unable to communicate with device"====<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/<printer id><br />
or, "{{Codeline|Unable to communicate with device"}}", then it may be needed to add the user to the lp group by running the following command:<br />
# gpasswd -a <username> lp<br />
<br />
====CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer====<br />
If receiving any of the following error messages in {{Filename|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer "<printer_name>" not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure '''hplip''' has been installed, in addition to [[#Packages|the packages mentioned above]], '''net-snmp''' is also needed. See [http://bbs.archlinux.org/viewtopic.php?id=65615 this forum post].<br />
# pacman -S hplip<br />
<br />
====Printing fails with unauthorised error====<br />
If the user has been added to the lp group, and allowed to print (set in {{Filename|cups.conf}}), then the problem lies in {{Filename|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
====Print button greyed-out in GNOME print dialogs====<br />
:''<small>Source: [http://bbs.archlinux.org/viewtopic.php?id=70418 I can't print from gnome applications. - Arch Forums]</small>''<br />
<br />
Be sure the package: '''libgnomeprint''' is installed<br />
<br />
Edit {{filename|/etc/cups/cupsd.conf}} and add<br />
# HostNameLookups Double<br />
<br />
Restart CUPS:<br />
# /etc/rc.d/cups restart<br />
<br />
====CUPS fails to print with 'Unable to open device "hal:///[...]": Permission denied'====<br />
The permissions on some files are wrong:<br />
# cd /usr/lib/cups/backend<br />
# chmod 700 hal # (previously 755)<br />
# chmod 700 usb # (previously 755)<br />
<br />
====Unknown supported format: application/postscript====<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{Filename|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{Filename|/etc/cups/mime.types}}.<br />
<br />
====Finding URIs for Windows Print Servers====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
<pre> WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series</pre><br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
<br />
==Appendix==<br />
<br />
===Alternative CUPS interfaces===<br />
If using [[GNOME]], a possibility is to manage and configure the printer by using the gnome-cups-manager. This package is available through pacman: <br />
# pacman -S gnome-cups-manager<br />
<br />
Alternatively, system-config-printer-gnome can be installed:<br />
# pacman -S system-config-printer-gnome<br />
<br />
For system-config-printer to work as it should, running as root may be required, or alternatively set up a "normal" user to administer CUPS (if so '''follow steps 1-3''')<br />
<br />
* 1. Create group, and add a user<br />
# groupadd lpadmin<br />
# usermod -aG lpadmin <username><br />
<br />
* 2. Add "lpadmin" (without the quotes) to this line in {{Filename|/etc/cups/cupsd.conf}}<br />
SystemGroup sys root <insert here><br />
<br />
* 3. Restart cups, log out and in again (or restart computer)<br />
# /etc/rc.d/cups restart<br />
<br />
[[KDE]] users can modify their printers from the Control Center. Both should refer to those desktop environments' documentation for more information on how to use the interfaces.<br />
<br />
There is also gtklp:<br />
# pacman -S gtklp<br />
<br />
===PDF virtual printer===<br />
CUPS-PDF is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. Obviously this package is not necessary, but it can be quite useful.<br />
<br />
Find generated PDF documents in a sub-directory located at <code>/var/spool/cups-pdf</code>. Normally, the subdirectory is named after the user who performed the job.<br />
<br />
This package can be installed by the following command:<br />
# pacman -S cups-pdf<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. For the Device, select '''CUPS-PDF (Virtual PDF Printer)'''; Make/Manufacturer, choose '''Generic'''; Model/Driver, select '''Generic postscript color printer'''. Alternatively, provide the PPD file from [http://www.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/cups-pdf-CURRENT/extra/CUPS-PDF.ppd this link].<br />
<br />
====Print to postscript: CUPS-PDF virtual printer trick====<br />
Printing to PDF in most applications like OpenOffice is no problem; just hit the button. Yet when printing out to postscript, matters take a little more work. For applications like OpenOffice where printing to kprinter is nebulous at best, there has to be another way -- and there is. The CUPS-PDF (Virtual PDF Printer) actually creates a postscript file and then creates the PDF using the ps2pdf utility. To print to postscript, what needs to be done is capturing the intermediate postscript file created by CUPS-PDF. This is easily accomplished with by selecting the "print to file" option in the print dialog. (choose either .ps or .eps as the extension) After selecting the "print to file" checkbox simply enter the filename and click "print".<br />
<br />
=====Configuring CUPS-PDF virtual printer=====<br />
1. Install cups & cups-pdf from extra.<br />
<br />
2. Start cups with:<br />
# /etc/rc.d/cups <br />
<br />
{{Note|Add 'cups' to the deamons line in /etc/rc.conf to start automatically at boot.}}<br />
<br />
3. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Find New Printers<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Now to print to postscript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
===Another source for printer drivers===<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
==Resources==<br />
* [http://localhost:631/documentation.html Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS Website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://home.nyc.rr.com/computertaijutsu/cups.html Tips and Suggestions on common CUPS problems], '''(Dead link)'''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's Printing Guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation Resources]''<br />
* [http://bbs.archlinux.org/ Arch Linux User Forums]<br />
<br />
{{Wikipedia|Common Unix Printing System}}</div>Bhobbithttps://wiki.archlinux.org/index.php?title=CUPS&diff=100066CUPS2010-03-14T04:48:38Z<p>Bhobbit: section link correction</p>
<hr />
<div>[[Category:Printers (English)]][[Category:HOWTOs (English)]]<br />
{{i18n|CUPS}}<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Installing and configuring CUPS}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|CUPS printer sharing}}<br />
{{Article summary wiki|CUPS printer-specific problems}}<br />
{{Article summary wiki|Samba}}<br />
{{Article summary end}}<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''CUPS is the standards-based, open source printing system developed by Apple Inc. for Mac OS® X and other UNIX®-like operating systems.''"<br />
Although there are other printing packages such as LPRNG, the ''C''ommon ''U''nix ''P''rinting ''S''ystem is the most popular choice because of its relative ease of use.<br />
<br />
==Installing==<br />
These packages are needed:<br />
# pacman -S cups ghostscript gsfonts<br />
<br />
* '''cups''' - The actual CUPS software<br />
* '''ghostscript''' - Interpreter for the Postscript language<br />
* '''gsfonts''' - GhostScript standard Type1 fonts<br />
* '''hal-cups-utils''' - This package might be needed. Read [http://bbs.archlinux.org/viewtopic.php?pid=655391#p655391 this forum post] for more information<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install Samba:<br />
# pacman -S samba<br />
<br />
===Printer driver===<br />
Here are some of the driver packages. Choosing the right driver depends on the printer:<br />
<br />
* '''gutenprint''' - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostSscript, CUPS, Foomatic, and the [[GIMP]]<br />
* '''foomatic-db, foomatic-db-engine, foomatic-db-nonfree, and foomatic-filters''' - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix. Installing foomatic-filters should solve problems if the cups error_log is reporting "stopped with status 22!".<br />
* '''hplip''' - HP GNU/Linux inkjet driver. Provides support for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models<br />
* '''splix''' - Samsung drivers for SPL (Samsung Printer Language) printers<br />
* '''ufr2''' - Canon UFR2 driver with support for LBP, iR and MF series printers. Package is available in the [[AUR]].<br />
* '''cups-pdf''' - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
<br />
If unsure of what driver package to install or if the current driver is not working, it may be easiest to just install all of drivers, since some of the packages are misleading because printers of other makes may rely on them. For instance, the Brother HL-2140 needs the hplip driver installed.<br />
# pacman -S gutenprint foomatic-db foomatic-db-engine \<br />
foomatic-db-nonfree foomatic-filters \<br />
hplip splix ufr2 cups-pdf<br />
<br />
====Download printer PPD====<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.linuxprinting.org/printer_list.cgi OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{Filename|/usr/share/cups/model/}}}}<br />
<br />
==Configuring==<br />
Now that CUPS is installed, there are a variety of options on how to setup printing solutions. As always, the tried and true command line method is at disposal. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. However, in order to make this process easy for the largest amount of users, this article will focus on the web interface provided by CUPS.<br />
<br />
If you are planning on connecting to a network printer, rather than one that is directly connected to the computer, you might want to read the [[CUPS printer sharing]] page first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
===Kernel modules===<br />
Before using the CUPS web interface, the appropriate kernel modules need to be installed. The following steps are from the Gentoo Printing Guide.<br />
<br />
This section may not be necessary, however, depending on which kernel is being used. The kernel module may load automatically after plugging in the printer. Use the {{Codeline|tail}} command (described below) to see if the printer has already been detected. The {{Codeline|lsmod}} utility can also be used to see what modules have been loaded.<br />
<br />
====USB printers====<br />
USB printer users may need to blacklist the {{codeline|usblp}} module. Keep in mind that there seems to be a lot of [http://bbs.archlinux.org/viewtopic.php?pid=660601 uncertainty] regarding blacklisting {{codeline|usblp}}, as some USB printers, including some Canon printer series, are not recognized without it. To disable the module, edit {{filename|rc.conf}} as shown:<br />
<br />
{{File|name=/etc/rc.conf|content=MODULES=(... '''!usblp''' ...)}}<br />
<br />
Custom kernel users may need to manually load the {{codeline|usbcore}} module before proceeding:<br />
# modprobe usbcore<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
If you're using {{codeline|usblp}}, the output should indicate that the printer has been detected like so:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
If you blacklisted {{codeline|usblp}}, you will see something like:<br />
usb 3-2: new full speed USB device using uhci_hcd and address 3<br />
usb 3-2: configuration #1 chosen from 1 choice<br />
<br />
====Parallel port printers====<br />
If planning on using a parallel port printer, note that the configuration is pretty much the same, except for the modules:<br />
# modprobe lp<br />
# modprobe parport<br />
# modprobe parport_pc<br />
<br />
Once again, check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
====Auto-loading====<br />
It's convenient to have the system automatically load the kernel module every time the it starts up. To do so, use a text editor to open up {{Filename|/etc/[[rc.conf]]}} and add the appropriate module to the <code>MODULES=()</code> line. Here is an example:<br />
MODULES=(!usbserial scsi_mod sd_mod snd-ymfpci snd-pcm-oss '''lp parport parport_pc''' ide-scsi)<br />
<br />
===CUPS daemon===<br />
With the kernel modules installed, the system is now ready to start the actual CUPS daemon. To do this, simply run this command:<br />
# /etc/rc.d/cups start<br />
<br />
For automatically starting CUPS every time the system is powered on, add it to the <code>DAEMONS=()</code> line in the {{Filename|/etc/rc.conf}} file. For example:<br />
DAEMONS=(pcmcia syslogd klogd !fam esd mono network autofs '''cups''' crond gdm)<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{Filename|/etc/hosts}}).<br />
<br />
{{Tip|[[GNOME]] users may be inclined towards installing the GNOME CUPS manager GUI frontend. See: [[#Alternative CUPS interfaces]]}}<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a user-name and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label ( e.g., next to ''USB Printer #1'' for USB printers). Finally, chose the appropriate drivers and the configuration is complete.<br />
<br />
Now, test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
==== CUPS administration ====<br />
<br />
A user-name and password will be required when administrating the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default user-name is the one assigned in the ''sys'' group, or root (change this by editing {{Filename|/etc/cups/cupsd.conf}} in the line of ''SystemGroup''). <br />
<br />
If the root account has been locked, it is not possible to log in the CUPS administration interface with the default user-name and password. In this case, it may be needed to change the default SystemGroup in cupsd.conf and read [http://bbs.archlinux.org/viewtopic.php?id=35567 this post].<br />
<br />
====Remote access to web interface====<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{Filename|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
There are three levels of access that can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{codeline|Allow}} statement to that level's section. An {{codeline|Allow}} statement can take one or more of the forms listed below:<br />
Allow all<br />
Allow host.domain.com<br />
Allow *.domain.com<br />
Allow ip-address<br />
Allow ip-address/netmask<br />
<br />
Deny statements can also be used. For example, if wanting to give all hosts on the 192.168.1.0/255.255.255.0 subnet full access, file {{Filename|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
# Encryption disabled by default<br />
#Encryption Required<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
==Troubleshooting==<br />
The best way to get printing working is to set 'LogLevel' in {{Filename|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{Filename|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{Filename|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{Filename|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{Filename|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
===Problems resulting from upgrades===<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
====CUPS stops working====<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" my result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy /etc/cups/cupsd.conf.default to /etc/cups/cupsd.conf (backup the old the configuration if needed):<br />
# cp /etc/cups/cupsd.conf.default /etc/cups/cupsd.conf<br />
and restart CUPS to employ the new settings.<br />
<br />
====Error with gnutls====<br />
If receiving errors such as:<br />
/usr/sbin/cupsd: error while loading shared libraries: libgnutls.so.13: cannot open shared object file: No such file or directory<br />
gnutls may be in need of updating:<br />
# pacman -S gnutls<br />
<br />
After updating, there may be a file named {{Filename|cupsd.conf.pacnew}} in {{Filename|/etc/cups}}. This is the unmodified original configuration file that has been placed as part of the update. Compare it with the currently installed version and adjust to preference.<br />
<br />
====All jobs are "stopped"====<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
====The PPD version is not compatible with gutenprint====<br />
Run:<br />
# /usr/sbin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
===USB printers under CUPS 1.4.x===<br />
New CUPS 1.4.x introduces many changes:<br />
<br />
====Configuration file====<br />
The syntax of the configuration file cupsd.conf changed. Start with a new cupsd.conf file based on /etc/cups/cupsd.conf.default.<br />
<br />
====Blacklisting usblp====<br />
CUPS now uses libusb and printer USB devices (under /dev/bus/usb/) instead of the usblp generated /dev/usb/lpX ones. In order to get USB printers working, the usblp module needs disabling. This can be done by blacklisting it in /etc/rc.conf, or by adding "blacklist usblp" to a configuration file in /etc/modprobe.d. Some users have also reported that they needed to reinstall their printer.<br />
<br />
====Device node permissions====<br />
In addition to usblp not being loaded, CUPS also needs the ownership of the USB device file of the printer to be root:lp, and permissions to be 660. E.g.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
This is supposed to be achieved by two udev rules in /lib/udev/rules.d/50-udev-default.rules:<br />
# hplip and cups 1.4+ use raw USB devices, so permissions should be similar to<br />
# the ones from the old usblp kernel module<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}=="", IMPORT{program}="usb_id --export %p"<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}==":0701*:", GROUP="lp", MODE="660"<br />
<br />
However, for some devices, in particular combined printer/scanner devices, these rules either do not trigger, or are overwritten by rules of the 'sane' package. In these cases a custom udev rule needs to be added. See below.<br />
<br />
=====Device node permission troubleshooting=====<br />
Get the printer's device file and its permissions with: <br />
$ lsusb<br />
...<br />
Bus 003 Device 002: ID 04b8:0841 Seiko Epson Corp.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
If the permissions are not already root:lp 660, enforce it by creating a custom udev rule, e.g<br />
cat /etc/udev/rules.d/10-usbprinter.rules<br />
ATTR{idVendor}=="04b8", ATTR{idProduct}=="0841", MODE:="0660", GROUP:="lp"<br />
<br />
Note that idVendor and idProduct are from the lsusb listing above.<br />
<br />
=====Loading firmware=====<br />
<br />
Some printers and drivers need to load firmware to the printer (such as HP LaserJet 10xx printers using foo2zjs) and do this by writing directly to the lp device, a functionality provided by usblp. A work around until this issue is resolved is to install the usblp module until the firmware is loaded, then remove the module to allow CUPS to work. This can be accomplished by manually running "$ modprobe usblp", waiting for the firmware to load, then "$ rmmod usblp". You can also not blacklist usblp, then put "rmmod usblp" to /etc/rc.local, allowing the firmware to be loaded on boot before rc.local is run, then removing usblp.<br />
<br />
===Other===<br />
<br />
=====CUPS permission errors=====<br />
*Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
*Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
====HPLIP printer sends "/usr/lib/cups/backend/hp failed" error====<br />
Make sure dbus is installed and running, e.g. check DAEMONS in {{Filename|/etc/rc.conf}} or run {{Codeline|ls /var/run/daemons}}.<br />
<br />
====hp-toolbox sends an error, "Unable to communicate with device"====<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/<printer id><br />
or, "{{Codeline|Unable to communicate with device"}}", then it may be needed to add the user to the lp group by running the following command:<br />
# gpasswd -a <username> lp<br />
<br />
====CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer====<br />
If receiving any of the following error messages in {{Filename|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer "<printer_name>" not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure '''hplip''' has been installed, in addition to [[#Packages|the packages mentioned above]], '''net-snmp''' is also needed. See [http://bbs.archlinux.org/viewtopic.php?id=65615 this forum post].<br />
# pacman -S hplip<br />
<br />
====Printing fails with unauthorised error====<br />
If the user has been added to the lp group, and allowed to print (set in {{Filename|cups.conf}}), then the problem lies in {{Filename|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
====Print button greyed-out in GNOME print dialogs====<br />
:''<small>Source: [http://bbs.archlinux.org/viewtopic.php?id=70418 I can't print from gnome applications. - Arch Forums]</small>''<br />
<br />
Be sure the package: '''libgnomeprint''' is installed<br />
<br />
Edit {{filename|/etc/cups/cupsd.conf}} and add<br />
# HostNameLookups Double<br />
<br />
Restart CUPS:<br />
# /etc/rc.d/cups restart<br />
<br />
====CUPS fails to print with 'Unable to open device "hal:///[...]": Permission denied'====<br />
The permissions on some files are wrong:<br />
# cd /usr/lib/cups/backend<br />
# chmod 700 hal # (previously 755)<br />
# chmod 700 usb # (previously 755)<br />
<br />
====Unknown supported format: application/postscript====<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{Filename|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{Filename|/etc/cups/mime.types}}.<br />
<br />
====Finding URIs for Windows Print Servers====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
<pre> WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series</pre><br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
<br />
==Appendix==<br />
<br />
===Alternative CUPS interfaces===<br />
If using [[GNOME]], a possibility is to manage and configure the printer by using the gnome-cups-manager. This package is available through pacman: <br />
# pacman -S gnome-cups-manager<br />
<br />
Alternatively, system-config-printer-gnome can be installed:<br />
# pacman -S system-config-printer-gnome<br />
<br />
For system-config-printer to work as it should, running as root may be required, or alternatively set up a "normal" user to administer CUPS (if so '''follow steps 1-3''')<br />
<br />
* 1. Create group, and add a user<br />
# groupadd lpadmin<br />
# usermod -aG lpadmin <username><br />
<br />
* 2. Add "lpadmin" (without the quotes) to this line in {{Filename|/etc/cups/cupsd.conf}}<br />
SystemGroup sys root <insert here><br />
<br />
* 3. Restart cups, log out and in again (or restart computer)<br />
# /etc/rc.d/cups restart<br />
<br />
[[KDE]] users can modify their printers from the Control Center. Both should refer to those desktop environments' documentation for more information on how to use the interfaces.<br />
<br />
There is also gtklp:<br />
# pacman -S gtklp<br />
<br />
===PDF virtual printer===<br />
CUPS-PDF is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. Obviously this package is not necessary, but it can be quite useful.<br />
<br />
Find generated PDF documents in a sub-directory located at <code>/var/spool/cups-pdf</code>. Normally, the subdirectory is named after the user who performed the job.<br />
<br />
This package can be installed by the following command:<br />
# pacman -S cups-pdf<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. For the Device, select '''CUPS-PDF (Virtual PDF Printer)'''; Make/Manufacturer, choose '''Generic'''; Model/Driver, select '''Generic postscript color printer'''. Alternatively, provide the PPD file from [http://www.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/cups-pdf-CURRENT/extra/CUPS-PDF.ppd this link].<br />
<br />
====Print to postscript: CUPS-PDF virtual printer trick====<br />
Printing to PDF in most applications like OpenOffice is no problem; just hit the button. Yet when printing out to postscript, matters take a little more work. For applications like OpenOffice where printing to kprinter is nebulous at best, there has to be another way -- and there is. The CUPS-PDF (Virtual PDF Printer) actually creates a postscript file and then creates the PDF using the ps2pdf utility. To print to postscript, what needs to be done is capturing the intermediate postscript file created by CUPS-PDF. This is easily accomplished with by selecting the "print to file" option in the print dialog. (choose either .ps or .eps as the extension) After selecting the "print to file" checkbox simply enter the filename and click "print".<br />
<br />
=====Configuring CUPS-PDF virtual printer=====<br />
1. Install cups & cups-pdf from extra.<br />
<br />
2. Start cups with:<br />
# /etc/rc.d/cups <br />
<br />
{{Note|Add 'cups' to the deamons line in /etc/rc.conf to start automatically at boot.}}<br />
<br />
3. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Find New Printers<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Now to print to postscript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
===Another source for printer drivers===<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
==Resources==<br />
* [http://localhost:631/documentation.html Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS Website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://home.nyc.rr.com/computertaijutsu/cups.html Tips and Suggestions on common CUPS problems], '''(Dead link)'''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's Printing Guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation Resources]''<br />
* [http://bbs.archlinux.org/ Arch Linux User Forums]<br />
<br />
{{Wikipedia|Common Unix Printing System}}</div>Bhobbithttps://wiki.archlinux.org/index.php?title=CUPS&diff=100065CUPS2010-03-14T04:45:04Z<p>Bhobbit: Wikification and additional info</p>
<hr />
<div>[[Category:Printers (English)]][[Category:HOWTOs (English)]]<br />
{{i18n|CUPS}}<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Installing and configuring CUPS}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|CUPS printer sharing}}<br />
{{Article summary wiki|CUPS printer-specific problems}}<br />
{{Article summary wiki|Samba}}<br />
{{Article summary end}}<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''CUPS is the standards-based, open source printing system developed by Apple Inc. for Mac OS® X and other UNIX®-like operating systems.''"<br />
Although there are other printing packages such as LPRNG, the ''C''ommon ''U''nix ''P''rinting ''S''ystem is the most popular choice because of its relative ease of use.<br />
<br />
==Installing==<br />
These packages are needed:<br />
# pacman -S cups ghostscript gsfonts<br />
<br />
* '''cups''' - The actual CUPS software<br />
* '''ghostscript''' - Interpreter for the Postscript language<br />
* '''gsfonts''' - GhostScript standard Type1 fonts<br />
* '''hal-cups-utils''' - This package might be needed. Read [http://bbs.archlinux.org/viewtopic.php?pid=655391#p655391 this forum post] for more information<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install Samba:<br />
# pacman -S samba<br />
<br />
===Printer driver===<br />
Here are some of the driver packages. Choosing the right driver depends on the printer:<br />
<br />
* '''gutenprint''' - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostSscript, CUPS, Foomatic, and the [[GIMP]]<br />
* '''foomatic-db, foomatic-db-engine, foomatic-db-nonfree, and foomatic-filters''' - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix. Installing foomatic-filters should solve problems if the cups error_log is reporting "stopped with status 22!".<br />
* '''hplip''' - HP GNU/Linux inkjet driver. Provides support for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models<br />
* '''splix''' - Samsung drivers for SPL (Samsung Printer Language) printers<br />
* '''ufr2''' - Canon UFR2 driver with support for LBP, iR and MF series printers. Package is available in the [[AUR]].<br />
* '''cups-pdf''' - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
<br />
If unsure of what driver package to install or if the current driver is not working, it may be easiest to just install all of drivers, since some of the packages are misleading because printers of other makes may rely on them. For instance, the Brother HL-2140 needs the hplip driver installed.<br />
# pacman -S gutenprint foomatic-db foomatic-db-engine \<br />
foomatic-db-nonfree foomatic-filters \<br />
hplip splix ufr2 cups-pdf<br />
<br />
====Download printer PPD====<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.linuxprinting.org/printer_list.cgi OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{Filename|/usr/share/cups/model/}}}}<br />
<br />
==Configuring==<br />
Now that CUPS is installed, there are a variety of options on how to setup printing solutions. As always, the tried and true command line method is at disposal. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. However, in order to make this process easy for the largest amount of users, this article will focus on the web interface provided by CUPS.<br />
<br />
Please note that if planning on connecting to a network printer, rather than one that is directly connected to the computer, read the [[#Printer sharing]] section first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
===Kernel modules===<br />
Before using the CUPS web interface, the appropriate kernel modules need to be installed. The following steps are from the Gentoo Printing Guide.<br />
<br />
This section may not be necessary, however, depending on which kernel is being used. The kernel module may load automatically after plugging in the printer. Use the {{Codeline|tail}} command (described below) to see if the printer has already been detected. The {{Codeline|lsmod}} utility can also be used to see what modules have been loaded.<br />
<br />
====USB printers====<br />
USB printer users may need to blacklist the {{codeline|usblp}} module. Keep in mind that there seems to be a lot of [http://bbs.archlinux.org/viewtopic.php?pid=660601 uncertainty] regarding blacklisting {{codeline|usblp}}, as some USB printers, including some Canon printer series, are not recognized without it. To disable the module, edit {{filename|rc.conf}} as shown:<br />
<br />
{{File|name=/etc/rc.conf|content=MODULES=(... '''!usblp''' ...)}}<br />
<br />
Custom kernel users may need to manually load the {{codeline|usbcore}} module before proceeding:<br />
# modprobe usbcore<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
If you're using {{codeline|usblp}}, the output should indicate that the printer has been detected like so:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
If you blacklisted {{codeline|usblp}}, you will see something like:<br />
usb 3-2: new full speed USB device using uhci_hcd and address 3<br />
usb 3-2: configuration #1 chosen from 1 choice<br />
<br />
====Parallel port printers====<br />
If planning on using a parallel port printer, note that the configuration is pretty much the same, except for the modules:<br />
# modprobe lp<br />
# modprobe parport<br />
# modprobe parport_pc<br />
<br />
Once again, check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
====Auto-loading====<br />
It's convenient to have the system automatically load the kernel module every time the it starts up. To do so, use a text editor to open up {{Filename|/etc/[[rc.conf]]}} and add the appropriate module to the <code>MODULES=()</code> line. Here is an example:<br />
MODULES=(!usbserial scsi_mod sd_mod snd-ymfpci snd-pcm-oss '''lp parport parport_pc''' ide-scsi)<br />
<br />
===CUPS daemon===<br />
With the kernel modules installed, the system is now ready to start the actual CUPS daemon. To do this, simply run this command:<br />
# /etc/rc.d/cups start<br />
<br />
For automatically starting CUPS every time the system is powered on, add it to the <code>DAEMONS=()</code> line in the {{Filename|/etc/rc.conf}} file. For example:<br />
DAEMONS=(pcmcia syslogd klogd !fam esd mono network autofs '''cups''' crond gdm)<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{Filename|/etc/hosts}}).<br />
<br />
{{Tip|[[GNOME]] users may be inclined towards installing the GNOME CUPS manager GUI frontend. See: [[#Alternative CUPS interfaces]]}}<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a user-name and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label ( e.g., next to ''USB Printer #1'' for USB printers). Finally, chose the appropriate drivers and the configuration is complete.<br />
<br />
Now, test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
==== CUPS administration ====<br />
<br />
A user-name and password will be required when administrating the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default user-name is the one assigned in the ''sys'' group, or root (change this by editing {{Filename|/etc/cups/cupsd.conf}} in the line of ''SystemGroup''). <br />
<br />
If the root account has been locked, it is not possible to log in the CUPS administration interface with the default user-name and password. In this case, it may be needed to change the default SystemGroup in cupsd.conf and read [http://bbs.archlinux.org/viewtopic.php?id=35567 this post].<br />
<br />
====Remote access to web interface====<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{Filename|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
There are three levels of access that can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{codeline|Allow}} statement to that level's section. An {{codeline|Allow}} statement can take one or more of the forms listed below:<br />
Allow all<br />
Allow host.domain.com<br />
Allow *.domain.com<br />
Allow ip-address<br />
Allow ip-address/netmask<br />
<br />
Deny statements can also be used. For example, if wanting to give all hosts on the 192.168.1.0/255.255.255.0 subnet full access, file {{Filename|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
# Encryption disabled by default<br />
#Encryption Required<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
==Troubleshooting==<br />
The best way to get printing working is to set 'LogLevel' in {{Filename|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{Filename|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{Filename|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{Filename|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{Filename|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
===Problems resulting from upgrades===<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
====CUPS stops working====<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" my result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy /etc/cups/cupsd.conf.default to /etc/cups/cupsd.conf (backup the old the configuration if needed):<br />
# cp /etc/cups/cupsd.conf.default /etc/cups/cupsd.conf<br />
and restart CUPS to employ the new settings.<br />
<br />
====Error with gnutls====<br />
If receiving errors such as:<br />
/usr/sbin/cupsd: error while loading shared libraries: libgnutls.so.13: cannot open shared object file: No such file or directory<br />
gnutls may be in need of updating:<br />
# pacman -S gnutls<br />
<br />
After updating, there may be a file named {{Filename|cupsd.conf.pacnew}} in {{Filename|/etc/cups}}. This is the unmodified original configuration file that has been placed as part of the update. Compare it with the currently installed version and adjust to preference.<br />
<br />
====All jobs are "stopped"====<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
====The PPD version is not compatible with gutenprint====<br />
Run:<br />
# /usr/sbin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
===USB printers under CUPS 1.4.x===<br />
New CUPS 1.4.x introduces many changes:<br />
<br />
====Configuration file====<br />
The syntax of the configuration file cupsd.conf changed. Start with a new cupsd.conf file based on /etc/cups/cupsd.conf.default.<br />
<br />
====Blacklisting usblp====<br />
CUPS now uses libusb and printer USB devices (under /dev/bus/usb/) instead of the usblp generated /dev/usb/lpX ones. In order to get USB printers working, the usblp module needs disabling. This can be done by blacklisting it in /etc/rc.conf, or by adding "blacklist usblp" to a configuration file in /etc/modprobe.d. Some users have also reported that they needed to reinstall their printer.<br />
<br />
====Device node permissions====<br />
In addition to usblp not being loaded, CUPS also needs the ownership of the USB device file of the printer to be root:lp, and permissions to be 660. E.g.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
This is supposed to be achieved by two udev rules in /lib/udev/rules.d/50-udev-default.rules:<br />
# hplip and cups 1.4+ use raw USB devices, so permissions should be similar to<br />
# the ones from the old usblp kernel module<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}=="", IMPORT{program}="usb_id --export %p"<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}==":0701*:", GROUP="lp", MODE="660"<br />
<br />
However, for some devices, in particular combined printer/scanner devices, these rules either do not trigger, or are overwritten by rules of the 'sane' package. In these cases a custom udev rule needs to be added. See below.<br />
<br />
=====Device node permission troubleshooting=====<br />
Get the printer's device file and its permissions with: <br />
$ lsusb<br />
...<br />
Bus 003 Device 002: ID 04b8:0841 Seiko Epson Corp.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
If the permissions are not already root:lp 660, enforce it by creating a custom udev rule, e.g<br />
cat /etc/udev/rules.d/10-usbprinter.rules<br />
ATTR{idVendor}=="04b8", ATTR{idProduct}=="0841", MODE:="0660", GROUP:="lp"<br />
<br />
Note that idVendor and idProduct are from the lsusb listing above.<br />
<br />
=====Loading firmware=====<br />
<br />
Some printers and drivers need to load firmware to the printer (such as HP LaserJet 10xx printers using foo2zjs) and do this by writing directly to the lp device, a functionality provided by usblp. A work around until this issue is resolved is to install the usblp module until the firmware is loaded, then remove the module to allow CUPS to work. This can be accomplished by manually running "$ modprobe usblp", waiting for the firmware to load, then "$ rmmod usblp". You can also not blacklist usblp, then put "rmmod usblp" to /etc/rc.local, allowing the firmware to be loaded on boot before rc.local is run, then removing usblp.<br />
<br />
===Other===<br />
<br />
=====CUPS permission errors=====<br />
*Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
*Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
====HPLIP printer sends "/usr/lib/cups/backend/hp failed" error====<br />
Make sure dbus is installed and running, e.g. check DAEMONS in {{Filename|/etc/rc.conf}} or run {{Codeline|ls /var/run/daemons}}.<br />
<br />
====hp-toolbox sends an error, "Unable to communicate with device"====<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/<printer id><br />
or, "{{Codeline|Unable to communicate with device"}}", then it may be needed to add the user to the lp group by running the following command:<br />
# gpasswd -a <username> lp<br />
<br />
====CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer====<br />
If receiving any of the following error messages in {{Filename|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer "<printer_name>" not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure '''hplip''' has been installed, in addition to [[#Packages|the packages mentioned above]], '''net-snmp''' is also needed. See [http://bbs.archlinux.org/viewtopic.php?id=65615 this forum post].<br />
# pacman -S hplip<br />
<br />
====Printing fails with unauthorised error====<br />
If the user has been added to the lp group, and allowed to print (set in {{Filename|cups.conf}}), then the problem lies in {{Filename|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
====Print button greyed-out in GNOME print dialogs====<br />
:''<small>Source: [http://bbs.archlinux.org/viewtopic.php?id=70418 I can't print from gnome applications. - Arch Forums]</small>''<br />
<br />
Be sure the package: '''libgnomeprint''' is installed<br />
<br />
Edit {{filename|/etc/cups/cupsd.conf}} and add<br />
# HostNameLookups Double<br />
<br />
Restart CUPS:<br />
# /etc/rc.d/cups restart<br />
<br />
====CUPS fails to print with 'Unable to open device "hal:///[...]": Permission denied'====<br />
The permissions on some files are wrong:<br />
# cd /usr/lib/cups/backend<br />
# chmod 700 hal # (previously 755)<br />
# chmod 700 usb # (previously 755)<br />
<br />
====Unknown supported format: application/postscript====<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{Filename|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{Filename|/etc/cups/mime.types}}.<br />
<br />
====Finding URIs for Windows Print Servers====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
<pre> WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series</pre><br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
<br />
==Appendix==<br />
<br />
===Alternative CUPS interfaces===<br />
If using [[GNOME]], a possibility is to manage and configure the printer by using the gnome-cups-manager. This package is available through pacman: <br />
# pacman -S gnome-cups-manager<br />
<br />
Alternatively, system-config-printer-gnome can be installed:<br />
# pacman -S system-config-printer-gnome<br />
<br />
For system-config-printer to work as it should, running as root may be required, or alternatively set up a "normal" user to administer CUPS (if so '''follow steps 1-3''')<br />
<br />
* 1. Create group, and add a user<br />
# groupadd lpadmin<br />
# usermod -aG lpadmin <username><br />
<br />
* 2. Add "lpadmin" (without the quotes) to this line in {{Filename|/etc/cups/cupsd.conf}}<br />
SystemGroup sys root <insert here><br />
<br />
* 3. Restart cups, log out and in again (or restart computer)<br />
# /etc/rc.d/cups restart<br />
<br />
[[KDE]] users can modify their printers from the Control Center. Both should refer to those desktop environments' documentation for more information on how to use the interfaces.<br />
<br />
There is also gtklp:<br />
# pacman -S gtklp<br />
<br />
===PDF virtual printer===<br />
CUPS-PDF is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. Obviously this package is not necessary, but it can be quite useful.<br />
<br />
Find generated PDF documents in a sub-directory located at <code>/var/spool/cups-pdf</code>. Normally, the subdirectory is named after the user who performed the job.<br />
<br />
This package can be installed by the following command:<br />
# pacman -S cups-pdf<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. For the Device, select '''CUPS-PDF (Virtual PDF Printer)'''; Make/Manufacturer, choose '''Generic'''; Model/Driver, select '''Generic postscript color printer'''. Alternatively, provide the PPD file from [http://www.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/cups-pdf-CURRENT/extra/CUPS-PDF.ppd this link].<br />
<br />
====Print to postscript: CUPS-PDF virtual printer trick====<br />
Printing to PDF in most applications like OpenOffice is no problem; just hit the button. Yet when printing out to postscript, matters take a little more work. For applications like OpenOffice where printing to kprinter is nebulous at best, there has to be another way -- and there is. The CUPS-PDF (Virtual PDF Printer) actually creates a postscript file and then creates the PDF using the ps2pdf utility. To print to postscript, what needs to be done is capturing the intermediate postscript file created by CUPS-PDF. This is easily accomplished with by selecting the "print to file" option in the print dialog. (choose either .ps or .eps as the extension) After selecting the "print to file" checkbox simply enter the filename and click "print".<br />
<br />
=====Configuring CUPS-PDF virtual printer=====<br />
1. Install cups & cups-pdf from extra.<br />
<br />
2. Start cups with:<br />
# /etc/rc.d/cups <br />
<br />
{{Note|Add 'cups' to the deamons line in /etc/rc.conf to start automatically at boot.}}<br />
<br />
3. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Find New Printers<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Now to print to postscript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
===Another source for printer drivers===<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
==Resources==<br />
* [http://localhost:631/documentation.html Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS Website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://home.nyc.rr.com/computertaijutsu/cups.html Tips and Suggestions on common CUPS problems], '''(Dead link)'''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's Printing Guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation Resources]''<br />
* [http://bbs.archlinux.org/ Arch Linux User Forums]<br />
<br />
{{Wikipedia|Common Unix Printing System}}</div>Bhobbithttps://wiki.archlinux.org/index.php?title=CUPS&diff=100063CUPS2010-03-14T04:36:46Z<p>Bhobbit: section moved to CUPS printer-specific problems</p>
<hr />
<div>[[Category:Printers (English)]][[Category:HOWTOs (English)]]<br />
{{i18n|CUPS}}<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Installing and configuring CUPS}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|CUPS printer sharing}}<br />
{{Article summary wiki|CUPS printer-specific problems}}<br />
{{Article summary wiki|Samba}}<br />
{{Article summary end}}<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''CUPS is the standards-based, open source printing system developed by Apple Inc. for Mac OS® X and other UNIX®-like operating systems.''"<br />
Although there are other printing packages such as LPRNG, the ''C''ommon ''U''nix ''P''rinting ''S''ystem is the most popular choice because of its relative ease of use.<br />
<br />
==Installing==<br />
These packages are needed:<br />
# pacman -S cups ghostscript gsfonts<br />
<br />
* '''cups''' - The actual CUPS software<br />
* '''ghostscript''' - Interpreter for the Postscript language<br />
* '''gsfonts''' - GhostScript standard Type1 fonts<br />
* '''hal-cups-utils''' - This package might be needed. Read [http://bbs.archlinux.org/viewtopic.php?pid=655391#p655391 this forum post] for more information<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install Samba:<br />
# pacman -S samba<br />
<br />
===Printer driver===<br />
Here are some of the driver packages. Choosing the right driver depends on the printer:<br />
<br />
* '''gutenprint''' - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostSscript, CUPS, Foomatic, and the [[GIMP]]<br />
* '''foomatic-db, foomatic-db-engine, foomatic-db-nonfree, and foomatic-filters''' - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix. Installing foomatic-filters should solve problems if the cups error_log is reporting "stopped with status 22!".<br />
* '''hplip''' - HP GNU/Linux inkjet driver. Provides support for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models<br />
* '''splix''' - Samsung drivers for SPL (Samsung Printer Language) printers<br />
* '''ufr2''' - Canon UFR2 driver with support for LBP, iR and MF series printers. Package is available in the [[AUR]].<br />
* '''cups-pdf''' - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
<br />
If unsure of what driver package to install or if the current driver is not working, it may be easiest to just install all of drivers, since some of the packages are misleading because printers of other makes may rely on them. For instance, the Brother HL-2140 needs the hplip driver installed.<br />
# pacman -S gutenprint foomatic-db foomatic-db-engine \<br />
foomatic-db-nonfree foomatic-filters \<br />
hplip splix ufr2 cups-pdf<br />
<br />
====Download printer PPD====<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.linuxprinting.org/printer_list.cgi OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{Filename|/usr/share/cups/model/}}}}<br />
<br />
==Configuring==<br />
Now that CUPS is installed, there are a variety of options on how to setup printing solutions. As always, the tried and true command line method is at disposal. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. However, in order to make this process easy for the largest amount of users, this article will focus on the web interface provided by CUPS.<br />
<br />
Please note that if planning on connecting to a network printer, rather than one that is directly connected to the computer, read the [[#Printer sharing]] section first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
===Kernel modules===<br />
Before using the CUPS web interface, the appropriate kernel modules need to be installed. The following steps are from the Gentoo Printing Guide.<br />
<br />
This section may not be necessary, however, depending on which kernel is being used. The kernel module may load automatically after plugging in the printer. Use the {{Codeline|tail}} command (described below) to see if the printer has already been detected. The {{Codeline|lsmod}} utility can also be used to see what modules have been loaded.<br />
<br />
====USB printers====<br />
USB printer users may need to blacklist the {{codeline|usblp}} module. Keep in mind that there seems to be a lot of [http://bbs.archlinux.org/viewtopic.php?pid=660601 uncertainty] regarding blacklisting usblp, as some USB printers, including some Canon printer series, are not recognized without it. To disable the module, edit {{filename|rc.conf}} as shown:<br />
MODULES=(... '''!usblp''' ...)<br />
<br />
Custom kernel users may need to manually load the {{codeline|usbcore}} module before proceeding:<br />
# modprobe usbcore<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
The output should indicate that the printer has been detected:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
====Parallel port printers====<br />
If planning on using a parallel port printer, note that the configuration is pretty much the same, except for the modules:<br />
# modprobe lp<br />
# modprobe parport<br />
# modprobe parport_pc<br />
<br />
Once again, check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
====Auto-loading====<br />
It's convenient to have the system automatically load the kernel module every time the it starts up. To do so, use a text editor to open up {{Filename|/etc/[[rc.conf]]}} and add the appropriate module to the <code>MODULES=()</code> line. Here is an example:<br />
MODULES=(!usbserial scsi_mod sd_mod snd-ymfpci snd-pcm-oss '''lp parport parport_pc''' ide-scsi)<br />
<br />
===CUPS daemon===<br />
With the kernel modules installed, the system is now ready to start the actual CUPS daemon. To do this, simply run this command:<br />
# /etc/rc.d/cups start<br />
<br />
For automatically starting CUPS every time the system is powered on, add it to the <code>DAEMONS=()</code> line in the {{Filename|/etc/rc.conf}} file. For example:<br />
DAEMONS=(pcmcia syslogd klogd !fam esd mono network autofs '''cups''' crond gdm)<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{Filename|/etc/hosts}}).<br />
<br />
{{Tip|[[GNOME]] users may be inclined towards installing the GNOME CUPS manager GUI frontend. See: [[#Alternative CUPS interfaces]]}}<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a user-name and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label ( e.g., next to ''USB Printer #1'' for USB printers). Finally, chose the appropriate drivers and the configuration is complete.<br />
<br />
Now, test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
==== CUPS administration ====<br />
<br />
A user-name and password will be required when administrating the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default user-name is the one assigned in the ''sys'' group, or root (change this by editing {{Filename|/etc/cups/cupsd.conf}} in the line of ''SystemGroup''). <br />
<br />
If the root account has been locked, it is not possible to log in the CUPS administration interface with the default user-name and password. In this case, it may be needed to change the default SystemGroup in cupsd.conf and read [http://bbs.archlinux.org/viewtopic.php?id=35567 this post].<br />
<br />
====Remote access to web interface====<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{Filename|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
There are three levels of access that can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{codeline|Allow}} statement to that level's section. An {{codeline|Allow}} statement can take one or more of the forms listed below:<br />
Allow all<br />
Allow host.domain.com<br />
Allow *.domain.com<br />
Allow ip-address<br />
Allow ip-address/netmask<br />
<br />
Deny statements can also be used. For example, if wanting to give all hosts on the 192.168.1.0/255.255.255.0 subnet full access, file {{Filename|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
# Encryption disabled by default<br />
#Encryption Required<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
==Troubleshooting==<br />
The best way to get printing working is to set 'LogLevel' in {{Filename|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{Filename|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{Filename|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{Filename|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{Filename|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
===Problems resulting from upgrades===<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
====CUPS stops working====<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" my result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy /etc/cups/cupsd.conf.default to /etc/cups/cupsd.conf (backup the old the configuration if needed):<br />
# cp /etc/cups/cupsd.conf.default /etc/cups/cupsd.conf<br />
and restart CUPS to employ the new settings.<br />
<br />
====Error with gnutls====<br />
If receiving errors such as:<br />
/usr/sbin/cupsd: error while loading shared libraries: libgnutls.so.13: cannot open shared object file: No such file or directory<br />
gnutls may be in need of updating:<br />
# pacman -S gnutls<br />
<br />
After updating, there may be a file named {{Filename|cupsd.conf.pacnew}} in {{Filename|/etc/cups}}. This is the unmodified original configuration file that has been placed as part of the update. Compare it with the currently installed version and adjust to preference.<br />
<br />
====All jobs are "stopped"====<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
====The PPD version is not compatible with gutenprint====<br />
Run:<br />
# /usr/sbin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
===USB printers under CUPS 1.4.x===<br />
New CUPS 1.4.x introduces many changes:<br />
<br />
====Configuration file====<br />
The syntax of the configuration file cupsd.conf changed. Start with a new cupsd.conf file based on /etc/cups/cupsd.conf.default.<br />
<br />
====Blacklisting usblp====<br />
CUPS now uses libusb and printer USB devices (under /dev/bus/usb/) instead of the usblp generated /dev/usb/lpX ones. In order to get USB printers working, the usblp module needs disabling. This can be done by blacklisting it in /etc/rc.conf, or by adding "blacklist usblp" to a configuration file in /etc/modprobe.d. Some users have also reported that they needed to reinstall their printer.<br />
<br />
====Device node permissions====<br />
In addition to usblp not being loaded, CUPS also needs the ownership of the USB device file of the printer to be root:lp, and permissions to be 660. E.g.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
This is supposed to be achieved by two udev rules in /lib/udev/rules.d/50-udev-default.rules:<br />
# hplip and cups 1.4+ use raw USB devices, so permissions should be similar to<br />
# the ones from the old usblp kernel module<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}=="", IMPORT{program}="usb_id --export %p"<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}==":0701*:", GROUP="lp", MODE="660"<br />
<br />
However, for some devices, in particular combined printer/scanner devices, these rules either do not trigger, or are overwritten by rules of the 'sane' package. In these cases a custom udev rule needs to be added. See below.<br />
<br />
=====Device node permission troubleshooting=====<br />
Get the printer's device file and its permissions with: <br />
$ lsusb<br />
...<br />
Bus 003 Device 002: ID 04b8:0841 Seiko Epson Corp.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
If the permissions are not already root:lp 660, enforce it by creating a custom udev rule, e.g<br />
cat /etc/udev/rules.d/10-usbprinter.rules<br />
ATTR{idVendor}=="04b8", ATTR{idProduct}=="0841", MODE:="0660", GROUP:="lp"<br />
<br />
Note that idVendor and idProduct are from the lsusb listing above.<br />
<br />
=====Loading firmware=====<br />
<br />
Some printers and drivers need to load firmware to the printer (such as HP LaserJet 10xx printers using foo2zjs) and do this by writing directly to the lp device, a functionality provided by usblp. A work around until this issue is resolved is to install the usblp module until the firmware is loaded, then remove the module to allow CUPS to work. This can be accomplished by manually running "$ modprobe usblp", waiting for the firmware to load, then "$ rmmod usblp". You can also not blacklist usblp, then put "rmmod usblp" to /etc/rc.local, allowing the firmware to be loaded on boot before rc.local is run, then removing usblp.<br />
<br />
===Other===<br />
<br />
=====CUPS permission errors=====<br />
*Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
*Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
====HPLIP printer sends "/usr/lib/cups/backend/hp failed" error====<br />
Make sure dbus is installed and running, e.g. check DAEMONS in {{Filename|/etc/rc.conf}} or run {{Codeline|ls /var/run/daemons}}.<br />
<br />
====hp-toolbox sends an error, "Unable to communicate with device"====<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/<printer id><br />
or, "{{Codeline|Unable to communicate with device"}}", then it may be needed to add the user to the lp group by running the following command:<br />
# gpasswd -a <username> lp<br />
<br />
====CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer====<br />
If receiving any of the following error messages in {{Filename|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer "<printer_name>" not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure '''hplip''' has been installed, in addition to [[#Packages|the packages mentioned above]], '''net-snmp''' is also needed. See [http://bbs.archlinux.org/viewtopic.php?id=65615 this forum post].<br />
# pacman -S hplip<br />
<br />
====Printing fails with unauthorised error====<br />
If the user has been added to the lp group, and allowed to print (set in {{Filename|cups.conf}}), then the problem lies in {{Filename|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
====Print button greyed-out in GNOME print dialogs====<br />
:''<small>Source: [http://bbs.archlinux.org/viewtopic.php?id=70418 I can't print from gnome applications. - Arch Forums]</small>''<br />
<br />
Be sure the package: '''libgnomeprint''' is installed<br />
<br />
Edit {{filename|/etc/cups/cupsd.conf}} and add<br />
# HostNameLookups Double<br />
<br />
Restart CUPS:<br />
# /etc/rc.d/cups restart<br />
<br />
====CUPS fails to print with 'Unable to open device "hal:///[...]": Permission denied'====<br />
The permissions on some files are wrong:<br />
# cd /usr/lib/cups/backend<br />
# chmod 700 hal # (previously 755)<br />
# chmod 700 usb # (previously 755)<br />
<br />
====Unknown supported format: application/postscript====<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{Filename|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{Filename|/etc/cups/mime.types}}.<br />
<br />
====Finding URIs for Windows Print Servers====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
<pre> WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series</pre><br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
<br />
==Appendix==<br />
<br />
===Alternative CUPS interfaces===<br />
If using [[GNOME]], a possibility is to manage and configure the printer by using the gnome-cups-manager. This package is available through pacman: <br />
# pacman -S gnome-cups-manager<br />
<br />
Alternatively, system-config-printer-gnome can be installed:<br />
# pacman -S system-config-printer-gnome<br />
<br />
For system-config-printer to work as it should, running as root may be required, or alternatively set up a "normal" user to administer CUPS (if so '''follow steps 1-3''')<br />
<br />
* 1. Create group, and add a user<br />
# groupadd lpadmin<br />
# usermod -aG lpadmin <username><br />
<br />
* 2. Add "lpadmin" (without the quotes) to this line in {{Filename|/etc/cups/cupsd.conf}}<br />
SystemGroup sys root <insert here><br />
<br />
* 3. Restart cups, log out and in again (or restart computer)<br />
# /etc/rc.d/cups restart<br />
<br />
[[KDE]] users can modify their printers from the Control Center. Both should refer to those desktop environments' documentation for more information on how to use the interfaces.<br />
<br />
There is also gtklp:<br />
# pacman -S gtklp<br />
<br />
===PDF virtual printer===<br />
CUPS-PDF is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. Obviously this package is not necessary, but it can be quite useful.<br />
<br />
Find generated PDF documents in a sub-directory located at <code>/var/spool/cups-pdf</code>. Normally, the subdirectory is named after the user who performed the job.<br />
<br />
This package can be installed by the following command:<br />
# pacman -S cups-pdf<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. For the Device, select '''CUPS-PDF (Virtual PDF Printer)'''; Make/Manufacturer, choose '''Generic'''; Model/Driver, select '''Generic postscript color printer'''. Alternatively, provide the PPD file from [http://www.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/cups-pdf-CURRENT/extra/CUPS-PDF.ppd this link].<br />
<br />
====Print to postscript: CUPS-PDF virtual printer trick====<br />
Printing to PDF in most applications like OpenOffice is no problem; just hit the button. Yet when printing out to postscript, matters take a little more work. For applications like OpenOffice where printing to kprinter is nebulous at best, there has to be another way -- and there is. The CUPS-PDF (Virtual PDF Printer) actually creates a postscript file and then creates the PDF using the ps2pdf utility. To print to postscript, what needs to be done is capturing the intermediate postscript file created by CUPS-PDF. This is easily accomplished with by selecting the "print to file" option in the print dialog. (choose either .ps or .eps as the extension) After selecting the "print to file" checkbox simply enter the filename and click "print".<br />
<br />
=====Configuring CUPS-PDF virtual printer=====<br />
1. Install cups & cups-pdf from extra.<br />
<br />
2. Start cups with:<br />
# /etc/rc.d/cups <br />
<br />
{{Note|Add 'cups' to the deamons line in /etc/rc.conf to start automatically at boot.}}<br />
<br />
3. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Find New Printers<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Now to print to postscript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
===Another source for printer drivers===<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
==Resources==<br />
* [http://localhost:631/documentation.html Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS Website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://home.nyc.rr.com/computertaijutsu/cups.html Tips and Suggestions on common CUPS problems], '''(Dead link)'''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's Printing Guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation Resources]''<br />
* [http://bbs.archlinux.org/ Arch Linux User Forums]<br />
<br />
{{Wikipedia|Common Unix Printing System}}</div>Bhobbithttps://wiki.archlinux.org/index.php?title=CUPS/Printer-specific_problems&diff=100062CUPS/Printer-specific problems2010-03-14T04:36:22Z<p>Bhobbit: Utility functions section moved from CUPS</p>
<hr />
<div>[[Category:Printers (English)]][[Category:HOWTOs (English)]]<br />
{{i18n|CUPS printer-specific problems}}<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Dealing with printer-specific problems}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|CUPS}}<br />
{{Article summary end}}<br />
<br />
Printer-specific problems and their solutions.<br />
<br />
==Brother==<br />
<br />
===DCP 7020===<br />
See: [[Brother DCP-7020]]<br />
<br />
==Canon==<br />
===MF 4150===<br />
This is required as some Canon printers apparently do not declare their specification correctly for kernel and libusb to recognize them<br />
<br />
* Do NOT blacklist usblp module.<br />
<br />
* Install hal-cups-utils and restart hal<br />
# sudo pacman -S hal-cups-utils<br />
# sudo /etc/rc.d/hal restart<br />
<br />
* Connect the printer<br />
<br />
The printer should now be recognized by the CUPS Add printer dialog. If still having problems, try restarting CUPS.<br />
<br />
* Install UFRII driver ({{Package AUR|ufr2}} from the [[AUR]] and complete the printer installation.<br />
<br />
==Epson==<br />
<br />
===Utility functions===<br />
====escputil====<br />
This section explains how to perform some of the utility functions (such as nozzle cleaning) on Epson printers, by using the escputil utility, part of the gutenprint package.<br />
<br />
There is a escputil's man-page provides basic information, but it does not touch on how to identify the printer. There are two parameters that can be used to do so:<br />
<br />
* One is <tt>--printer</tt>: it expects the name used to identify the printer when is was configured.<br />
<br />
* The other is <tt>--raw-device</tt>: this option expects a path beginning with "/dev". If the printer is the only serial printer on the system, "/dev/lp0" should be its device node. For USB printers, it is "/dev/usb/lp0". If having more than one printer, they will have names ending in "lp1", "lp2", etc.<br />
<br />
On to the maintenance options:<br />
* To clean the printer heads:<br />
$ escputil -u --clean-head<br />
<br />
* To print the nozzle-check pattern (allows verifying that the previous head cleaning worked, and determining the heads need cleaning):<br />
$ escputil -u --nozzle-check<br />
<br />
If wanting to perform an operation that requires two-way communication with a printer, use the "--raw-device" specification and the user must be root or be a member of the group "lp".<br />
<br />
* The following is an example of getting the printer's internal identification:<br />
$ sudo escputil --raw-device=/dev/usb/lp0 --identify<br />
<br />
* To print out the ink levels of the printer:<br />
$ sudo escputil --raw-device=/dev/usb/lp0 --ink-level<br />
<br />
====mtink====<br />
This is a printer status monitor which enables to get the remaining ink quantity, to print test patterns, to reset printer and to clean nozzle. It use an intuitive graphical user interface. Package can be downloaded from [http://aur.archlinux.org/packages.php?do_Details=1&ID=476&O=0&L=0&C=0&K=mtink&SB=n&SO=a&PP=25&do_MyPackages=0&do_Orphans=0&SeB=nd AUR].<br />
<br />
====Stylus-toolbox====<br />
This is a GUI using escputil and cups drivers. It supports nearly all USB printer of Epson and displays ink quantity, can clean and align print heads and print test patterns. It can be downloaded from [http://aur.archlinux.org/packages.php?ID=30319 AUR]<br />
<br />
===AcuLaser CX11(NF)===<br />
Install [http://aur.archlinux.org/packages.php?ID=30424 Epson-ALCX11-filter] from the AUR. Restart CUPS and add the printer using the driver "EPSON AL-CX11, ESC/PageS Filter".<br />
<br />
Both connections, USB and network, should work as expected.<br />
<br />
==FX==<br />
=== C1110 (not model B)===<br />
Keep in mind that these directions assume that the printer is connected and listening on the network.<br />
<br />
*Install cpio and rpmunpack to later unpack the package:<br />
# pacman -S cpio rpmunpack cups ghostscript gsfonts<br />
<br />
*Get the FX GNU/Linux driver [http://www.fujixeroxprinters.com/downloads/uploaded/Drivers/DocuPrint%20C1110%20C1110B/linux/fxlinuxprint-1.0.1-1.i386.zip here].<br />
<br />
*Unzip {{Filename|fxlinuxprint-1.0.1-1.i386.zip}} to /var/tmp (the directory is not important):<br />
$ unzip fxlinuxprint-1.0.1-1.i386.zip -d /var/tmp<br />
<br />
*Continue extracting the file:<br />
$ cd /var/tmp<br />
$ rpmunpack fxlinuxprint-1.0.1-1.i386.rpm<br />
$ gunzip fxlinuxprint-1.0.1-1.cpio.gz<br />
<br />
*Move the cpio DST file (for convenience):<br />
$ mkdir /var/tmp/DST<br />
$ mv fxlinuxprint-1.0.1-1.cpio /var/tmp/DST<br />
<br />
*Extract it:<br />
$ cd /var/tmp/DST<br />
$ cpio -id < fxlinuxprint-1.0.1-1.cpio<br />
<br />
*Filter the relevant files:<br />
$ cd /var/tmp<br />
$ find /var/tmp/DST -type f |cat -n<br />
1 /var/tmp/DST/etc/cups/mimefx.convs<br />
2 /var/tmp/DST/etc/cups/mimefx.types<br />
3 /var/tmp/DST/usr/lib/cups/filter/pdftopjlfx<br />
4 /var/tmp/DST/usr/lib/cups/filter/pstopdffx<br />
5 /var/tmp/DST/usr/lib/cups/filter/pdftopdffx<br />
6 /var/tmp/DST/usr/share/cups/model/FujiXerox/en/fxlinuxprint.ppd<br />
<br />
*Copy the files found in the previous step to /<br />
{{Note|For the PPD use {{Filename|/usr/share/cups/model/fxlinuxprint.ppd}}}}<br />
<br />
*Access http://localhost:631/ and add the lpd://f.q.d.n/queue printer, aunthenticating as root.<br />
<br />
*Go through "Manage Printer" and "Set Printer Options".<br />
<br />
*Print a test page (substitue color103 with the assigned printer name):<br />
$ lpq -P color103<br />
color103 is ready<br />
no entries<br />
<br />
==HP==<br />
===Deskjet 700 Series===<br />
====Printing does not work====<br />
The solution is to install '''pnm2ppa''' printer filter for the HP Deskjet 700 series. Without this, the print jobs will be aborted by the system. A [[Arch Build System|PKGBUILD]] for pnm2ppa can be found in [http://aur.archlinux.org/packages.php?do_Details=1&ID=696&O=0&L=0&C=0&K=pnm&SB=n&SO=a&PP=25&do_MyPackages=0&do_Orphans=0 AUR].<br />
<br />
=== HP LaserJet 1010 ===<br />
A solution to make LaserJet 1010 work with CUPS may be to compile a newer version of GhostScript:<br />
<pre><br />
$ pacman -Qs cups a2ps psutils foo ghost<br />
local/cups 1.1.23-3<br />
The CUPS Printing System<br />
local/a2ps 4.13b-3<br />
a2ps is an Any to PostScript filter<br />
local/psutils p17-3<br />
A set of postscript utilities.<br />
local/foomatic-db 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-db-engine 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-db-ppd 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-filters 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/espgs 8.15.1-1<br />
ESP Ghostscript<br />
</pre><br />
<br />
Setting <code>LogLevel</code> may also need to be set in {{Filename|/etc/cups/cupsd.conf}} to <code>debug2</code>, this way the logs will show how to circumvent minor issues, such as missing fonts. Search Google for [http://www.google.com/search?q=n019003l+filetype%3Apfb n019003l filetype:pfb]<br />
<br />
The debug solution might work if getting errors similar to 'Unsupport PCL', etc. See: [http://linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_1010 OpenPrinting database - Printer: HP LaserJet 1010]<br />
<br />
===LaserJet 1020===<br />
====Installation from AUR====<br />
Install the package foo2zjs from AUR and modify the {{Filename|PKGBUILD}}. Change the line:<br />
./getweb all<br />
to<br />
./getweb 1020<br />
<br />
If getting errors with incorrect md5sums, the md5sum of {{Filename|foo2zjs.tar.gz}} in the PKGBUILD should be changed to match the downloaded driver.<br />
<br />
As a last step, add and configure the printer in the CUPS manager. The printer should be recognized automatically, and function for both root and regular users.<br />
<br />
====Manual installation====<br />
{{Warning|This section involves installing packages without pacman. These directions should ideally be automated with a PKGBUILD in order to prevent issues.}}<br />
<br />
First of all, only CUPS and GhostScript needs to be installed. Then follow the links in [http://www.linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_1020 OpenPrinting database - Printer: HP LaserJet 1020] and [http://foo2zjs.rkkda.com/ foo2zjs: a linux printer driver for ZjStream protocol] to the printer driver page, and follow the install instructions. After login in as root, and downloading all the package and extracted the archives, change into the foo2zjs directory. Now, follow the regular installation instructions with a minor modification to change the 'userid' for printing:<br />
$ make<br />
$ ./getweb 1020<br />
<br />
Open the {{Filename|Makefile}}:<br />
$ nano Makefile<br />
and search for the line:<br />
# LPuid=-olp<br />
modify it to:<br />
# LPuid=-oroot<br />
then continue with the script:<br />
$ make install<br />
$ make install-hotplug<br />
$ make cups<br />
<br />
==Printer connected to an Airport Express Station==<br />
The first step is to scan the Airport Express station. It seems that there are different addresses depending on the model:<br />
<pre><br />
[root@somostation somos]# nmap 192.168.0.4<br />
<br />
Starting Nmap 4.20 ( http://insecure.org ) at 2007-06-26 00:50 CEST<br />
Interesting ports on 192.168.0.4:<br />
Not shown: 1694 closed ports<br />
PORT STATE SERVICE<br />
5000/tcp open UPnP<br />
9100/tcp open jetdirect<br />
10000/tcp open snet-sensor-mgmt<br />
MAC Address: 00:14:51:70:D5:66 (Apple Computer)<br />
<br />
Nmap finished: 1 IP address (1 host up) scanned in 25.815 seconds<br />
</pre><br />
<br />
The Airport station is accessed like an HP JetDirect printer. Afterwards, edit {{Filename|printer.conf}}:<br />
<pre><br />
# Printer configuration file for CUPS v1.2.11<br />
# Written by cupsd on 2007-06-26 00:44<br />
<Printer LaserSim><br />
Info SAMSUNG ML-1510 gdi<br />
Location SomoStation<br />
DeviceURI socket://192.168.0.4:9100<br />
State Idle<br />
StateTime 1182811465<br />
Accepting Yes<br />
Shared Yes<br />
JobSheets none none<br />
QuotaPeriod 0<br />
PageLimit 0<br />
KLimit 0<br />
OpPolicy default<br />
ErrorPolicy stop-printer<br />
</Printer><br />
</pre><br />
Problems may be resolved by removing foomatic and installing foomatic-db, foomatic-db-engine, foomatic-db-ppd instead.</div>Bhobbithttps://wiki.archlinux.org/index.php?title=CUPS&diff=100061CUPS2010-03-14T04:32:07Z<p>Bhobbit: Printer-specific problems moved to a separate page</p>
<hr />
<div>[[Category:Printers (English)]][[Category:HOWTOs (English)]]<br />
{{i18n|CUPS}}<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Installing and configuring CUPS}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|CUPS printer sharing}}<br />
{{Article summary wiki|CUPS printer-specific problems}}<br />
{{Article summary wiki|Samba}}<br />
{{Article summary end}}<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''CUPS is the standards-based, open source printing system developed by Apple Inc. for Mac OS® X and other UNIX®-like operating systems.''"<br />
Although there are other printing packages such as LPRNG, the ''C''ommon ''U''nix ''P''rinting ''S''ystem is the most popular choice because of its relative ease of use.<br />
<br />
==Installing==<br />
These packages are needed:<br />
# pacman -S cups ghostscript gsfonts<br />
<br />
* '''cups''' - The actual CUPS software<br />
* '''ghostscript''' - Interpreter for the Postscript language<br />
* '''gsfonts''' - GhostScript standard Type1 fonts<br />
* '''hal-cups-utils''' - This package might be needed. Read [http://bbs.archlinux.org/viewtopic.php?pid=655391#p655391 this forum post] for more information<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install Samba:<br />
# pacman -S samba<br />
<br />
===Printer driver===<br />
Here are some of the driver packages. Choosing the right driver depends on the printer:<br />
<br />
* '''gutenprint''' - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostSscript, CUPS, Foomatic, and the [[GIMP]]<br />
* '''foomatic-db, foomatic-db-engine, foomatic-db-nonfree, and foomatic-filters''' - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix. Installing foomatic-filters should solve problems if the cups error_log is reporting "stopped with status 22!".<br />
* '''hplip''' - HP GNU/Linux inkjet driver. Provides support for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models<br />
* '''splix''' - Samsung drivers for SPL (Samsung Printer Language) printers<br />
* '''ufr2''' - Canon UFR2 driver with support for LBP, iR and MF series printers. Package is available in the [[AUR]].<br />
* '''cups-pdf''' - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
<br />
If unsure of what driver package to install or if the current driver is not working, it may be easiest to just install all of drivers, since some of the packages are misleading because printers of other makes may rely on them. For instance, the Brother HL-2140 needs the hplip driver installed.<br />
# pacman -S gutenprint foomatic-db foomatic-db-engine \<br />
foomatic-db-nonfree foomatic-filters \<br />
hplip splix ufr2 cups-pdf<br />
<br />
====Download printer PPD====<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.linuxprinting.org/printer_list.cgi OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{Filename|/usr/share/cups/model/}}}}<br />
<br />
==Configuring==<br />
Now that CUPS is installed, there are a variety of options on how to setup printing solutions. As always, the tried and true command line method is at disposal. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. However, in order to make this process easy for the largest amount of users, this article will focus on the web interface provided by CUPS.<br />
<br />
Please note that if planning on connecting to a network printer, rather than one that is directly connected to the computer, read the [[#Printer sharing]] section first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
===Kernel modules===<br />
Before using the CUPS web interface, the appropriate kernel modules need to be installed. The following steps are from the Gentoo Printing Guide.<br />
<br />
This section may not be necessary, however, depending on which kernel is being used. The kernel module may load automatically after plugging in the printer. Use the {{Codeline|tail}} command (described below) to see if the printer has already been detected. The {{Codeline|lsmod}} utility can also be used to see what modules have been loaded.<br />
<br />
====USB printers====<br />
USB printer users may need to blacklist the {{codeline|usblp}} module. Keep in mind that there seems to be a lot of [http://bbs.archlinux.org/viewtopic.php?pid=660601 uncertainty] regarding blacklisting usblp, as some USB printers, including some Canon printer series, are not recognized without it. To disable the module, edit {{filename|rc.conf}} as shown:<br />
MODULES=(... '''!usblp''' ...)<br />
<br />
Custom kernel users may need to manually load the {{codeline|usbcore}} module before proceeding:<br />
# modprobe usbcore<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
The output should indicate that the printer has been detected:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
====Parallel port printers====<br />
If planning on using a parallel port printer, note that the configuration is pretty much the same, except for the modules:<br />
# modprobe lp<br />
# modprobe parport<br />
# modprobe parport_pc<br />
<br />
Once again, check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
====Auto-loading====<br />
It's convenient to have the system automatically load the kernel module every time the it starts up. To do so, use a text editor to open up {{Filename|/etc/[[rc.conf]]}} and add the appropriate module to the <code>MODULES=()</code> line. Here is an example:<br />
MODULES=(!usbserial scsi_mod sd_mod snd-ymfpci snd-pcm-oss '''lp parport parport_pc''' ide-scsi)<br />
<br />
===CUPS daemon===<br />
With the kernel modules installed, the system is now ready to start the actual CUPS daemon. To do this, simply run this command:<br />
# /etc/rc.d/cups start<br />
<br />
For automatically starting CUPS every time the system is powered on, add it to the <code>DAEMONS=()</code> line in the {{Filename|/etc/rc.conf}} file. For example:<br />
DAEMONS=(pcmcia syslogd klogd !fam esd mono network autofs '''cups''' crond gdm)<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{Filename|/etc/hosts}}).<br />
<br />
{{Tip|[[GNOME]] users may be inclined towards installing the GNOME CUPS manager GUI frontend. See: [[#Alternative CUPS interfaces]]}}<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a user-name and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label ( e.g., next to ''USB Printer #1'' for USB printers). Finally, chose the appropriate drivers and the configuration is complete.<br />
<br />
Now, test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
==== CUPS administration ====<br />
<br />
A user-name and password will be required when administrating the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default user-name is the one assigned in the ''sys'' group, or root (change this by editing {{Filename|/etc/cups/cupsd.conf}} in the line of ''SystemGroup''). <br />
<br />
If the root account has been locked, it is not possible to log in the CUPS administration interface with the default user-name and password. In this case, it may be needed to change the default SystemGroup in cupsd.conf and read [http://bbs.archlinux.org/viewtopic.php?id=35567 this post].<br />
<br />
====Remote access to web interface====<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{Filename|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
There are three levels of access that can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{codeline|Allow}} statement to that level's section. An {{codeline|Allow}} statement can take one or more of the forms listed below:<br />
Allow all<br />
Allow host.domain.com<br />
Allow *.domain.com<br />
Allow ip-address<br />
Allow ip-address/netmask<br />
<br />
Deny statements can also be used. For example, if wanting to give all hosts on the 192.168.1.0/255.255.255.0 subnet full access, file {{Filename|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
# Encryption disabled by default<br />
#Encryption Required<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
==Troubleshooting==<br />
The best way to get printing working is to set 'LogLevel' in {{Filename|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{Filename|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{Filename|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{Filename|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{Filename|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
===Problems resulting from upgrades===<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
====CUPS stops working====<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" my result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy /etc/cups/cupsd.conf.default to /etc/cups/cupsd.conf (backup the old the configuration if needed):<br />
# cp /etc/cups/cupsd.conf.default /etc/cups/cupsd.conf<br />
and restart CUPS to employ the new settings.<br />
<br />
====Error with gnutls====<br />
If receiving errors such as:<br />
/usr/sbin/cupsd: error while loading shared libraries: libgnutls.so.13: cannot open shared object file: No such file or directory<br />
gnutls may be in need of updating:<br />
# pacman -S gnutls<br />
<br />
After updating, there may be a file named {{Filename|cupsd.conf.pacnew}} in {{Filename|/etc/cups}}. This is the unmodified original configuration file that has been placed as part of the update. Compare it with the currently installed version and adjust to preference.<br />
<br />
====All jobs are "stopped"====<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
====The PPD version is not compatible with gutenprint====<br />
Run:<br />
# /usr/sbin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
===USB printers under CUPS 1.4.x===<br />
New CUPS 1.4.x introduces many changes:<br />
<br />
====Configuration file====<br />
The syntax of the configuration file cupsd.conf changed. Start with a new cupsd.conf file based on /etc/cups/cupsd.conf.default.<br />
<br />
====Blacklisting usblp====<br />
CUPS now uses libusb and printer USB devices (under /dev/bus/usb/) instead of the usblp generated /dev/usb/lpX ones. In order to get USB printers working, the usblp module needs disabling. This can be done by blacklisting it in /etc/rc.conf, or by adding "blacklist usblp" to a configuration file in /etc/modprobe.d. Some users have also reported that they needed to reinstall their printer.<br />
<br />
====Device node permissions====<br />
In addition to usblp not being loaded, CUPS also needs the ownership of the USB device file of the printer to be root:lp, and permissions to be 660. E.g.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
This is supposed to be achieved by two udev rules in /lib/udev/rules.d/50-udev-default.rules:<br />
# hplip and cups 1.4+ use raw USB devices, so permissions should be similar to<br />
# the ones from the old usblp kernel module<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}=="", IMPORT{program}="usb_id --export %p"<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}==":0701*:", GROUP="lp", MODE="660"<br />
<br />
However, for some devices, in particular combined printer/scanner devices, these rules either do not trigger, or are overwritten by rules of the 'sane' package. In these cases a custom udev rule needs to be added. See below.<br />
<br />
=====Device node permission troubleshooting=====<br />
Get the printer's device file and its permissions with: <br />
$ lsusb<br />
...<br />
Bus 003 Device 002: ID 04b8:0841 Seiko Epson Corp.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
If the permissions are not already root:lp 660, enforce it by creating a custom udev rule, e.g<br />
cat /etc/udev/rules.d/10-usbprinter.rules<br />
ATTR{idVendor}=="04b8", ATTR{idProduct}=="0841", MODE:="0660", GROUP:="lp"<br />
<br />
Note that idVendor and idProduct are from the lsusb listing above.<br />
<br />
=====Loading firmware=====<br />
<br />
Some printers and drivers need to load firmware to the printer (such as HP LaserJet 10xx printers using foo2zjs) and do this by writing directly to the lp device, a functionality provided by usblp. A work around until this issue is resolved is to install the usblp module until the firmware is loaded, then remove the module to allow CUPS to work. This can be accomplished by manually running "$ modprobe usblp", waiting for the firmware to load, then "$ rmmod usblp". You can also not blacklist usblp, then put "rmmod usblp" to /etc/rc.local, allowing the firmware to be loaded on boot before rc.local is run, then removing usblp.<br />
<br />
===Other===<br />
<br />
=====CUPS permission errors=====<br />
*Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
*Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
====HPLIP printer sends "/usr/lib/cups/backend/hp failed" error====<br />
Make sure dbus is installed and running, e.g. check DAEMONS in {{Filename|/etc/rc.conf}} or run {{Codeline|ls /var/run/daemons}}.<br />
<br />
====hp-toolbox sends an error, "Unable to communicate with device"====<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/<printer id><br />
or, "{{Codeline|Unable to communicate with device"}}", then it may be needed to add the user to the lp group by running the following command:<br />
# gpasswd -a <username> lp<br />
<br />
====CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer====<br />
If receiving any of the following error messages in {{Filename|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer "<printer_name>" not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure '''hplip''' has been installed, in addition to [[#Packages|the packages mentioned above]], '''net-snmp''' is also needed. See [http://bbs.archlinux.org/viewtopic.php?id=65615 this forum post].<br />
# pacman -S hplip<br />
<br />
====Printing fails with unauthorised error====<br />
If the user has been added to the lp group, and allowed to print (set in {{Filename|cups.conf}}), then the problem lies in {{Filename|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
====Print button greyed-out in GNOME print dialogs====<br />
:''<small>Source: [http://bbs.archlinux.org/viewtopic.php?id=70418 I can't print from gnome applications. - Arch Forums]</small>''<br />
<br />
Be sure the package: '''libgnomeprint''' is installed<br />
<br />
Edit {{filename|/etc/cups/cupsd.conf}} and add<br />
# HostNameLookups Double<br />
<br />
Restart CUPS:<br />
# /etc/rc.d/cups restart<br />
<br />
====CUPS fails to print with 'Unable to open device "hal:///[...]": Permission denied'====<br />
The permissions on some files are wrong:<br />
# cd /usr/lib/cups/backend<br />
# chmod 700 hal # (previously 755)<br />
# chmod 700 usb # (previously 755)<br />
<br />
====Unknown supported format: application/postscript====<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{Filename|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{Filename|/etc/cups/mime.types}}.<br />
<br />
====Finding URIs for Windows Print Servers====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
<pre> WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series</pre><br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
<br />
==Appendix==<br />
<br />
===Alternative CUPS interfaces===<br />
If using [[GNOME]], a possibility is to manage and configure the printer by using the gnome-cups-manager. This package is available through pacman: <br />
# pacman -S gnome-cups-manager<br />
<br />
Alternatively, system-config-printer-gnome can be installed:<br />
# pacman -S system-config-printer-gnome<br />
<br />
For system-config-printer to work as it should, running as root may be required, or alternatively set up a "normal" user to administer CUPS (if so '''follow steps 1-3''')<br />
<br />
* 1. Create group, and add a user<br />
# groupadd lpadmin<br />
# usermod -aG lpadmin <username><br />
<br />
* 2. Add "lpadmin" (without the quotes) to this line in {{Filename|/etc/cups/cupsd.conf}}<br />
SystemGroup sys root <insert here><br />
<br />
* 3. Restart cups, log out and in again (or restart computer)<br />
# /etc/rc.d/cups restart<br />
<br />
[[KDE]] users can modify their printers from the Control Center. Both should refer to those desktop environments' documentation for more information on how to use the interfaces.<br />
<br />
There is also gtklp:<br />
# pacman -S gtklp<br />
<br />
===Utility functions on Epson printers===<br />
<br />
====escputil====<br />
This section explains how to perform some of the utility functions (such as nozzle cleaning) on Epson printers, by using the escputil utility, part of the gutenprint package.<br />
<br />
There is a escputil's man-page provides basic information, but it does not touch on how to identify the printer. There are two parameters that can be used to do so:<br />
<br />
* One is <tt>--printer</tt>: it expects the name used to identify the printer when is was configured.<br />
<br />
* The other is <tt>--raw-device</tt>: this option expects a path beginning with "/dev". If the printer is the only serial printer on the system, "/dev/lp0" should be its device node. For USB printers, it is "/dev/usb/lp0". If having more than one printer, they will have names ending in "lp1", "lp2", etc.<br />
<br />
On to the maintenance options:<br />
* To clean the printer heads:<br />
$ escputil -u --clean-head<br />
<br />
* To print the nozzle-check pattern (allows verifying that the previous head cleaning worked, and determining the heads need cleaning):<br />
$ escputil -u --nozzle-check<br />
<br />
If wanting to perform an operation that requires two-way communication with a printer, use the "--raw-device" specification and the user must be root or be a member of the group "lp".<br />
<br />
* The following is an example of getting the printer's internal identification:<br />
$ sudo escputil --raw-device=/dev/usb/lp0 --identify<br />
<br />
* To print out the ink levels of the printer:<br />
$ sudo escputil --raw-device=/dev/usb/lp0 --ink-level<br />
<br />
====mtink====<br />
This is a printer status monitor which enables to get the remaining ink quantity, to print test patterns, to reset printer and to clean nozzle. It use an intuitive graphical user interface. Package can be downloaded from [http://aur.archlinux.org/packages.php?do_Details=1&ID=476&O=0&L=0&C=0&K=mtink&SB=n&SO=a&PP=25&do_MyPackages=0&do_Orphans=0&SeB=nd AUR].<br />
<br />
====Stylus-toolbox====<br />
This is a GUI using escputil and cups drivers. It supports nearly all USB printer of Epson and displays ink quantity, can clean and align print heads and print test patterns. It can be downloaded from [http://aur.archlinux.org/packages.php?ID=30319 AUR]<br />
<br />
===PDF virtual printer===<br />
CUPS-PDF is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. Obviously this package is not necessary, but it can be quite useful.<br />
<br />
Find generated PDF documents in a sub-directory located at <code>/var/spool/cups-pdf</code>. Normally, the subdirectory is named after the user who performed the job.<br />
<br />
This package can be installed by the following command:<br />
# pacman -S cups-pdf<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. For the Device, select '''CUPS-PDF (Virtual PDF Printer)'''; Make/Manufacturer, choose '''Generic'''; Model/Driver, select '''Generic postscript color printer'''. Alternatively, provide the PPD file from [http://www.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/cups-pdf-CURRENT/extra/CUPS-PDF.ppd this link].<br />
<br />
====Print to postscript: CUPS-PDF virtual printer trick====<br />
Printing to PDF in most applications like OpenOffice is no problem; just hit the button. Yet when printing out to postscript, matters take a little more work. For applications like OpenOffice where printing to kprinter is nebulous at best, there has to be another way -- and there is. The CUPS-PDF (Virtual PDF Printer) actually creates a postscript file and then creates the PDF using the ps2pdf utility. To print to postscript, what needs to be done is capturing the intermediate postscript file created by CUPS-PDF. This is easily accomplished with by selecting the "print to file" option in the print dialog. (choose either .ps or .eps as the extension) After selecting the "print to file" checkbox simply enter the filename and click "print".<br />
<br />
=====Configuring CUPS-PDF virtual printer=====<br />
1. Install cups & cups-pdf from extra.<br />
<br />
2. Start cups with:<br />
# /etc/rc.d/cups <br />
<br />
{{Note|Add 'cups' to the deamons line in /etc/rc.conf to start automatically at boot.}}<br />
<br />
3. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Find New Printers<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Now to print to postscript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
===Another source for printer drivers===<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
==Resources==<br />
* [http://localhost:631/documentation.html Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS Website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://home.nyc.rr.com/computertaijutsu/cups.html Tips and Suggestions on common CUPS problems], '''(Dead link)'''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's Printing Guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation Resources]''<br />
* [http://bbs.archlinux.org/ Arch Linux User Forums]<br />
<br />
{{Wikipedia|Common Unix Printing System}}</div>Bhobbithttps://wiki.archlinux.org/index.php?title=CUPS/Printer-specific_problems&diff=100060CUPS/Printer-specific problems2010-03-14T04:30:15Z<p>Bhobbit: Moved printer-specific problems to a separate page from CUPS</p>
<hr />
<div>[[Category:Printers (English)]][[Category:HOWTOs (English)]]<br />
{{i18n|CUPS printer-specific problems}}<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Dealing with printer-specific problems}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|CUPS}}<br />
{{Article summary end}}<br />
<br />
Printer-specific problems and their solutions.<br />
<br />
==Brother==<br />
<br />
===DCP 7020===<br />
See: [[Brother DCP-7020]]<br />
<br />
==Canon==<br />
===MF 4150===<br />
This is required as some Canon printers apparently do not declare their specification correctly for kernel and libusb to recognize them<br />
<br />
* Do NOT blacklist usblp module.<br />
<br />
* Install hal-cups-utils and restart hal<br />
# sudo pacman -S hal-cups-utils<br />
# sudo /etc/rc.d/hal restart<br />
<br />
* Connect the printer<br />
<br />
The printer should now be recognized by the CUPS Add printer dialog. If still having problems, try restarting CUPS.<br />
<br />
* Install UFRII driver ({{Package AUR|ufr2}} from the [[AUR]] and complete the printer installation.<br />
<br />
==Epson==<br />
===AcuLaser CX11(NF)===<br />
Install [http://aur.archlinux.org/packages.php?ID=30424 Epson-ALCX11-filter] from the AUR. Restart CUPS and add the printer using the driver "EPSON AL-CX11, ESC/PageS Filter".<br />
<br />
Both connections, USB and network, should work as expected.<br />
<br />
==FX==<br />
=== C1110 (not model B)===<br />
Keep in mind that these directions assume that the printer is connected and listening on the network.<br />
<br />
*Install cpio and rpmunpack to later unpack the package:<br />
# pacman -S cpio rpmunpack cups ghostscript gsfonts<br />
<br />
*Get the FX GNU/Linux driver [http://www.fujixeroxprinters.com/downloads/uploaded/Drivers/DocuPrint%20C1110%20C1110B/linux/fxlinuxprint-1.0.1-1.i386.zip here].<br />
<br />
*Unzip {{Filename|fxlinuxprint-1.0.1-1.i386.zip}} to /var/tmp (the directory is not important):<br />
$ unzip fxlinuxprint-1.0.1-1.i386.zip -d /var/tmp<br />
<br />
*Continue extracting the file:<br />
$ cd /var/tmp<br />
$ rpmunpack fxlinuxprint-1.0.1-1.i386.rpm<br />
$ gunzip fxlinuxprint-1.0.1-1.cpio.gz<br />
<br />
*Move the cpio DST file (for convenience):<br />
$ mkdir /var/tmp/DST<br />
$ mv fxlinuxprint-1.0.1-1.cpio /var/tmp/DST<br />
<br />
*Extract it:<br />
$ cd /var/tmp/DST<br />
$ cpio -id < fxlinuxprint-1.0.1-1.cpio<br />
<br />
*Filter the relevant files:<br />
$ cd /var/tmp<br />
$ find /var/tmp/DST -type f |cat -n<br />
1 /var/tmp/DST/etc/cups/mimefx.convs<br />
2 /var/tmp/DST/etc/cups/mimefx.types<br />
3 /var/tmp/DST/usr/lib/cups/filter/pdftopjlfx<br />
4 /var/tmp/DST/usr/lib/cups/filter/pstopdffx<br />
5 /var/tmp/DST/usr/lib/cups/filter/pdftopdffx<br />
6 /var/tmp/DST/usr/share/cups/model/FujiXerox/en/fxlinuxprint.ppd<br />
<br />
*Copy the files found in the previous step to /<br />
{{Note|For the PPD use {{Filename|/usr/share/cups/model/fxlinuxprint.ppd}}}}<br />
<br />
*Access http://localhost:631/ and add the lpd://f.q.d.n/queue printer, aunthenticating as root.<br />
<br />
*Go through "Manage Printer" and "Set Printer Options".<br />
<br />
*Print a test page (substitue color103 with the assigned printer name):<br />
$ lpq -P color103<br />
color103 is ready<br />
no entries<br />
<br />
==HP==<br />
===Deskjet 700 Series===<br />
====Printing does not work====<br />
The solution is to install '''pnm2ppa''' printer filter for the HP Deskjet 700 series. Without this, the print jobs will be aborted by the system. A [[Arch Build System|PKGBUILD]] for pnm2ppa can be found in [http://aur.archlinux.org/packages.php?do_Details=1&ID=696&O=0&L=0&C=0&K=pnm&SB=n&SO=a&PP=25&do_MyPackages=0&do_Orphans=0 AUR].<br />
<br />
=== HP LaserJet 1010 ===<br />
A solution to make LaserJet 1010 work with CUPS may be to compile a newer version of GhostScript:<br />
<pre><br />
$ pacman -Qs cups a2ps psutils foo ghost<br />
local/cups 1.1.23-3<br />
The CUPS Printing System<br />
local/a2ps 4.13b-3<br />
a2ps is an Any to PostScript filter<br />
local/psutils p17-3<br />
A set of postscript utilities.<br />
local/foomatic-db 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-db-engine 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-db-ppd 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-filters 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/espgs 8.15.1-1<br />
ESP Ghostscript<br />
</pre><br />
<br />
Setting <code>LogLevel</code> may also need to be set in {{Filename|/etc/cups/cupsd.conf}} to <code>debug2</code>, this way the logs will show how to circumvent minor issues, such as missing fonts. Search Google for [http://www.google.com/search?q=n019003l+filetype%3Apfb n019003l filetype:pfb]<br />
<br />
The debug solution might work if getting errors similar to 'Unsupport PCL', etc. See: [http://linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_1010 OpenPrinting database - Printer: HP LaserJet 1010]<br />
<br />
===LaserJet 1020===<br />
====Installation from AUR====<br />
Install the package foo2zjs from AUR and modify the {{Filename|PKGBUILD}}. Change the line:<br />
./getweb all<br />
to<br />
./getweb 1020<br />
<br />
If getting errors with incorrect md5sums, the md5sum of {{Filename|foo2zjs.tar.gz}} in the PKGBUILD should be changed to match the downloaded driver.<br />
<br />
As a last step, add and configure the printer in the CUPS manager. The printer should be recognized automatically, and function for both root and regular users.<br />
<br />
====Manual installation====<br />
{{Warning|This section involves installing packages without pacman. These directions should ideally be automated with a PKGBUILD in order to prevent issues.}}<br />
<br />
First of all, only CUPS and GhostScript needs to be installed. Then follow the links in [http://www.linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_1020 OpenPrinting database - Printer: HP LaserJet 1020] and [http://foo2zjs.rkkda.com/ foo2zjs: a linux printer driver for ZjStream protocol] to the printer driver page, and follow the install instructions. After login in as root, and downloading all the package and extracted the archives, change into the foo2zjs directory. Now, follow the regular installation instructions with a minor modification to change the 'userid' for printing:<br />
$ make<br />
$ ./getweb 1020<br />
<br />
Open the {{Filename|Makefile}}:<br />
$ nano Makefile<br />
and search for the line:<br />
# LPuid=-olp<br />
modify it to:<br />
# LPuid=-oroot<br />
then continue with the script:<br />
$ make install<br />
$ make install-hotplug<br />
$ make cups<br />
<br />
==Printer connected to an Airport Express Station==<br />
The first step is to scan the Airport Express station. It seems that there are different addresses depending on the model:<br />
<pre><br />
[root@somostation somos]# nmap 192.168.0.4<br />
<br />
Starting Nmap 4.20 ( http://insecure.org ) at 2007-06-26 00:50 CEST<br />
Interesting ports on 192.168.0.4:<br />
Not shown: 1694 closed ports<br />
PORT STATE SERVICE<br />
5000/tcp open UPnP<br />
9100/tcp open jetdirect<br />
10000/tcp open snet-sensor-mgmt<br />
MAC Address: 00:14:51:70:D5:66 (Apple Computer)<br />
<br />
Nmap finished: 1 IP address (1 host up) scanned in 25.815 seconds<br />
</pre><br />
<br />
The Airport station is accessed like an HP JetDirect printer. Afterwards, edit {{Filename|printer.conf}}:<br />
<pre><br />
# Printer configuration file for CUPS v1.2.11<br />
# Written by cupsd on 2007-06-26 00:44<br />
<Printer LaserSim><br />
Info SAMSUNG ML-1510 gdi<br />
Location SomoStation<br />
DeviceURI socket://192.168.0.4:9100<br />
State Idle<br />
StateTime 1182811465<br />
Accepting Yes<br />
Shared Yes<br />
JobSheets none none<br />
QuotaPeriod 0<br />
PageLimit 0<br />
KLimit 0<br />
OpPolicy default<br />
ErrorPolicy stop-printer<br />
</Printer><br />
</pre><br />
Problems may be resolved by removing foomatic and installing foomatic-db, foomatic-db-engine, foomatic-db-ppd instead.</div>Bhobbithttps://wiki.archlinux.org/index.php?title=CUPS&diff=100057CUPS2010-03-14T04:18:08Z<p>Bhobbit: This page has become too unwieldy, so I moved printer sharing to its own page</p>
<hr />
<div>[[Category:Printers (English)]][[Category:HOWTOs (English)]]<br />
{{i18n|CUPS}}<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Installing and configuring CUPS}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|CUPS printer sharing}}<br />
{{Article summary wiki|Samba}}<br />
{{Article summary end}}<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''CUPS is the standards-based, open source printing system developed by Apple Inc. for Mac OS® X and other UNIX®-like operating systems.''"<br />
Although there are other printing packages such as LPRNG, the ''C''ommon ''U''nix ''P''rinting ''S''ystem is the most popular choice because of its relative ease of use.<br />
<br />
==Installing==<br />
These packages are needed:<br />
# pacman -S cups ghostscript gsfonts<br />
<br />
* '''cups''' - The actual CUPS software<br />
* '''ghostscript''' - Interpreter for the Postscript language<br />
* '''gsfonts''' - GhostScript standard Type1 fonts<br />
* '''hal-cups-utils''' - This package might be needed. Read [http://bbs.archlinux.org/viewtopic.php?pid=655391#p655391 this forum post] for more information<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install Samba:<br />
# pacman -S samba<br />
<br />
===Printer driver===<br />
Here are some of the driver packages. Choosing the right driver depends on the printer:<br />
<br />
* '''gutenprint''' - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostSscript, CUPS, Foomatic, and the [[GIMP]]<br />
* '''foomatic-db, foomatic-db-engine, foomatic-db-nonfree, and foomatic-filters''' - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix. Installing foomatic-filters should solve problems if the cups error_log is reporting "stopped with status 22!".<br />
* '''hplip''' - HP GNU/Linux inkjet driver. Provides support for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models<br />
* '''splix''' - Samsung drivers for SPL (Samsung Printer Language) printers<br />
* '''ufr2''' - Canon UFR2 driver with support for LBP, iR and MF series printers. Package is available in the [[AUR]].<br />
* '''cups-pdf''' - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
<br />
If unsure of what driver package to install or if the current driver is not working, it may be easiest to just install all of drivers, since some of the packages are misleading because printers of other makes may rely on them. For instance, the Brother HL-2140 needs the hplip driver installed.<br />
# pacman -S gutenprint foomatic-db foomatic-db-engine \<br />
foomatic-db-nonfree foomatic-filters \<br />
hplip splix ufr2 cups-pdf<br />
<br />
====Download printer PPD====<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.linuxprinting.org/printer_list.cgi OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{Filename|/usr/share/cups/model/}}}}<br />
<br />
==Configuring==<br />
Now that CUPS is installed, there are a variety of options on how to setup printing solutions. As always, the tried and true command line method is at disposal. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. However, in order to make this process easy for the largest amount of users, this article will focus on the web interface provided by CUPS.<br />
<br />
Please note that if planning on connecting to a network printer, rather than one that is directly connected to the computer, read the [[#Printer sharing]] section first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
===Kernel modules===<br />
Before using the CUPS web interface, the appropriate kernel modules need to be installed. The following steps are from the Gentoo Printing Guide.<br />
<br />
This section may not be necessary, however, depending on which kernel is being used. The kernel module may load automatically after plugging in the printer. Use the {{Codeline|tail}} command (described below) to see if the printer has already been detected. The {{Codeline|lsmod}} utility can also be used to see what modules have been loaded.<br />
<br />
====USB printers====<br />
USB printer users may need to blacklist the {{codeline|usblp}} module. Keep in mind that there seems to be a lot of [http://bbs.archlinux.org/viewtopic.php?pid=660601 uncertainty] regarding blacklisting usblp, as some USB printers, including some Canon printer series, are not recognized without it. To disable the module, edit {{filename|rc.conf}} as shown:<br />
MODULES=(... '''!usblp''' ...)<br />
<br />
Custom kernel users may need to manually load the {{codeline|usbcore}} module before proceeding:<br />
# modprobe usbcore<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
The output should indicate that the printer has been detected:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
====Parallel port printers====<br />
If planning on using a parallel port printer, note that the configuration is pretty much the same, except for the modules:<br />
# modprobe lp<br />
# modprobe parport<br />
# modprobe parport_pc<br />
<br />
Once again, check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
====Auto-loading====<br />
It's convenient to have the system automatically load the kernel module every time the it starts up. To do so, use a text editor to open up {{Filename|/etc/[[rc.conf]]}} and add the appropriate module to the <code>MODULES=()</code> line. Here is an example:<br />
MODULES=(!usbserial scsi_mod sd_mod snd-ymfpci snd-pcm-oss '''lp parport parport_pc''' ide-scsi)<br />
<br />
===CUPS daemon===<br />
With the kernel modules installed, the system is now ready to start the actual CUPS daemon. To do this, simply run this command:<br />
# /etc/rc.d/cups start<br />
<br />
For automatically starting CUPS every time the system is powered on, add it to the <code>DAEMONS=()</code> line in the {{Filename|/etc/rc.conf}} file. For example:<br />
DAEMONS=(pcmcia syslogd klogd !fam esd mono network autofs '''cups''' crond gdm)<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{Filename|/etc/hosts}}).<br />
<br />
{{Tip|[[GNOME]] users may be inclined towards installing the GNOME CUPS manager GUI frontend. See: [[#Alternative CUPS interfaces]]}}<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a user-name and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label ( e.g., next to ''USB Printer #1'' for USB printers). Finally, chose the appropriate drivers and the configuration is complete.<br />
<br />
Now, test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
==== CUPS administration ====<br />
<br />
A user-name and password will be required when administrating the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default user-name is the one assigned in the ''sys'' group, or root (change this by editing {{Filename|/etc/cups/cupsd.conf}} in the line of ''SystemGroup''). <br />
<br />
If the root account has been locked, it is not possible to log in the CUPS administration interface with the default user-name and password. In this case, it may be needed to change the default SystemGroup in cupsd.conf and read [http://bbs.archlinux.org/viewtopic.php?id=35567 this post].<br />
<br />
====Remote access to web interface====<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{Filename|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
There are three levels of access that can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{codeline|Allow}} statement to that level's section. An {{codeline|Allow}} statement can take one or more of the forms listed below:<br />
Allow all<br />
Allow host.domain.com<br />
Allow *.domain.com<br />
Allow ip-address<br />
Allow ip-address/netmask<br />
<br />
Deny statements can also be used. For example, if wanting to give all hosts on the 192.168.1.0/255.255.255.0 subnet full access, file {{Filename|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
# Encryption disabled by default<br />
#Encryption Required<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
==Troubleshooting==<br />
The best way to get printing working is to set 'LogLevel' in {{Filename|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{Filename|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{Filename|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{Filename|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{Filename|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
===Problems resulting from upgrades===<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
====CUPS stops working====<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" my result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy /etc/cups/cupsd.conf.default to /etc/cups/cupsd.conf (backup the old the configuration if needed):<br />
# cp /etc/cups/cupsd.conf.default /etc/cups/cupsd.conf<br />
and restart CUPS to employ the new settings.<br />
<br />
====Error with gnutls====<br />
If receiving errors such as:<br />
/usr/sbin/cupsd: error while loading shared libraries: libgnutls.so.13: cannot open shared object file: No such file or directory<br />
gnutls may be in need of updating:<br />
# pacman -S gnutls<br />
<br />
After updating, there may be a file named {{Filename|cupsd.conf.pacnew}} in {{Filename|/etc/cups}}. This is the unmodified original configuration file that has been placed as part of the update. Compare it with the currently installed version and adjust to preference.<br />
<br />
====All jobs are "stopped"====<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
====The PPD version is not compatible with gutenprint====<br />
Run:<br />
# /usr/sbin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
===USB printers under CUPS 1.4.x===<br />
New CUPS 1.4.x introduces many changes:<br />
<br />
====Configuration file====<br />
The syntax of the configuration file cupsd.conf changed. Start with a new cupsd.conf file based on /etc/cups/cupsd.conf.default.<br />
<br />
====Blacklisting usblp====<br />
CUPS now uses libusb and printer USB devices (under /dev/bus/usb/) instead of the usblp generated /dev/usb/lpX ones. In order to get USB printers working, the usblp module needs disabling. This can be done by blacklisting it in /etc/rc.conf, or by adding "blacklist usblp" to a configuration file in /etc/modprobe.d. Some users have also reported that they needed to reinstall their printer.<br />
<br />
====Device node permissions====<br />
In addition to usblp not being loaded, CUPS also needs the ownership of the USB device file of the printer to be root:lp, and permissions to be 660. E.g.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
This is supposed to be achieved by two udev rules in /lib/udev/rules.d/50-udev-default.rules:<br />
# hplip and cups 1.4+ use raw USB devices, so permissions should be similar to<br />
# the ones from the old usblp kernel module<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}=="", IMPORT{program}="usb_id --export %p"<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}==":0701*:", GROUP="lp", MODE="660"<br />
<br />
However, for some devices, in particular combined printer/scanner devices, these rules either do not trigger, or are overwritten by rules of the 'sane' package. In these cases a custom udev rule needs to be added. See below.<br />
<br />
=====Device node permission troubleshooting=====<br />
Get the printer's device file and its permissions with: <br />
$ lsusb<br />
...<br />
Bus 003 Device 002: ID 04b8:0841 Seiko Epson Corp.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
If the permissions are not already root:lp 660, enforce it by creating a custom udev rule, e.g<br />
cat /etc/udev/rules.d/10-usbprinter.rules<br />
ATTR{idVendor}=="04b8", ATTR{idProduct}=="0841", MODE:="0660", GROUP:="lp"<br />
<br />
Note that idVendor and idProduct are from the lsusb listing above.<br />
<br />
=====Loading firmware=====<br />
<br />
Some printers and drivers need to load firmware to the printer (such as HP LaserJet 10xx printers using foo2zjs) and do this by writing directly to the lp device, a functionality provided by usblp. A work around until this issue is resolved is to install the usblp module until the firmware is loaded, then remove the module to allow CUPS to work. This can be accomplished by manually running "$ modprobe usblp", waiting for the firmware to load, then "$ rmmod usblp". You can also not blacklist usblp, then put "rmmod usblp" to /etc/rc.local, allowing the firmware to be loaded on boot before rc.local is run, then removing usblp.<br />
<br />
===Other===<br />
<br />
=====CUPS permission errors=====<br />
*Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
*Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
====HPLIP printer sends "/usr/lib/cups/backend/hp failed" error====<br />
Make sure dbus is installed and running, e.g. check DAEMONS in {{Filename|/etc/rc.conf}} or run {{Codeline|ls /var/run/daemons}}.<br />
<br />
====hp-toolbox sends an error, "Unable to communicate with device"====<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/<printer id><br />
or, "{{Codeline|Unable to communicate with device"}}", then it may be needed to add the user to the lp group by running the following command:<br />
# gpasswd -a <username> lp<br />
<br />
====CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer====<br />
If receiving any of the following error messages in {{Filename|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer "<printer_name>" not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure '''hplip''' has been installed, in addition to [[#Packages|the packages mentioned above]], '''net-snmp''' is also needed. See [http://bbs.archlinux.org/viewtopic.php?id=65615 this forum post].<br />
# pacman -S hplip<br />
<br />
====Printing fails with unauthorised error====<br />
If the user has been added to the lp group, and allowed to print (set in {{Filename|cups.conf}}), then the problem lies in {{Filename|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
====Print button greyed-out in GNOME print dialogs====<br />
:''<small>Source: [http://bbs.archlinux.org/viewtopic.php?id=70418 I can't print from gnome applications. - Arch Forums]</small>''<br />
<br />
Be sure the package: '''libgnomeprint''' is installed<br />
<br />
Edit {{filename|/etc/cups/cupsd.conf}} and add<br />
# HostNameLookups Double<br />
<br />
Restart CUPS:<br />
# /etc/rc.d/cups restart<br />
<br />
====CUPS fails to print with 'Unable to open device "hal:///[...]": Permission denied'====<br />
The permissions on some files are wrong:<br />
# cd /usr/lib/cups/backend<br />
# chmod 700 hal # (previously 755)<br />
# chmod 700 usb # (previously 755)<br />
<br />
====Unknown supported format: application/postscript====<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{Filename|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{Filename|/etc/cups/mime.types}}.<br />
<br />
====Finding URIs for Windows Print Servers====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
<pre> WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series</pre><br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
<br />
===Printer-specific===<br />
''Printer-specific problems and their solutions''<br />
<br />
<br />
<br />
====Brother DCP 7020====<br />
See: [[Brother DCP-7020]]<br />
<br />
====Canon MF 4150====<br />
This is required as some Canon printers apparently do not declare their specification correctly for kernel and libusb to recognize them<br />
<br />
* Do NOT blacklist usblp module.<br />
<br />
* Install hal-cups-utils and restart hal<br />
# sudo pacman -S hal-cups-utils<br />
# sudo /etc/rc.d/hal restart<br />
<br />
* Connect the printer<br />
<br />
The printer should now be recognized by the CUPS Add printer dialog. If still having problems, try restarting CUPS.<br />
<br />
* Install UFRII driver ({{Package AUR|ufr2}} from the [[AUR]] and complete the printer installation.<br />
<br />
====Epson AcuLaser CX11(NF)====<br />
Install [http://aur.archlinux.org/packages.php?ID=30424 Epson-ALCX11-filter] from the AUR. Restart CUPS and add the printer using the driver "EPSON AL-CX11, ESC/PageS Filter".<br />
<br />
Both connections, USB and network, should work as expected.<br />
<br />
====FX C1110 (not model B)====<br />
Keep in mind that these directions assume that the printer is connected and listening on the network.<br />
<br />
*Install cpio and rpmunpack to later unpack the package:<br />
# pacman -S cpio rpmunpack cups ghostscript gsfonts<br />
<br />
*Get the FX GNU/Linux driver [http://www.fujixeroxprinters.com/downloads/uploaded/Drivers/DocuPrint%20C1110%20C1110B/linux/fxlinuxprint-1.0.1-1.i386.zip here].<br />
<br />
*Unzip {{Filename|fxlinuxprint-1.0.1-1.i386.zip}} to /var/tmp (the directory is not important):<br />
$ unzip fxlinuxprint-1.0.1-1.i386.zip -d /var/tmp<br />
<br />
*Continue extracting the file:<br />
$ cd /var/tmp<br />
$ rpmunpack fxlinuxprint-1.0.1-1.i386.rpm<br />
$ gunzip fxlinuxprint-1.0.1-1.cpio.gz<br />
<br />
*Move the cpio DST file (for convenience):<br />
$ mkdir /var/tmp/DST<br />
$ mv fxlinuxprint-1.0.1-1.cpio /var/tmp/DST<br />
<br />
*Extract it:<br />
$ cd /var/tmp/DST<br />
$ cpio -id < fxlinuxprint-1.0.1-1.cpio<br />
<br />
*Filter the relevant files:<br />
$ cd /var/tmp<br />
$ find /var/tmp/DST -type f |cat -n<br />
1 /var/tmp/DST/etc/cups/mimefx.convs<br />
2 /var/tmp/DST/etc/cups/mimefx.types<br />
3 /var/tmp/DST/usr/lib/cups/filter/pdftopjlfx<br />
4 /var/tmp/DST/usr/lib/cups/filter/pstopdffx<br />
5 /var/tmp/DST/usr/lib/cups/filter/pdftopdffx<br />
6 /var/tmp/DST/usr/share/cups/model/FujiXerox/en/fxlinuxprint.ppd<br />
<br />
*Copy the files found in the previous step to /<br />
{{Note|For the PPD use {{Filename|/usr/share/cups/model/fxlinuxprint.ppd}}}}<br />
<br />
*Access http://localhost:631/ and add the lpd://f.q.d.n/queue printer, aunthenticating as root.<br />
<br />
*Go through "Manage Printer" and "Set Printer Options".<br />
<br />
*Print a test page (substitue color103 with the assigned printer name):<br />
$ lpq -P color103<br />
color103 is ready<br />
no entries<br />
<br />
====Printing does not work with the HP Deskjet 700 Series====<br />
The solution is to install '''pnm2ppa''' printer filter for the HP Deskjet 700 series. Without this, the print jobs will be aborted by the system. A [[Arch Build System|PKGBUILD]] for pnm2ppa can be found in [http://aur.archlinux.org/packages.php?do_Details=1&ID=696&O=0&L=0&C=0&K=pnm&SB=n&SO=a&PP=25&do_MyPackages=0&do_Orphans=0 AUR].<br />
<br />
====Getting HP LaserJet 1010 to work====<br />
A solution may be to compile a newer version of GhostScript:<br />
<pre><br />
$ pacman -Qs cups a2ps psutils foo ghost<br />
local/cups 1.1.23-3<br />
The CUPS Printing System<br />
local/a2ps 4.13b-3<br />
a2ps is an Any to PostScript filter<br />
local/psutils p17-3<br />
A set of postscript utilities.<br />
local/foomatic-db 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-db-engine 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-db-ppd 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-filters 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/espgs 8.15.1-1<br />
ESP Ghostscript<br />
</pre><br />
<br />
Setting <code>LogLevel</code> may also need to be set in {{Filename|/etc/cups/cupsd.conf}} to <code>debug2</code>, this way the logs will show how to circumvent minor issues, such as missing fonts. Search Google for [http://www.google.com/search?q=n019003l+filetype%3Apfb n019003l filetype:pfb]<br />
<br />
The debug solution might work if getting errors similar to 'Unsupport PCL', etc. See: [http://linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_1010 OpenPrinting database - Printer: HP LaserJet 1010]<br />
<br />
====HP LaserJet 1020====<br />
<br />
=====Installation from AUR=====<br />
Install the package foo2zjs from AUR and modify the {{Filename|PKGBUILD}}. Change the line:<br />
./getweb all<br />
to<br />
./getweb 1020<br />
<br />
If getting errors with incorrect md5sums, the md5sum of {{Filename|foo2zjs.tar.gz}} in the PKGBUILD should be changed to match the downloaded driver.<br />
<br />
As a last step, add and configure the printer in the CUPS manager. The printer should be recognized automatically, and function for both root and regular users.<br />
<br />
=====Manual installation=====<br />
{{Warning|This section involves installing packages without pacman. These directions should ideally be automated with a PKGBUILD in order to prevent issues.}}<br />
<br />
First of all, only CUPS and GhostScript needs to be installed. Then follow the links in [http://www.linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_1020 OpenPrinting database - Printer: HP LaserJet 1020] and [http://foo2zjs.rkkda.com/ foo2zjs: a linux printer driver for ZjStream protocol] to the printer driver page, and follow the install instructions. After login in as root, and downloading all the package and extracted the archives, change into the foo2zjs directory. Now, follow the regular installation instructions with a minor modification to change the 'userid' for printing:<br />
$ make<br />
$ ./getweb 1020<br />
<br />
Open the {{Filename|Makefile}}:<br />
$ nano Makefile<br />
and search for the line:<br />
# LPuid=-olp<br />
modify it to:<br />
# LPuid=-oroot<br />
then continue with the script:<br />
$ make install<br />
$ make install-hotplug<br />
$ make cups<br />
<br />
====Printer connected to an Airport Express Station====<br />
The first step is to scan the Airport Express station. It seems that there are different addresses depending on the model:<br />
<pre><br />
[root@somostation somos]# nmap 192.168.0.4<br />
<br />
Starting Nmap 4.20 ( http://insecure.org ) at 2007-06-26 00:50 CEST<br />
Interesting ports on 192.168.0.4:<br />
Not shown: 1694 closed ports<br />
PORT STATE SERVICE<br />
5000/tcp open UPnP<br />
9100/tcp open jetdirect<br />
10000/tcp open snet-sensor-mgmt<br />
MAC Address: 00:14:51:70:D5:66 (Apple Computer)<br />
<br />
Nmap finished: 1 IP address (1 host up) scanned in 25.815 seconds<br />
</pre><br />
<br />
The Airport station is accessed like an HP JetDirect printer. Afterwards, edit {{Filename|printer.conf}}:<br />
<pre><br />
# Printer configuration file for CUPS v1.2.11<br />
# Written by cupsd on 2007-06-26 00:44<br />
<Printer LaserSim><br />
Info SAMSUNG ML-1510 gdi<br />
Location SomoStation<br />
DeviceURI socket://192.168.0.4:9100<br />
State Idle<br />
StateTime 1182811465<br />
Accepting Yes<br />
Shared Yes<br />
JobSheets none none<br />
QuotaPeriod 0<br />
PageLimit 0<br />
KLimit 0<br />
OpPolicy default<br />
ErrorPolicy stop-printer<br />
</Printer><br />
</pre><br />
Problems may be resolved by removing foomatic and installing foomatic-db, foomatic-db-engine, foomatic-db-ppd instead.<br />
<br />
==Appendix==<br />
<br />
===Alternative CUPS interfaces===<br />
If using [[GNOME]], a possibility is to manage and configure the printer by using the gnome-cups-manager. This package is available through pacman: <br />
# pacman -S gnome-cups-manager<br />
<br />
Alternatively, system-config-printer-gnome can be installed:<br />
# pacman -S system-config-printer-gnome<br />
<br />
For system-config-printer to work as it should, running as root may be required, or alternatively set up a "normal" user to administer CUPS (if so '''follow steps 1-3''')<br />
<br />
* 1. Create group, and add a user<br />
# groupadd lpadmin<br />
# usermod -aG lpadmin <username><br />
<br />
* 2. Add "lpadmin" (without the quotes) to this line in {{Filename|/etc/cups/cupsd.conf}}<br />
SystemGroup sys root <insert here><br />
<br />
* 3. Restart cups, log out and in again (or restart computer)<br />
# /etc/rc.d/cups restart<br />
<br />
[[KDE]] users can modify their printers from the Control Center. Both should refer to those desktop environments' documentation for more information on how to use the interfaces.<br />
<br />
There is also gtklp:<br />
# pacman -S gtklp<br />
<br />
===Utility functions on Epson printers===<br />
<br />
====escputil====<br />
This section explains how to perform some of the utility functions (such as nozzle cleaning) on Epson printers, by using the escputil utility, part of the gutenprint package.<br />
<br />
There is a escputil's man-page provides basic information, but it does not touch on how to identify the printer. There are two parameters that can be used to do so:<br />
<br />
* One is <tt>--printer</tt>: it expects the name used to identify the printer when is was configured.<br />
<br />
* The other is <tt>--raw-device</tt>: this option expects a path beginning with "/dev". If the printer is the only serial printer on the system, "/dev/lp0" should be its device node. For USB printers, it is "/dev/usb/lp0". If having more than one printer, they will have names ending in "lp1", "lp2", etc.<br />
<br />
On to the maintenance options:<br />
* To clean the printer heads:<br />
$ escputil -u --clean-head<br />
<br />
* To print the nozzle-check pattern (allows verifying that the previous head cleaning worked, and determining the heads need cleaning):<br />
$ escputil -u --nozzle-check<br />
<br />
If wanting to perform an operation that requires two-way communication with a printer, use the "--raw-device" specification and the user must be root or be a member of the group "lp".<br />
<br />
* The following is an example of getting the printer's internal identification:<br />
$ sudo escputil --raw-device=/dev/usb/lp0 --identify<br />
<br />
* To print out the ink levels of the printer:<br />
$ sudo escputil --raw-device=/dev/usb/lp0 --ink-level<br />
<br />
====mtink====<br />
This is a printer status monitor which enables to get the remaining ink quantity, to print test patterns, to reset printer and to clean nozzle. It use an intuitive graphical user interface. Package can be downloaded from [http://aur.archlinux.org/packages.php?do_Details=1&ID=476&O=0&L=0&C=0&K=mtink&SB=n&SO=a&PP=25&do_MyPackages=0&do_Orphans=0&SeB=nd AUR].<br />
<br />
====Stylus-toolbox====<br />
This is a GUI using escputil and cups drivers. It supports nearly all USB printer of Epson and displays ink quantity, can clean and align print heads and print test patterns. It can be downloaded from [http://aur.archlinux.org/packages.php?ID=30319 AUR]<br />
<br />
===PDF virtual printer===<br />
CUPS-PDF is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. Obviously this package is not necessary, but it can be quite useful.<br />
<br />
Find generated PDF documents in a sub-directory located at <code>/var/spool/cups-pdf</code>. Normally, the subdirectory is named after the user who performed the job.<br />
<br />
This package can be installed by the following command:<br />
# pacman -S cups-pdf<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. For the Device, select '''CUPS-PDF (Virtual PDF Printer)'''; Make/Manufacturer, choose '''Generic'''; Model/Driver, select '''Generic postscript color printer'''. Alternatively, provide the PPD file from [http://www.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/cups-pdf-CURRENT/extra/CUPS-PDF.ppd this link].<br />
<br />
====Print to postscript: CUPS-PDF virtual printer trick====<br />
Printing to PDF in most applications like OpenOffice is no problem; just hit the button. Yet when printing out to postscript, matters take a little more work. For applications like OpenOffice where printing to kprinter is nebulous at best, there has to be another way -- and there is. The CUPS-PDF (Virtual PDF Printer) actually creates a postscript file and then creates the PDF using the ps2pdf utility. To print to postscript, what needs to be done is capturing the intermediate postscript file created by CUPS-PDF. This is easily accomplished with by selecting the "print to file" option in the print dialog. (choose either .ps or .eps as the extension) After selecting the "print to file" checkbox simply enter the filename and click "print".<br />
<br />
=====Configuring CUPS-PDF virtual printer=====<br />
1. Install cups & cups-pdf from extra.<br />
<br />
2. Start cups with:<br />
# /etc/rc.d/cups <br />
<br />
{{Note|Add 'cups' to the deamons line in /etc/rc.conf to start automatically at boot.}}<br />
<br />
3. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Find New Printers<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Now to print to postscript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
===Another source for printer drivers===<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
==Resources==<br />
* [http://localhost:631/documentation.html Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS Website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://home.nyc.rr.com/computertaijutsu/cups.html Tips and Suggestions on common CUPS problems], '''(Dead link)'''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's Printing Guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation Resources]''<br />
* [http://bbs.archlinux.org/ Arch Linux User Forums]<br />
<br />
{{Wikipedia|Common Unix Printing System}}</div>Bhobbithttps://wiki.archlinux.org/index.php?title=CUPS/Printer_sharing&diff=100056CUPS/Printer sharing2010-03-14T04:15:13Z<p>Bhobbit: Moved printer sharing section from CUPS article as it has become too large</p>
<hr />
<div>[[Category:Printers (English)]][[Category:HOWTOs (English)]]<br />
{{i18n|CUPS printer sharing}}<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Setting up printer sharing using CUPS}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Samba}}<br />
{{Article summary wiki|CUPS}}<br />
{{Article summary end}}<br />
<br />
[[CUPS]] provides capabilities to set up printer sharing between different systems. Below you'll find instructions for common scenarios.<br />
<br />
==Between GNU/Linux systems==<br />
Once CUPS has been setup on the GNU/Linux print server, the recommended method of sharing the printer with another GNU/Linux system is through the relatively easy to use web interface, yet manual configuration is also a way.<br />
<br />
===Using the web interface===<br />
<br />
Access http://localhost:631 with a browser and the CUPS administration home page will be displayed. <br />
<br />
Click on the ''Administration'' tab near the top, select the add printer option and it should automatically detect the connected printer. If not, try turning off the printer and then back on before another attempt. <br />
<br />
Once the printer has been set up, look under the ''Server'' heading and click the checkbox for "Share printers connected to this system". Now, conclude by clicking ''change settings'' and the server will automatically restart. <br />
<br />
Selecting "Edit Configuration File" allows making direct edits to the {{Filename|cups.conf}} file. This is useful for allowing server access only to certain users or IP addresses, as the example shown below.<br />
<br />
===Manual setup===<br />
<br />
On the server computer (the one directly connected to the printer) simply open up {{Filename|/etc/cups/cupsd.conf}} and allow access to the server by modifying the location lines. For instance:<br />
<Location /><br />
Order allow,deny<br />
Allow localhost<br />
Allow 192.168.0.*<br />
</Location><br />
<br />
Also make sure the server is listening on the IP address the client will be addressing. Add the following line after "# Listen <serverip>:631" (using the server's IP address instead of client's 192.168.0.100):<br />
Listen 192.168.0.101:631<br />
<br />
To "Show shared printers on the local network", add the line "BrowseAllow all":<br />
Browsing On<br />
BrowseOrder allow,deny<br />
BrowseAllow @LOCAL<br />
BrowseAllow all<br />
<br />
After making modifications, restart CUPS by:<br />
# /etc/rc.d/cups restart<br />
<br />
On the client system, open up (create if not present) {{Filename|/etc/cups/client.conf}} and add the ServerName to match the IP address or the name of the server. Add this line:<br />
ServerName 192.168.0.101<br />
<br />
To "Show shared printers on the local network", add the line "BrowseAllow all":<br />
Browsing On<br />
BrowseOrder allow,deny<br />
BrowseAllow @LOCAL<br />
BrowseAllow all<br />
<br />
There are more configuration possibilities, including automatic methods, which are described in detail in http://localhost:631/help/network.html <!-- Someone with CUPS installed could rename the link to the page title --><br />
<br />
After making modifications, restart CUPS.<br />
<br />
{{Note|When adding the printer from the client, if using the Internet Printing Protocol (IPP), put the URI as ipp://192.168.0.101:631/printers/<name-of-printer>}}<br />
<br />
==Between GNU/Linux and Windows==<br />
<br />
===GNU/Linux client===<br />
If connected to a Windows print server (or any other [[Samba]] capable print server), skip the section about kernel modules and such. All that needs to be done is to start the CUPS daemon and complete the web interface as specified previously. Before this, activate the Samba CUPS back-end. Do this by entering the following command:<br />
# ln -s $(which smbspool) /usr/lib/cups/backend/smb<br />
<br />
After completing this task, restart CUPS issuing the command specified in the previous section. Next, simply log in on the CUPS web interface and choose to add a new printer. As a device choose "Windows Printer via SAMBA".<br />
<br />
For the device location, enter:<br />
smb://username:password@hostname/printer_name<br />
<br />
Or without a password:<br />
smb://username@hostname/printer_name<br />
<br />
Make sure that the user actually has access to the printer on the Windows computer and select the appropriate drivers. If the computer is located on a domain, make sure the user-name includes the domain: <br />
smb://username:password@domain/hostname/printer_name<br />
<br />
If the network contains many printers, use {{Codeline|lpoptions -d desired_default_printer_name}} to set the preferred printer.<br />
<br />
===Windows client===<br />
Sometimes one might want to allow a Windows computer to connect to a GNU/Linux server. There are a few ways to do this, including Samba. In order to do this, edit {{Filename|/etc/samba/smb.conf}} file to allow access to printers. File {{Filename|smb.conf}} can look something like this:<br />
<pre><br />
[global]<br />
workgroup=Heroes<br />
server string=Arch Linux Print Server<br />
security=user<br />
<br />
[printers]<br />
comment=All Printers<br />
path=/var/spool/samba<br />
browseable=yes<br />
# to allow user 'guest account' to print.<br />
guest ok=no<br />
writable=no<br />
printable=yes<br />
create mode=0700<br />
write list=@adm root neocephas<br />
</pre><br />
<br />
That should be enough to share the printer, yet adding an individual printer entry may be desirable:<br />
<pre><br />
[ML1250]<br />
comment=Samsung ML-1250 Laser Printer<br />
printer=ml1250<br />
path=/var/spool/samba<br />
printing=cups<br />
printable=yes<br />
printer admin=@admin root neocephas<br />
user client driver=yes<br />
# to allow user 'guest account' to print.<br />
guest ok=no<br />
writable=no<br />
write list=@adm root neocephas<br />
valid users=@adm root neocephas<br />
</pre><br />
<br />
Please note that this assumes configuration was made so that users must have a valid account to access the printer. To have a public printer, set ''guest ok'' to ''yes'', and remove the ''valid users'' line. To add accounts, set up a regular GNU/Linux account and then set up a Samba password on the server. For instance:<br />
<pre><br />
# useradd neocephas<br />
# smbpasswd -a neocephas<br />
</pre><br />
<br />
<!--<br />
After setting up all the needed user accounts, the samba spool directory also needs configuration:<br />
<pre><br />
# mkdir /var/spool/samba<br />
# chmod 777 /var/spool/samba<br />
</pre><br />
<br />
The next items that need changing are {{Filename|/etc/cups/mime.convs}} and {{Filename|/etc/cups/mime.types}}:<br />
<br />
{{Filename|mime.convs}}:<br />
<pre><br />
# The following line is found at near the end of the file. Uncomment it.<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
</pre><br />
<br />
{{Filename|mime.types}}:<br />
<pre><br />
# Again near the end of the file.<br />
application/octet-stream<br />
</pre><br />
<br />
The changes to {{Filename|mime.convs}} and {{Filename|mime.types}} are needed to make CUPS print Microsoft Office document files. Many users seem to need that.<br />
--><br />
<br />
After this, restart Samba daemon:<br />
# /etc/rc.d/samba restart<br />
<br />
Obviously, there are a lot of tweaks and customizations that can be done with setting up a Samba print server, so it is advised to look at the Samba and CUPS documentation for more help. The {{Filename|smb.conf.example}} file also has some good samples that might warrant imitating.<br />
<br />
====Windows 2000 and Windows XP====<br />
<!-- Requesting page titles for the CUPS interface links in this section and the next. --><br />
For the most modern flavors of Windows, an alternative way of connecting to the GNU/Linux printer server is to use the CUPS protocol directly. The Windows client will need to be using Windows 2000 or Windows XP. Make sure the clients are allowed to access the print server by editing the location settings as specified in section 4.1.<br />
<br />
On the Windows computer, go to the printer control panel and choose to 'Add a New Printer'. Next, choose to give a URL. For the URL, type in the location of the printer: http://host_ip_address:631/printers/printer_name (where host_ip_address is the GNU/Linux server's IP address and printer_name is the name of the printer being connected to).<br />
<br />
After this, install the printer drivers for the Windows computer. If the CUPS server is setup to use its own printer drivers, then just select a generic postscript printer for the Windows client. Then test the print setup by printing a test page.<br />
<br />
==Other operating systems==<br />
More information on interfacing CUPS with other printing systems can be found in the CUPS manual, e.g. on http://localhost:631/sam.html#PRINTING_OTHER</div>Bhobbithttps://wiki.archlinux.org/index.php?title=CUPS&diff=100054CUPS2010-03-14T02:50:06Z<p>Bhobbit: Formatting changes to improve readability</p>
<hr />
<div>[[Category:Printers (English)]][[Category:HOWTOs (English)]]<br />
{{i18n|CUPS}}<br />
{{Article summary start|Summary}}<br />
{{Article summary text|Installing and configuring CUPS}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Samba}}<br />
{{Article summary end}}<br />
From [http://www.cups.org/index.php CUPS' site]:<br />
:"''CUPS is the standards-based, open source printing system developed by Apple Inc. for Mac OS® X and other UNIX®-like operating systems.''"<br />
Although there are other printing packages such as LPRNG, the ''C''ommon ''U''nix ''P''rinting ''S''ystem is the most popular choice because of its relative ease of use.<br />
<br />
==Installing==<br />
These packages are needed:<br />
# pacman -S cups ghostscript gsfonts<br />
<br />
* '''cups''' - The actual CUPS software<br />
* '''ghostscript''' - Interpreter for the Postscript language<br />
* '''gsfonts''' - GhostScript standard Type1 fonts<br />
* '''hal-cups-utils''' - This package might be needed. Read [http://bbs.archlinux.org/viewtopic.php?pid=655391#p655391 this forum post] for more information<br />
<br />
If the system is connected to a networked printer using the [[Samba]] protocol or if the system is to be a print server for Windows clients, also install Samba:<br />
# pacman -S samba<br />
<br />
===Printer driver===<br />
Here are some of the driver packages. Choosing the right driver depends on the printer:<br />
<br />
* '''gutenprint''' - A collection of high quality drivers for Canon, Epson, Lexmark, Sony, Olympus, and PCL printers for use with GhostSscript, CUPS, Foomatic, and the [[GIMP]]<br />
* '''foomatic-db, foomatic-db-engine, foomatic-db-nonfree, and foomatic-filters''' - Foomatic is a database-driven system for integrating free software printer drivers with common spoolers under Unix. Installing foomatic-filters should solve problems if the cups error_log is reporting "stopped with status 22!".<br />
* '''hplip''' - HP GNU/Linux inkjet driver. Provides support for DeskJet, OfficeJet, Photosmart, Business Inkjet and some LaserJet printer models<br />
* '''splix''' - Samsung drivers for SPL (Samsung Printer Language) printers<br />
* '''ufr2''' - Canon UFR2 driver with support for LBP, iR and MF series printers. Package is available in the [[AUR]].<br />
* '''cups-pdf''' - A package that allows one to setup a virtual PDF Printer that generates a PDF out of jobs sent to it<br />
<br />
If unsure of what driver package to install or if the current driver is not working, it may be easiest to just install all of drivers, since some of the packages are misleading because printers of other makes may rely on them. For instance, the Brother HL-2140 needs the hplip driver installed.<br />
# pacman -S gutenprint foomatic-db foomatic-db-engine \<br />
foomatic-db-nonfree foomatic-filters \<br />
hplip splix ufr2 cups-pdf<br />
<br />
====Download printer PPD====<br />
Depending on the printer, this step is optional and may not be needed, as the standard CUPS installation already comes with quite a few PPD (Postscript Printer Description) files. Moreover, the ''foomatic-filters'', ''gimp-print'' and ''hplip'' packages already include quite a few PPD files which will automatically be detected by CUPS.<br />
<br />
Here is an explanation of what a PPD file is from the Linux Printing website:<br />
:"''For every PostScript printer the manufacturers provide a PPD file which contains all printer-specific information about the particular printer model: Basic printer capabilities as whether the printer is a color printer, fonts, PostScript level, etc., and especially the user-adjustable options, as paper size, resolution, etc.''"<br />
<br />
If the PPD for the printer is ''not'' already in CUPS, then:<br />
*check [[AUR]] to see if there are packages for the printer/manufacturer<br />
*visit the [http://www.linuxprinting.org/printer_list.cgi OpenPrinting database] and select the manufacturer and model of the printer<br />
*visit the manufacturer's site and search for GNU/Linux drivers<br />
<br />
{{Note|PPD files go in {{Filename|/usr/share/cups/model/}}}}<br />
<br />
==Configuring==<br />
Now that CUPS is installed, there are a variety of options on how to setup printing solutions. As always, the tried and true command line method is at disposal. Likewise, various desktop environments such as GNOME and KDE have useful programs that can help manage printers. However, in order to make this process easy for the largest amount of users, this article will focus on the web interface provided by CUPS.<br />
<br />
Please note that if planning on connecting to a network printer, rather than one that is directly connected to the computer, read the [[#Printer sharing]] section first. Printer sharing between GNU/Linux systems is quite easy and involves very little configuration, whereas sharing between a Windows and GNU/Linux host requires a little bit more effort.<br />
<br />
===Kernel modules===<br />
Before using the CUPS web interface, the appropriate kernel modules need to be installed. The following steps are from the Gentoo Printing Guide.<br />
<br />
This section may not be necessary, however, depending on which kernel is being used. The kernel module may load automatically after plugging in the printer. Use the {{Codeline|tail}} command (described below) to see if the printer has already been detected. The {{Codeline|lsmod}} utility can also be used to see what modules have been loaded.<br />
<br />
====USB printers====<br />
USB printer users may need to blacklist the {{codeline|usblp}} module. Keep in mind that there seems to be a lot of [http://bbs.archlinux.org/viewtopic.php?pid=660601 uncertainty] regarding blacklisting usblp, as some USB printers, including some Canon printer series, are not recognized without it. To disable the module, edit {{filename|rc.conf}} as shown:<br />
MODULES=(... '''!usblp''' ...)<br />
<br />
Custom kernel users may need to manually load the {{codeline|usbcore}} module before proceeding:<br />
# modprobe usbcore<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# tail /var/log/messages.log<br />
or<br />
# dmesg<br />
<br />
The output should indicate that the printer has been detected:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
====Parallel port printers====<br />
If planning on using a parallel port printer, note that the configuration is pretty much the same, except for the modules:<br />
# modprobe lp<br />
# modprobe parport<br />
# modprobe parport_pc<br />
<br />
Once again, check the setup by running:<br />
# tail /var/log/messages.log<br />
It should display something like this:<br />
lp0: using parport0 (polling).<br />
<br />
====Auto-loading====<br />
It's convenient to have the system automatically load the kernel module every time the it starts up. To do so, use a text editor to open up {{Filename|/etc/[[rc.conf]]}} and add the appropriate module to the <code>MODULES=()</code> line. Here is an example:<br />
MODULES=(!usbserial scsi_mod sd_mod snd-ymfpci snd-pcm-oss '''lp parport parport_pc''' ide-scsi)<br />
<br />
===CUPS daemon===<br />
With the kernel modules installed, the system is now ready to start the actual CUPS daemon. To do this, simply run this command:<br />
# /etc/rc.d/cups start<br />
<br />
For automatically starting CUPS every time the system is powered on, add it to the <code>DAEMONS=()</code> line in the {{Filename|/etc/rc.conf}} file. For example:<br />
DAEMONS=(pcmcia syslogd klogd !fam esd mono network autofs '''cups''' crond gdm)<br />
<br />
=== Web interface and tool-kit ===<br />
<br />
Once the daemon is running, open a browser and go to: http://localhost:631 (''The '''localhost''' string may need to be replaced with the hostname found in'' {{Filename|/etc/hosts}}).<br />
<br />
{{Tip|[[GNOME]] users may be inclined towards installing the GNOME CUPS manager GUI frontend. See: [[#Alternative CUPS interfaces]]}}<br />
<br />
From here, follow the various wizards to add the printer. A usual procedure is to start by clicking on ''Adding Printers and Classes'' and then ''Add Printer''. When prompted for a user-name and password, log in as root. The name assigned to the printer does not matter, the same applies for 'location' and 'description'. Next, a list of devices to select from will be presented. The actual name of the printer shows up next to the label ( e.g., next to ''USB Printer #1'' for USB printers). Finally, chose the appropriate drivers and the configuration is complete.<br />
<br />
Now, test the configuration by pressing the ''Maintenance'' drop-down menu then ''Print Test Page''. If it does not print and there is certainty regarding the correctness of applied settings, then the problem is most likely due to missing a proper printer driver.<br />
<br />
==== CUPS administration ====<br />
<br />
A user-name and password will be required when administrating the printer in the web interface, such as: adding or removing printers, stopping print tasks, etc. The default user-name is the one assigned in the ''sys'' group, or root (change this by editing {{Filename|/etc/cups/cupsd.conf}} in the line of ''SystemGroup''). <br />
<br />
If the root account has been locked, it is not possible to log in the CUPS administration interface with the default user-name and password. In this case, it may be needed to change the default SystemGroup in cupsd.conf and read [http://bbs.archlinux.org/viewtopic.php?id=35567 this post].<br />
<br />
====Remote access to web interface====<br />
By default, the CUPS web interface can only be accessed by the ''localhost''; i.e. the computer that it is installed on. To remotely access the interface, make the following changes to the {{Filename|/etc/cups/cupsd.conf}} file. Replace the line:<br />
Listen localhost:631<br />
with<br />
port 631<br />
so that CUPS listens to incoming requests.<br />
<br />
There are three levels of access that can be granted:<br />
<Location /> #access to the server<br />
<Location /admin> #access to the admin pages<br />
<Location /admin/conf> #access to configuration files<br />
<br />
To give remote hosts access to one of these levels, add an {{codeline|Allow}} statement to that level's section. An {{codeline|Allow}} statement can take one or more of the forms listed below:<br />
Allow all<br />
Allow host.domain.com<br />
Allow *.domain.com<br />
Allow ip-address<br />
Allow ip-address/netmask<br />
<br />
Deny statements can also be used. For example, if wanting to give all hosts on the 192.168.1.0/255.255.255.0 subnet full access, file {{Filename|/etc/cups/cupsd.conf}} would include this:<br />
# Restrict access to the server...<br />
# By default only localhost connections are possible<br />
<Location /><br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to the admin pages...<br />
<Location /admin><br />
# Encryption disabled by default<br />
#Encryption Required<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
# Restrict access to configuration files...<br />
<Location /admin/conf><br />
AuthType Basic<br />
Require user @SYSTEM<br />
Order allow,deny<br />
Allow From localhost<br />
'''Allow From 192.168.1.0/255.255.255.0'''<br />
</Location><br />
<br />
==Printer sharing==<br />
<br />
===Between GNU/Linux systems===<br />
Once CUPS has been setup on the GNU/Linux print server, the recommended method of sharing the printer with another GNU/Linux system is through the relatively easy to use web interface, yet manual configuration is also a way.<br />
<br />
====Using the web interface====<br />
<br />
Access http://localhost:631 with a browser and the CUPS administration home page will be displayed. <br />
<br />
Click on the ''Administration'' tab near the top, select the add printer option and it should automatically detect the connected printer. If not, try turning off the printer and then back on before another attempt. <br />
<br />
Once the printer has been set up, look under the ''Server'' heading and click the checkbox for "Share printers connected to this system". Now, conclude by clicking ''change settings'' and the server will automatically restart. <br />
<br />
Selecting "Edit Configuration File" allows making direct edits to the {{Filename|cups.conf}} file. This is useful for allowing server access only to certain users or IP addresses, as the example shown below.<br />
<br />
====Manual setup====<br />
<br />
On the server computer (the one directly connected to the printer) simply open up {{Filename|/etc/cups/cupsd.conf}} and allow access to the server by modifying the location lines. For instance:<br />
<Location /><br />
Order allow,deny<br />
Allow localhost<br />
Allow 192.168.0.*<br />
</Location><br />
<br />
Also make sure the server is listening on the IP address the client will be addressing. Add the following line after "# Listen <serverip>:631" (using the server's IP address instead of client's 192.168.0.100):<br />
Listen 192.168.0.101:631<br />
<br />
To "Show shared printers on the local network", add the line "BrowseAllow all":<br />
Browsing On<br />
BrowseOrder allow,deny<br />
BrowseAllow @LOCAL<br />
BrowseAllow all<br />
<br />
After making modifications, restart CUPS by:<br />
# /etc/rc.d/cups restart<br />
<br />
On the client system, open up (create if not present) {{Filename|/etc/cups/client.conf}} and add the ServerName to match the IP address or the name of the server. Add this line:<br />
ServerName 192.168.0.101<br />
<br />
To "Show shared printers on the local network", add the line "BrowseAllow all":<br />
Browsing On<br />
BrowseOrder allow,deny<br />
BrowseAllow @LOCAL<br />
BrowseAllow all<br />
<br />
There are more configuration possibilities, including automatic methods, which are described in detail in http://localhost:631/help/network.html <!-- Someone with CUPS installed could rename the link to the page title --><br />
<br />
After making modifications, restart CUPS.<br />
<br />
{{Note|When adding the printer from the client, if using the Internet Printing Protocol (IPP), put the URI as ipp://192.168.0.101:631/printers/<name-of-printer>}}<br />
<br />
===Between GNU/Linux and Windows===<br />
<br />
====GNU/Linux client====<br />
If connected to a Windows print server (or any other [[Samba]] capable print server), skip the section about kernel modules and such. All that needs to be done is to start the CUPS daemon and complete the web interface as specified previously. Before this, activate the Samba CUPS back-end. Do this by entering the following command:<br />
# ln -s $(which smbspool) /usr/lib/cups/backend/smb<br />
<br />
After completing this task, restart CUPS issuing the command specified in the previous section. Next, simply log in on the CUPS web interface and choose to add a new printer. As a device choose "Windows Printer via SAMBA".<br />
<br />
For the device location, enter:<br />
smb://username:password@hostname/printer_name<br />
<br />
Or without a password:<br />
smb://username@hostname/printer_name<br />
<br />
Make sure that the user actually has access to the printer on the Windows computer and select the appropriate drivers. If the computer is located on a domain, make sure the user-name includes the domain: <br />
smb://username:password@domain/hostname/printer_name<br />
<br />
If the network contains many printers, use {{Codeline|lpoptions -d desired_default_printer_name}} to set the preferred printer.<br />
<br />
====Windows client====<br />
Sometimes one might want to allow a Windows computer to connect to a GNU/Linux server. There are a few ways to do this, including Samba. In order to do this, edit {{Filename|/etc/samba/smb.conf}} file to allow access to printers. File {{Filename|smb.conf}} can look something like this:<br />
<pre><br />
[global]<br />
workgroup=Heroes<br />
server string=Arch Linux Print Server<br />
security=user<br />
<br />
[printers]<br />
comment=All Printers<br />
path=/var/spool/samba<br />
browseable=yes<br />
# to allow user 'guest account' to print.<br />
guest ok=no<br />
writable=no<br />
printable=yes<br />
create mode=0700<br />
write list=@adm root neocephas<br />
</pre><br />
<br />
That should be enough to share the printer, yet adding an individual printer entry may be desirable:<br />
<pre><br />
[ML1250]<br />
comment=Samsung ML-1250 Laser Printer<br />
printer=ml1250<br />
path=/var/spool/samba<br />
printing=cups<br />
printable=yes<br />
printer admin=@admin root neocephas<br />
user client driver=yes<br />
# to allow user 'guest account' to print.<br />
guest ok=no<br />
writable=no<br />
write list=@adm root neocephas<br />
valid users=@adm root neocephas<br />
</pre><br />
<br />
Please note that this assumes configuration was made so that users must have a valid account to access the printer. To have a public printer, set ''guest ok'' to ''yes'', and remove the ''valid users'' line. To add accounts, set up a regular GNU/Linux account and then set up a Samba password on the server. For instance:<br />
<pre><br />
# useradd neocephas<br />
# smbpasswd -a neocephas<br />
</pre><br />
<br />
<!--<br />
After setting up all the needed user accounts, the samba spool directory also needs configuration:<br />
<pre><br />
# mkdir /var/spool/samba<br />
# chmod 777 /var/spool/samba<br />
</pre><br />
<br />
The next items that need changing are {{Filename|/etc/cups/mime.convs}} and {{Filename|/etc/cups/mime.types}}:<br />
<br />
{{Filename|mime.convs}}:<br />
<pre><br />
# The following line is found at near the end of the file. Uncomment it.<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
</pre><br />
<br />
{{Filename|mime.types}}:<br />
<pre><br />
# Again near the end of the file.<br />
application/octet-stream<br />
</pre><br />
<br />
The changes to {{Filename|mime.convs}} and {{Filename|mime.types}} are needed to make CUPS print Microsoft Office document files. Many users seem to need that.<br />
--><br />
<br />
After this, restart Samba daemon:<br />
# /etc/rc.d/samba restart<br />
<br />
Obviously, there are a lot of tweaks and customizations that can be done with setting up a Samba print server, so it is advised to look at the Samba and CUPS documentation for more help. The {{Filename|smb.conf.example}} file also has some good samples that might warrant imitating.<br />
<br />
=====Windows 2000 and Windows XP=====<br />
<!-- Requesting page titles for the CUPS interface links in this section and the next. --><br />
For the most modern flavors of Windows, an alternative way of connecting to the GNU/Linux printer server is to use the CUPS protocol directly. The Windows client will need to be using Windows 2000 or Windows XP. Make sure the clients are allowed to access the print server by editing the location settings as specified in section 4.1.<br />
<br />
On the Windows computer, go to the printer control panel and choose to 'Add a New Printer'. Next, choose to give a URL. For the URL, type in the location of the printer: http://host_ip_address:631/printers/printer_name (where host_ip_address is the GNU/Linux server's IP address and printer_name is the name of the printer being connected to).<br />
<br />
After this, install the printer drivers for the Windows computer. If the CUPS server is setup to use its own printer drivers, then just select a generic postscript printer for the Windows client. Then test the print setup by printing a test page.<br />
<br />
===Other operating systems===<br />
More information on interfacing CUPS with other printing systems can be found in the CUPS manual, e.g. on http://localhost:631/sam.html#PRINTING_OTHER<br />
<br />
==Troubleshooting==<br />
The best way to get printing working is to set 'LogLevel' in {{Filename|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{Filename|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{Filename|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{Filename|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{Filename|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
===Problems resulting from upgrades===<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
====CUPS stops working====<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" my result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy /etc/cups/cupsd.conf.default to /etc/cups/cupsd.conf (backup the old the configuration if needed):<br />
# cp /etc/cups/cupsd.conf.default /etc/cups/cupsd.conf<br />
and restart CUPS to employ the new settings.<br />
<br />
====Error with gnutls====<br />
If receiving errors such as:<br />
/usr/sbin/cupsd: error while loading shared libraries: libgnutls.so.13: cannot open shared object file: No such file or directory<br />
gnutls may be in need of updating:<br />
# pacman -S gnutls<br />
<br />
After updating, there may be a file named {{Filename|cupsd.conf.pacnew}} in {{Filename|/etc/cups}}. This is the unmodified original configuration file that has been placed as part of the update. Compare it with the currently installed version and adjust to preference.<br />
<br />
====All jobs are "stopped"====<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
====The PPD version is not compatible with gutenprint====<br />
Run:<br />
# /usr/sbin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message)<br />
<br />
===USB printers under CUPS 1.4.x===<br />
New CUPS 1.4.x introduces many changes:<br />
<br />
====Configuration file====<br />
The syntax of the configuration file cupsd.conf changed. Start with a new cupsd.conf file based on /etc/cups/cupsd.conf.default.<br />
<br />
====Blacklisting usblp====<br />
CUPS now uses libusb and printer USB devices (under /dev/bus/usb/) instead of the usblp generated /dev/usb/lpX ones. In order to get USB printers working, the usblp module needs disabling. This can be done by blacklisting it in /etc/rc.conf, or by adding "blacklist usblp" to a configuration file in /etc/modprobe.d. Some users have also reported that they needed to reinstall their printer.<br />
<br />
====Device node permissions====<br />
In addition to usblp not being loaded, CUPS also needs the ownership of the USB device file of the printer to be root:lp, and permissions to be 660. E.g.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
This is supposed to be achieved by two udev rules in /lib/udev/rules.d/50-udev-default.rules:<br />
# hplip and cups 1.4+ use raw USB devices, so permissions should be similar to<br />
# the ones from the old usblp kernel module<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}=="", IMPORT{program}="usb_id --export %p"<br />
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ENV{ID_USB_INTERFACES}==":0701*:", GROUP="lp", MODE="660"<br />
<br />
However, for some devices, in particular combined printer/scanner devices, these rules either do not trigger, or are overwritten by rules of the 'sane' package. In these cases a custom udev rule needs to be added. See below.<br />
<br />
=====Device node permission troubleshooting=====<br />
Get the printer's device file and its permissions with: <br />
$ lsusb<br />
...<br />
Bus 003 Device 002: ID 04b8:0841 Seiko Epson Corp.<br />
$ ls -l /dev/bus/usb/003/002<br />
crw-rw---- 1 root lp 189, 257 20. Okt 10:32 /dev/bus/usb/003/002<br />
<br />
If the permissions are not already root:lp 660, enforce it by creating a custom udev rule, e.g<br />
cat /etc/udev/rules.d/10-usbprinter.rules<br />
ATTR{idVendor}=="04b8", ATTR{idProduct}=="0841", MODE:="0660", GROUP:="lp"<br />
<br />
Note that idVendor and idProduct are from the lsusb listing above.<br />
<br />
=====Loading firmware=====<br />
<br />
Some printers and drivers need to load firmware to the printer (such as HP LaserJet 10xx printers using foo2zjs) and do this by writing directly to the lp device, a functionality provided by usblp. A work around until this issue is resolved is to install the usblp module until the firmware is loaded, then remove the module to allow CUPS to work. This can be accomplished by manually running "$ modprobe usblp", waiting for the firmware to load, then "$ rmmod usblp". You can also not blacklist usblp, then put "rmmod usblp" to /etc/rc.local, allowing the firmware to be loaded on boot before rc.local is run, then removing usblp.<br />
<br />
===Other===<br />
<br />
=====CUPS permission errors=====<br />
*Some users fixed 'NT_STATUS_ACCESS_DENIED' (Windows clients) errors by using a slightly different syntax:<br />
smb://workgroup/username:password@hostname/printer_name<br />
<br />
*Sometimes, the block device has wrong permissions:<br />
# ls /dev/usb/<br />
lp0<br />
# chgrp lp /dev/usb/lp0<br />
<br />
====HPLIP printer sends "/usr/lib/cups/backend/hp failed" error====<br />
Make sure dbus is installed and running, e.g. check DAEMONS in {{Filename|/etc/rc.conf}} or run {{Codeline|ls /var/run/daemons}}.<br />
<br />
====hp-toolbox sends an error, "Unable to communicate with device"====<br />
If running hp-toolbox as a regular user results in:<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/<printer id><br />
or, "{{Codeline|Unable to communicate with device"}}", then it may be needed to add the user to the lp group by running the following command:<br />
# gpasswd -a <username> lp<br />
<br />
====CUPS returns '"foomatic-rip" not available/stopped with status 3' with a HP printer====<br />
If receiving any of the following error messages in {{Filename|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer "<printer_name>" not available: No such file or director<br />
or:<br />
PID 5771 (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure '''hplip''' has been installed, in addition to [[#Packages|the packages mentioned above]], '''net-snmp''' is also needed. See [http://bbs.archlinux.org/viewtopic.php?id=65615 this forum post].<br />
# pacman -S hplip<br />
<br />
====Printing fails with unauthorised error====<br />
If the user has been added to the lp group, and allowed to print (set in {{Filename|cups.conf}}), then the problem lies in {{Filename|/etc/cups/printers.conf}}. This line could be the culprit:<br />
AuthInfoRequired negotiate<br />
<br />
Comment it out and restart CUPS.<br />
<br />
====Print button greyed-out in GNOME print dialogs====<br />
:''<small>Source: [http://bbs.archlinux.org/viewtopic.php?id=70418 I can't print from gnome applications. - Arch Forums]</small>''<br />
<br />
Be sure the package: '''libgnomeprint''' is installed<br />
<br />
Edit {{filename|/etc/cups/cupsd.conf}} and add<br />
# HostNameLookups Double<br />
<br />
Restart CUPS:<br />
# /etc/rc.d/cups restart<br />
<br />
====CUPS fails to print with 'Unable to open device "hal:///[...]": Permission denied'====<br />
The permissions on some files are wrong:<br />
# cd /usr/lib/cups/backend<br />
# chmod 700 hal # (previously 755)<br />
# chmod 700 usb # (previously 755)<br />
<br />
====Unknown supported format: application/postscript====<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{Filename|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{Filename|/etc/cups/mime.types}}.<br />
<br />
====Finding URIs for Windows Print Servers====<br />
<br />
Sometimes Windows is a little less than forthcoming about exact device URIs (device locations). If having trouble specifying the correct device location in CUPS, run the following command to list all shares available to a certain windows username:<br />
$ smbtree -U ''windowsusername''<br />
This will list every share available to a certain Windows username on the local area network subnet, as long as Samba is set up and running properly. It should return something like this:<br />
<pre> WORKGROUP<br />
\\REGULATOR-PC <br />
\\REGULATOR-PC\Z <br />
\\REGULATOR-PC\Public <br />
\\REGULATOR-PC\print$ Printer Drivers<br />
\\REGULATOR-PC\G <br />
\\REGULATOR-PC\EPSON Stylus CX8400 Series EPSON Stylus CX8400 Series</pre><br />
What is needed here is first part of the last line, the resource matching the printer description. So to print to the EPSON Stylus printer, one would enter:<br />
smb://username.password@REGULATOR-PC/EPSON Stylus CX8400 Series<br />
as the URI into CUPS. Notice that whitespaces are allowed in URIs, whereas backslashes get replaced with forward slashes.<br />
<br />
===Printer-specific===<br />
''Printer-specific problems and their solutions''<br />
<br />
<br />
<br />
====Brother DCP 7020====<br />
See: [[Brother DCP-7020]]<br />
<br />
====Canon MF 4150====<br />
This is required as some Canon printers apparently do not declare their specification correctly for kernel and libusb to recognize them<br />
<br />
* Do NOT blacklist usblp module.<br />
<br />
* Install hal-cups-utils and restart hal<br />
# sudo pacman -S hal-cups-utils<br />
# sudo /etc/rc.d/hal restart<br />
<br />
* Connect the printer<br />
<br />
The printer should now be recognized by the CUPS Add printer dialog. If still having problems, try restarting CUPS.<br />
<br />
* Install UFRII driver ({{Package AUR|ufr2}} from the [[AUR]] and complete the printer installation.<br />
<br />
====Epson AcuLaser CX11(NF)====<br />
Install [http://aur.archlinux.org/packages.php?ID=30424 Epson-ALCX11-filter] from the AUR. Restart CUPS and add the printer using the driver "EPSON AL-CX11, ESC/PageS Filter".<br />
<br />
Both connections, USB and network, should work as expected.<br />
<br />
====FX C1110 (not model B)====<br />
Keep in mind that these directions assume that the printer is connected and listening on the network.<br />
<br />
*Install cpio and rpmunpack to later unpack the package:<br />
# pacman -S cpio rpmunpack cups ghostscript gsfonts<br />
<br />
*Get the FX GNU/Linux driver [http://www.fujixeroxprinters.com/downloads/uploaded/Drivers/DocuPrint%20C1110%20C1110B/linux/fxlinuxprint-1.0.1-1.i386.zip here].<br />
<br />
*Unzip {{Filename|fxlinuxprint-1.0.1-1.i386.zip}} to /var/tmp (the directory is not important):<br />
$ unzip fxlinuxprint-1.0.1-1.i386.zip -d /var/tmp<br />
<br />
*Continue extracting the file:<br />
$ cd /var/tmp<br />
$ rpmunpack fxlinuxprint-1.0.1-1.i386.rpm<br />
$ gunzip fxlinuxprint-1.0.1-1.cpio.gz<br />
<br />
*Move the cpio DST file (for convenience):<br />
$ mkdir /var/tmp/DST<br />
$ mv fxlinuxprint-1.0.1-1.cpio /var/tmp/DST<br />
<br />
*Extract it:<br />
$ cd /var/tmp/DST<br />
$ cpio -id < fxlinuxprint-1.0.1-1.cpio<br />
<br />
*Filter the relevant files:<br />
$ cd /var/tmp<br />
$ find /var/tmp/DST -type f |cat -n<br />
1 /var/tmp/DST/etc/cups/mimefx.convs<br />
2 /var/tmp/DST/etc/cups/mimefx.types<br />
3 /var/tmp/DST/usr/lib/cups/filter/pdftopjlfx<br />
4 /var/tmp/DST/usr/lib/cups/filter/pstopdffx<br />
5 /var/tmp/DST/usr/lib/cups/filter/pdftopdffx<br />
6 /var/tmp/DST/usr/share/cups/model/FujiXerox/en/fxlinuxprint.ppd<br />
<br />
*Copy the files found in the previous step to /<br />
{{Note|For the PPD use {{Filename|/usr/share/cups/model/fxlinuxprint.ppd}}}}<br />
<br />
*Access http://localhost:631/ and add the lpd://f.q.d.n/queue printer, aunthenticating as root.<br />
<br />
*Go through "Manage Printer" and "Set Printer Options".<br />
<br />
*Print a test page (substitue color103 with the assigned printer name):<br />
$ lpq -P color103<br />
color103 is ready<br />
no entries<br />
<br />
====Printing does not work with the HP Deskjet 700 Series====<br />
The solution is to install '''pnm2ppa''' printer filter for the HP Deskjet 700 series. Without this, the print jobs will be aborted by the system. A [[Arch Build System|PKGBUILD]] for pnm2ppa can be found in [http://aur.archlinux.org/packages.php?do_Details=1&ID=696&O=0&L=0&C=0&K=pnm&SB=n&SO=a&PP=25&do_MyPackages=0&do_Orphans=0 AUR].<br />
<br />
====Getting HP LaserJet 1010 to work====<br />
A solution may be to compile a newer version of GhostScript:<br />
<pre><br />
$ pacman -Qs cups a2ps psutils foo ghost<br />
local/cups 1.1.23-3<br />
The CUPS Printing System<br />
local/a2ps 4.13b-3<br />
a2ps is an Any to PostScript filter<br />
local/psutils p17-3<br />
A set of postscript utilities.<br />
local/foomatic-db 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-db-engine 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-db-ppd 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/foomatic-filters 3.0.2-1<br />
Foomatic is a system for using free software printer drivers with common<br />
spoolers on Unix<br />
local/espgs 8.15.1-1<br />
ESP Ghostscript<br />
</pre><br />
<br />
Setting <code>LogLevel</code> may also need to be set in {{Filename|/etc/cups/cupsd.conf}} to <code>debug2</code>, this way the logs will show how to circumvent minor issues, such as missing fonts. Search Google for [http://www.google.com/search?q=n019003l+filetype%3Apfb n019003l filetype:pfb]<br />
<br />
The debug solution might work if getting errors similar to 'Unsupport PCL', etc. See: [http://linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_1010 OpenPrinting database - Printer: HP LaserJet 1010]<br />
<br />
====HP LaserJet 1020====<br />
<br />
=====Installation from AUR=====<br />
Install the package foo2zjs from AUR and modify the {{Filename|PKGBUILD}}. Change the line:<br />
./getweb all<br />
to<br />
./getweb 1020<br />
<br />
If getting errors with incorrect md5sums, the md5sum of {{Filename|foo2zjs.tar.gz}} in the PKGBUILD should be changed to match the downloaded driver.<br />
<br />
As a last step, add and configure the printer in the CUPS manager. The printer should be recognized automatically, and function for both root and regular users.<br />
<br />
=====Manual installation=====<br />
{{Warning|This section involves installing packages without pacman. These directions should ideally be automated with a PKGBUILD in order to prevent issues.}}<br />
<br />
First of all, only CUPS and GhostScript needs to be installed. Then follow the links in [http://www.linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_1020 OpenPrinting database - Printer: HP LaserJet 1020] and [http://foo2zjs.rkkda.com/ foo2zjs: a linux printer driver for ZjStream protocol] to the printer driver page, and follow the install instructions. After login in as root, and downloading all the package and extracted the archives, change into the foo2zjs directory. Now, follow the regular installation instructions with a minor modification to change the 'userid' for printing:<br />
$ make<br />
$ ./getweb 1020<br />
<br />
Open the {{Filename|Makefile}}:<br />
$ nano Makefile<br />
and search for the line:<br />
# LPuid=-olp<br />
modify it to:<br />
# LPuid=-oroot<br />
then continue with the script:<br />
$ make install<br />
$ make install-hotplug<br />
$ make cups<br />
<br />
====Printer connected to an Airport Express Station====<br />
The first step is to scan the Airport Express station. It seems that there are different addresses depending on the model:<br />
<pre><br />
[root@somostation somos]# nmap 192.168.0.4<br />
<br />
Starting Nmap 4.20 ( http://insecure.org ) at 2007-06-26 00:50 CEST<br />
Interesting ports on 192.168.0.4:<br />
Not shown: 1694 closed ports<br />
PORT STATE SERVICE<br />
5000/tcp open UPnP<br />
9100/tcp open jetdirect<br />
10000/tcp open snet-sensor-mgmt<br />
MAC Address: 00:14:51:70:D5:66 (Apple Computer)<br />
<br />
Nmap finished: 1 IP address (1 host up) scanned in 25.815 seconds<br />
</pre><br />
<br />
The Airport station is accessed like an HP JetDirect printer. Afterwards, edit {{Filename|printer.conf}}:<br />
<pre><br />
# Printer configuration file for CUPS v1.2.11<br />
# Written by cupsd on 2007-06-26 00:44<br />
<Printer LaserSim><br />
Info SAMSUNG ML-1510 gdi<br />
Location SomoStation<br />
DeviceURI socket://192.168.0.4:9100<br />
State Idle<br />
StateTime 1182811465<br />
Accepting Yes<br />
Shared Yes<br />
JobSheets none none<br />
QuotaPeriod 0<br />
PageLimit 0<br />
KLimit 0<br />
OpPolicy default<br />
ErrorPolicy stop-printer<br />
</Printer><br />
</pre><br />
Problems may be resolved by removing foomatic and installing foomatic-db, foomatic-db-engine, foomatic-db-ppd instead.<br />
<br />
==Appendix==<br />
<br />
===Alternative CUPS interfaces===<br />
If using [[GNOME]], a possibility is to manage and configure the printer by using the gnome-cups-manager. This package is available through pacman: <br />
# pacman -S gnome-cups-manager<br />
<br />
Alternatively, system-config-printer-gnome can be installed:<br />
# pacman -S system-config-printer-gnome<br />
<br />
For system-config-printer to work as it should, running as root may be required, or alternatively set up a "normal" user to administer CUPS (if so '''follow steps 1-3''')<br />
<br />
* 1. Create group, and add a user<br />
# groupadd lpadmin<br />
# usermod -aG lpadmin <username><br />
<br />
* 2. Add "lpadmin" (without the quotes) to this line in {{Filename|/etc/cups/cupsd.conf}}<br />
SystemGroup sys root <insert here><br />
<br />
* 3. Restart cups, log out and in again (or restart computer)<br />
# /etc/rc.d/cups restart<br />
<br />
[[KDE]] users can modify their printers from the Control Center. Both should refer to those desktop environments' documentation for more information on how to use the interfaces.<br />
<br />
There is also gtklp:<br />
# pacman -S gtklp<br />
<br />
===Utility functions on Epson printers===<br />
<br />
====escputil====<br />
This section explains how to perform some of the utility functions (such as nozzle cleaning) on Epson printers, by using the escputil utility, part of the gutenprint package.<br />
<br />
There is a escputil's man-page provides basic information, but it does not touch on how to identify the printer. There are two parameters that can be used to do so:<br />
<br />
* One is <tt>--printer</tt>: it expects the name used to identify the printer when is was configured.<br />
<br />
* The other is <tt>--raw-device</tt>: this option expects a path beginning with "/dev". If the printer is the only serial printer on the system, "/dev/lp0" should be its device node. For USB printers, it is "/dev/usb/lp0". If having more than one printer, they will have names ending in "lp1", "lp2", etc.<br />
<br />
On to the maintenance options:<br />
* To clean the printer heads:<br />
$ escputil -u --clean-head<br />
<br />
* To print the nozzle-check pattern (allows verifying that the previous head cleaning worked, and determining the heads need cleaning):<br />
$ escputil -u --nozzle-check<br />
<br />
If wanting to perform an operation that requires two-way communication with a printer, use the "--raw-device" specification and the user must be root or be a member of the group "lp".<br />
<br />
* The following is an example of getting the printer's internal identification:<br />
$ sudo escputil --raw-device=/dev/usb/lp0 --identify<br />
<br />
* To print out the ink levels of the printer:<br />
$ sudo escputil --raw-device=/dev/usb/lp0 --ink-level<br />
<br />
====mtink====<br />
This is a printer status monitor which enables to get the remaining ink quantity, to print test patterns, to reset printer and to clean nozzle. It use an intuitive graphical user interface. Package can be downloaded from [http://aur.archlinux.org/packages.php?do_Details=1&ID=476&O=0&L=0&C=0&K=mtink&SB=n&SO=a&PP=25&do_MyPackages=0&do_Orphans=0&SeB=nd AUR].<br />
<br />
====Stylus-toolbox====<br />
This is a GUI using escputil and cups drivers. It supports nearly all USB printer of Epson and displays ink quantity, can clean and align print heads and print test patterns. It can be downloaded from [http://aur.archlinux.org/packages.php?ID=30319 AUR]<br />
<br />
===PDF virtual printer===<br />
CUPS-PDF is a nice package that allows one to setup a virtual printer that will generate a PDF from anything sent to it. Obviously this package is not necessary, but it can be quite useful.<br />
<br />
Find generated PDF documents in a sub-directory located at <code>/var/spool/cups-pdf</code>. Normally, the subdirectory is named after the user who performed the job.<br />
<br />
This package can be installed by the following command:<br />
# pacman -S cups-pdf<br />
<br />
After installing the package, set it up as if it were for any other printer by using the web interface. For the Device, select '''CUPS-PDF (Virtual PDF Printer)'''; Make/Manufacturer, choose '''Generic'''; Model/Driver, select '''Generic postscript color printer'''. Alternatively, provide the PPD file from [http://www.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/cups-pdf-CURRENT/extra/CUPS-PDF.ppd this link].<br />
<br />
====Print to postscript: CUPS-PDF virtual printer trick====<br />
Printing to PDF in most applications like OpenOffice is no problem; just hit the button. Yet when printing out to postscript, matters take a little more work. For applications like OpenOffice where printing to kprinter is nebulous at best, there has to be another way -- and there is. The CUPS-PDF (Virtual PDF Printer) actually creates a postscript file and then creates the PDF using the ps2pdf utility. To print to postscript, what needs to be done is capturing the intermediate postscript file created by CUPS-PDF. This is easily accomplished with by selecting the "print to file" option in the print dialog. (choose either .ps or .eps as the extension) After selecting the "print to file" checkbox simply enter the filename and click "print".<br />
<br />
=====Configuring CUPS-PDF virtual printer=====<br />
1. Install cups & cups-pdf from extra.<br />
<br />
2. Start cups with:<br />
# /etc/rc.d/cups <br />
<br />
{{Note|Add 'cups' to the deamons line in /etc/rc.conf to start automatically at boot.}}<br />
<br />
3. Access the cups print manager: http://localhost:631 and select:<br />
Administration -> Find New Printers<br />
Select CUPS-PDF (Virtual PDF), choose for the make and driver:<br />
Make: Generic<br />
Driver: Generic CUPS-PDF Printer<br />
<br />
Now to print to postscript, just print as usual, in the print dialog choose "CUPS-PDF" as the printer, then select the checkbox for "print to file", hit print, enter the filename.ps and click save. This is handy for faxes, etc...<br />
<br />
===Another source for printer drivers===<br />
[http://www.turboprint.de/english.html Turboprint] is a proprietary driver for many printers not yet supported by GNU/Linux (Canon i*, for example). Unlike CUPS, however, high quality prints are either marked with a watermark or are a pay-only service.<br />
<br />
==Resources==<br />
* [http://localhost:631/documentation.html Official CUPS documentation], ''locally installed''<br />
* [http://www.cups.org/ Official CUPS Website]<br />
* [http://www.linuxprinting.org/ Linux Printing], ''[http://www.linuxfoundation.org The Linux Foundation]''<br />
* [http://home.nyc.rr.com/computertaijutsu/cups.html Tips and Suggestions on common CUPS problems], '''(Dead link)'''<br />
* [http://www.gentoo.org/doc/en/printing-howto.xml Gentoo's Printing Guide], ''[http://www.gentoo.org/doc/en Gentoo Documentation Resources]''<br />
* [http://bbs.archlinux.org/ Arch Linux User Forums]<br />
<br />
{{Wikipedia|Common Unix Printing System}}</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Arch_build_system&diff=97356Arch build system2010-02-18T22:23:33Z<p>Bhobbit: correction of wording correction :)</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:Package development (English)]][[Category:Package management (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{i18n|Arch Build System}}<br />
{{Article summary start}}<br />
{{Article summary text|Description of the Arch Build System, a 'ports-like' system for building and packaging software from source code.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|ABS FAQ}}<br />
{{Article summary wiki|Arch Packaging Standards}}<br />
{{Article summary wiki|Arch User Repository}}<br />
{{Article summary wiki|Creating Packages}}<br />
{{Article summary wiki|Kernel Compilation with ABS}}<br />
{{Article summary wiki|makepkg}}<br />
{{Article summary wiki|makepkg.conf}}<br />
{{Article summary wiki|pacman}}<br />
{{Article summary wiki|pacman Tips}}<br />
{{Article summary wiki|PKGBUILD}}<br />
{{Article summary wiki|PKGBUILD Tricks}}<br />
{{Article summary end}}<br />
<br />
This article provides an overview of the Arch Build System along with a walkthrough for beginners. It is not a complete reference guide! For a quick and simple introduction to the ABS see the [[ABS FAQ]]. If you need more information, please reference the man pages.<br />
<br />
== What is the Arch Build System? ==<br />
<br />
The Arch Build System (ABS for short) is a 'ports-like' system for building and packaging software from source code. While [[pacman]] is the specialized Arch tool for binary package management (including packages built with the ABS), ABS is a collection of tools for compiling source into installable {{Filename|.pkg.tar.gz}} packages.<br />
<br />
=== What is a ports-like system? ===<br />
<br />
'Ports' is a system used by *BSD, which allows source packages to be downloaded, unpacked, patched, compiled and installed. A 'port' is merely a small directory on the user's computer, named after the corresponding software to be installed, which contains a few files with instructions for downloading and installing an application from source (typically by navigating to the directory, or port, and doing 'make' and 'make install'). The system will then download, compile and install the desired software.<br />
<br />
=== '''ABS''' is a similar concept ===<br />
<br />
ABS is made up of a directory tree (the ABS tree) residing under {{Filename|/var/abs}}. This tree contains many subdirectories, each within a category and each named by their respective package. This tree represents (but does not contain) all ''official Arch software'', retrievable through the SVN system. You may refer to each package-named subdirectory as an 'ABS', much the way one would refer to a 'port'. These ABS (or subdirectories) do not contain the software package nor the source but rather a [[PKGBUILD]] file (and sometimes other files). A PKGBUILD is a simple BASH build script -- a text file containing the compilation and packaging instructions as well as the URL of the appropriate '''source''' tarball to be downloaded. (The most important component of ABS are PKGBUILDs.) By issuing the ABS [[makepkg]] command, the software is first compiled and then ''packaged'' within the build directory before being installed. Now you may use [[pacman]], the Arch Linux package manager, to install, upgrade, and remove your new package.<br />
<br />
=== ABS overview ===<br />
<br />
'ABS' may be used as an umbrella term, since it includes and relies on several other components. Therefore, though not technically accurate, 'ABS' can refer to the following structure and tools as a complete toolkit:<br />
<br />
; The ABS tree: The ABS directory structure; an SVN hierarchy under {{Filename|/var/abs/}} on your (local) machine. It contains many subdirectories, named for all available official Arch Linux software from repositories specified in {{Filename|/etc/abs.conf}}, but not the packages themselves.<br />
<br />
; ABS: A set of tools to retrieve and build '''official''' Arch Linux PKGBUILDs. Example PKGBUILDs are also included.<br />
<br />
; [[PKGBUILD]]s: Text build script files residing under the ABS directories, or that are custom made, with instructions for building packages and the URL of the sources. <br />
<br />
; [[makepkg]]: ABS shell command tool which reads the PKGBUILDs, automatically downloads and compiles the sources and creates a {{Filename|.pkg.tar.gz}}.<br />
<br />
; [[pacman]]: pacman is completely separate, but is necessarily invoked either by makepkg or manually to install and remove the built packages and for fetching dependencies.<br />
<br />
; [[AUR]]: The Arch User Repository is separate from ABS but [[AUR]] ([unsupported]) PKGBUILDs can be built using the ABS '''makepkg''' tool to compile and package up software. The AUR contains almost 16,000 user-contributed PKGBUILDs for software which is unavailable as an official Arch package. If you need to build a package outside the official Arch tree, chances are it is in the [[AUR]].<br />
<br />
== Why would I want to use ABS? ==<br />
<br />
The Arch Build System is used to:<br />
* Recompile a package, for any reason<br />
* Make and install new packages from source of software for which no packages are yet available (see [[Creating Packages]]) <br />
* Customize existing packages to fit your needs (enabling or disabling options, patching)<br />
* Rebuild your entire system using your compiler flags, "a la FreeBSD" (e.g. with [[pacbuilder]])<br />
* Cleanly build and install your own custom kernel (see [[Custom Kernel Compilation with ABS]] as well as [[Kernel Compilation]])<br />
* Get kernel modules working with your custom kernel<br />
* Easily compile and install a newer, older, beta, or development version of an Arch package by editing the version number in the PKGBUILD<br />
<br />
ABS is not necessary to use Arch Linux, but it is useful for automating certain tasks of source compilation.<br />
<br />
== Walkthrough ==<br />
<br />
''With the '''ABS tree''' in place, an Arch user has all available Arch software at their fingertips to compile from source, automatically package as a {{Filename|.pkg.tar.gz}}, and finally, install with pacman.''<br />
<br />
=== Quick overview ===<br />
<br />
Install the ABS package with {{Codeline|pacman -S abs}}. Running {{Codeline|abs}} as root creates the ABS tree by synchronizing with the Arch Linux server. If you wanted to build a package from source you would copy the build files (usually residing under {{Filename|/var/abs/<repo>/<pkgname>}}) to a build directory, navigate to that directory, edit the PKGBUILD (if desired/necessary) and do '''makepkg'''. According to instructions in the PKGBUILD, makepkg will download the appropriate source tarball, unpack it, patch if desired, compile according to CFLAGS specified in {{Filename|makepkg.conf}}, and finally compress the built files into a package with the extension {{Filename|.pkg.tar.gz}}. PKGBUILDs may be customized to suit your unique configuration needs, or for applying patches. Installing is as easy as doing {{Codeline|pacman -U <.pkg.tar.gz file>}}. Package removal is also handled by pacman.<br />
<br />
You may also use makepkg to make your own custom packages from the [[AUR]] or third-party sources. (See the [[Creating Packages]] wiki article.)<br />
<br />
=== Details ===<br />
<br />
To use abs, you first need to install '''abs''' from the [core] repository. This can be done simply by:<br />
<br />
# pacman -S abs<br />
<br />
This will grab the abs-sync scripts, various build scipts, and [[rsync]] (as a dependency, if you don't already have it).<br />
<br />
Before you can actually build anything, however, you will also need to grab basic compiling tools. These are handily collected in the package group '''base-devel'''. This group can be installed with:<br />
<br />
# pacman -S base-devel<br />
<br />
{{Warning | Remember this before complaining about missing (make)dependencies. The "base" group is assumed already installed in all Arch setups. The group "base-devel" is assumed already installed when building with makepkg.}}<br />
<br />
=== {{Filename|/etc/abs.conf}} ===<br />
<br />
As root, edit {{Filename|/etc/abs.conf}} to include your desired repositories:<br />
<br />
# vim /etc/abs.conf<br />
<br />
or:<br />
<br />
# nano /etc/abs.conf<br />
<br />
Remove the ! in front of the appropriate repos, e.g.:<br />
<br />
REPOS=(core extra community !testing)<br />
<br />
=== Download the ABS tree ===<br />
<br />
As root, run:<br />
<br />
# abs<br />
<br />
Your ABS tree is now created under {{Filename|/var/abs}}. Note the appropriate branches of the ABS tree now exist and correspond to the ones you specified in {{Filename|/etc/abs.conf}}. <br />
<br />
If you are an active developer, the abs command should also be run periodically to be in sync with the official repositories. If you are a casual developer, individual ABS package files can be downloaded by:<br />
<br />
# abs repository/package<br />
<br />
=== {{Filename|/etc/makepkg.conf}} ===<br />
<br />
{{Filename|/etc/makepkg.conf}} specifies global environment variables and compiler flags which you may wish to edit if you are using an SMP system, or to specify other desired optimizations. The default settings are for i686 and x86_64 optimizations which will work fine for those architectures on single-CPU systems. (The defaults will work on SMP machines, but will only use one core/CPU when compiling -- see [[makepkg.conf]].)<br />
<br />
=== The ABS tree ===<br />
<br />
When you run {{Codeline|abs}} for the first time, it synchronizes the ABS tree on the Arch Linux server to your computer. The ABS tree is an SVN directory hierarchy located under {{Filename|/var/abs}} and looks like this:<br />
<br />
<pre><br />
| -- core/<br />
| || -- base/<br />
| || || -- acl/<br />
| || || || -- PKGBUILD<br />
| || || -- attr/<br />
| || || || -- PKGBUILD<br />
| || || -- ...<br />
| || -- devel/<br />
| || || -- abs/<br />
| || || || -- PKGBUILD<br />
| || || -- autoconf/<br />
| || || || -- PKGBUILD<br />
| || || -- ...<br />
| || -- ...<br />
| -- extra/<br />
| || -- daemons/<br />
| || || -- acpid/<br />
| || || || -- PKGBUILD<br />
| || || || -- ...<br />
| || || -- apache/<br />
| || || || -- ...<br />
| || || -- ...<br />
| || -- ...<br />
| -- community/<br />
| || -- ...<br />
</pre><br />
<br />
The ABS tree has exactly the same structure as the package database:<br />
<br />
* First-level: Category directories<br />
* Second-level: Package name directories<br />
* Third level: PKGBUILD (contains information needed to build a package) and other related files (patches, other files needed for building the package)<br />
<br />
The source code for the package is not present in the ABS directory. Instead, the '''PKGBUILD''' file contains a URL that will download the source code when the package is built.<br />
<br />
=== Create a build directory ===<br />
<br />
You must create a build directory where the actual compiling will take place. This is where you'll do everything; you should never modify the ABS tree by building within it, as data will be lost (overwritten) on each ABS update. It is good practice to use your home directory, though some Arch users prefer to create a 'local' directory under {{Filename|/var/abs/}}, owned by a normal user. Copy the ABS from the tree ({{Filename|/var/abs/branch/category/pkgname}}) to the build directory, {{Filename|/path/to/build/dir}}.<br />
<br />
Create your build directory. e.g.:<br />
<br />
$ mkdir -p $HOME/abs<br />
<br />
{{Note | The first download of the abs tree is the biggest, then only minor updates are needed. Don't be afraid about the data to download if you've got only a 56K connection; it's only text files and is compressed during the transfer. For example, as of November 24, 2009, the abs tree that includes core, extra and community repositories is a ~16MB download (~56MB on disk).}}<br />
<br />
=== The build function, traditional method ===<br />
<br />
If you're not familiar with compiling from source, you should know that most packages (but not all) can be built from source in this '''traditional way''':<br />
<br />
* Download source tarball from remote server, using web browser, ftp, wget or alternate method.<br />
<br />
* Decompress the source file:<br />
$ tar -xzf foo-0.99.tar.gz<br />
or<br />
$ tar -xjf foo-0.99.tar.bz2<br />
<br />
* Enter the directory:<br />
$ cd foo-0.99<br />
<br />
* Configure the package. Generally, there is a script called {{Filename|configure}} in the source directory that is used to configure the package (add or remove support for things, choose the install destination, etc.) and check that your computer has all the software needed by the package. It can be run by:<br />
$ ./configure [option]<br />
<br />
You should first try the help to better understand how it works:<br />
$ ./configure --help<br />
<br />
If a {{Codeline|--prefix}} option is not passed to the script, ''most'' scripts will use {{Filename|/usr/local}} as the install path, but others will use {{Filename|/usr}}. For the sake of consistency, it is generally advised to pass the {{Codeline|1=--prefix=/usr/local}} option. It is good practice to install personal programs in {{Filename|/usr/local}}, and to have the ones being managed by the distro in {{Filename|/usr}}. This ensures personal program versions can coexist with those being managed by the distro's package manager -- in Arch's case, ''pacman''.<br />
$ ./configure --prefix=/usr/local<br />
<br />
* Compile the sources:<br />
<br />
$ make<br />
<br />
* Install:<br />
<br />
# make install<br />
<br />
* Removal would be accomplished by entering the source directory and running:<br />
<br />
# make uninstall<br />
<br />
However, you should always read the {{Filename|INSTALL}} file to know how the package should be built and installed! '''Not all packages use the <code>configure; make; make install</code> system!'''<br />
<br />
{{Note | The above traditional method of compiling source tarballs can, of course, still be used on Arch Linux. However, if you are not careful, files may become scattered throughout the filesystem that pacman (or any other package manager) will be unaware of. You should only use this method if you are experienced at manual compilation and system software tracking, as it can lead to future problems on Arch (or any distribution) if using a package manager.}}<br />
<br />
=== The build function, the ABS way ===<br />
<br />
ABS is an elegant tool which allows for powerful assistance and customization for the build process and creates a ''pacman-trackable'' package file for installation. The ABS method involves copying an ABS from the tree to a build directory, and doing makepkg. In our example, we will build the ''slim'' display manager package.<br />
<br />
Copy the slim ABS from the ABS tree to a build directory:<br />
$ cp -r /var/abs/extra/slim/ ~/abs<br />
<br />
Navigate to the build directory:<br />
$ cd ~/abs/slim<br />
<br />
Modify the PKGBUILD to add or remove support for components, to patch or to change package versions, etc. (optional):<br />
$ nano PKGBUILD<br />
<br />
Run makepkg as normal user (with {{Codeline|-s}} switch to install with automatic dependency handling):<br />
$ makepkg -s<br />
<br />
Install as root:<br />
# pacman -U slim-1.3.0-2-i686.pkg.tar.gz<br />
<br />
That's it. You have just built slim from source and cleanly installed it to your system with pacman. Package removal is also handled by pacman -- ({{Codeline|pacman -R slim}}).<br />
<br />
Essentially, the same steps are being executed as described in the traditional method (generally including the <code>./configure, make, make install</code> steps) but the software is installed into a ''fake root'' environment. (A ''fake root'' is simply a subdirectory within the build directory that functions and behaves as the system's root directory. In conjunction with the '''''fakeroot''''' program, makepkg creates a fake root directory, and installs the compiled binaries and associated files into it, with '''root''' as owner.) The ''fake root'', or subdirectory tree containing the compiled software, is then compressed into an archive with the extension {{Filename|.pkg.tar.gz}}, or a ''package''. When invoked, pacman then extracts the package (installs it) into the system's real root directory ({{Filename|/}}). Simple.<br />
<br />
''The ABS method adds a level of convenience and automation, while still maintaining complete transparency and control of the build and installation functions by including them in the PKGBUILD.''</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Arch_build_system&diff=97354Arch build system2010-02-18T22:21:45Z<p>Bhobbit: wording correction</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:Package development (English)]][[Category:Package management (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{i18n|Arch Build System}}<br />
{{Article summary start}}<br />
{{Article summary text|Description of the Arch Build System, a 'ports-like' system for building and packaging software from source code.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Arch Packaging Standards}}<br />
{{Article summary wiki|Arch User Repository}}<br />
{{Article summary wiki|Creating Packages}}<br />
{{Article summary wiki|Kernel Compilation with ABS}}<br />
{{Article summary wiki|makepkg}}<br />
{{Article summary wiki|makepkg.conf}}<br />
{{Article summary wiki|pacman}}<br />
{{Article summary wiki|pacman Tips}}<br />
{{Article summary wiki|PKGBUILD}}<br />
{{Article summary wiki|PKGBUILD Tricks}}<br />
{{Article summary end}}<br />
<br />
This article provides an overview of the Arch Build System along with a quick walkthrough for beginners. It is not a complete reference guide! If you need more information, please reference the man pages.<br />
<br />
== What is the Arch Build System? ==<br />
<br />
The Arch Build System (ABS for short) is a 'ports-like' system for building and packaging software from source code. While [[pacman]] is the specialized Arch tool for binary package management (including packages built with the ABS), ABS is a collection of tools for compiling source into an installable {{Filename|.pkg.tar.gz}} Arch packages.<br />
<br />
=== What is a ports-like system? ===<br />
<br />
'Ports' is a system used by *BSD, which allows source packages to be downloaded, unpacked, patched, compiled and installed. A 'port' is merely a small directory on the user's computer, named after the corresponding software to be installed, which contains a few files with instructions for downloading and installing an application from source (typically by navigating to the directory, or port, and doing 'make' and 'make install'). The system will then download, compile and install the desired software.<br />
<br />
=== '''ABS''' is a similar concept ===<br />
<br />
ABS is made up of a directory tree (the ABS tree) residing under {{Filename|/var/abs}}. This tree contains many subdirectories, each within a category and each named by their respective package. This tree represents (but does not contain) all ''official Arch software'', retrievable through the SVN system. You may refer to each package-named subdirectory as an 'ABS', much the way one would refer to a 'port'. These ABS (or subdirectories) do not contain the software package nor the source but rather a [[PKGBUILD]] file (and sometimes other files). A PKGBUILD is a simple BASH build script -- a text file containing the compilation and packaging instructions as well as the URL of the appropriate '''source''' tarball to be downloaded. (The most important component of ABS are PKGBUILDs.) By issuing the ABS [[makepkg]] command, the software is first compiled and then ''packaged'' within the build directory before being installed. Now you may use [[pacman]], the Arch Linux package manager, to install, upgrade, and remove your new package.<br />
<br />
=== ABS overview ===<br />
<br />
'ABS' may be used as an umbrella term, since it includes and relies on several other components. Therefore, though not technically accurate, 'ABS' can refer to the following structure and tools as a complete toolkit:<br />
<br />
; The ABS tree: The ABS directory structure; an SVN hierarchy under {{Filename|/var/abs/}} on your (local) machine. It contains many subdirectories, named for all available official Arch Linux software from repositories specified in {{Filename|/etc/abs.conf}}, but not the packages themselves.<br />
<br />
; ABS: A set of tools to retrieve and build '''official''' Arch Linux PKGBUILDs. Example PKGBUILDs are also included.<br />
<br />
; [[PKGBUILD]]s: Text build script files residing under the ABS directories, or that are custom made, with instructions for building packages and the URL of the sources. <br />
<br />
; [[makepkg]]: ABS shell command tool which reads the PKGBUILDs, automatically downloads and compiles the sources and creates a {{Filename|.pkg.tar.gz}}.<br />
<br />
; [[pacman]]: pacman is completely separate, but is necessarily invoked either by makepkg or manually to install and remove the built packages and for fetching dependencies.<br />
<br />
; [[AUR]]: The Arch User Repository is separate from ABS but [[AUR]] ([unsupported]) PKGBUILDs can be built using the ABS '''makepkg''' tool to compile and package up software. The AUR contains almost 16,000 user-contributed PKGBUILDs for software which is unavailable as an official Arch package. If you need to build a package outside the official Arch tree, chances are it is in the [[AUR]].<br />
<br />
== Why would I want to use ABS? ==<br />
<br />
The Arch Build System is used to:<br />
* Recompile a package, for any reason<br />
* Make and install new packages from source of software for which no packages are yet available (see [[Creating Packages]]) <br />
* Customize existing packages to fit your needs (enabling or disabling options, patching)<br />
* Rebuild your entire system using your compiler flags, "a la FreeBSD" (e.g. with [[pacbuilder]])<br />
* Cleanly build and install your own custom kernel (see [[Custom Kernel Compilation with ABS]] as well as [[Kernel Compilation]])<br />
* Get kernel modules working with your custom kernel<br />
* Easily compile and install a newer, older, beta, or development version of an Arch package by editing the version number in the PKGBUILD<br />
<br />
ABS is not necessary to use Arch Linux, but it is useful for automating certain tasks of source compilation.<br />
<br />
== Walkthrough ==<br />
<br />
''With the '''ABS tree''' in place, an Arch user has all available Arch software at their fingertips to compile from source, automatically package as a {{Filename|.pkg.tar.gz}}, and finally, install with pacman.''<br />
<br />
=== Quick overview ===<br />
<br />
Install the ABS package with {{Codeline|pacman -S abs}}. Running {{Codeline|abs}} as root creates the ABS tree by synchronizing with the Arch Linux server. If you wanted to build a package from source you would copy the build files (usually residing under {{Filename|/var/abs/<repo>/<pkgname>}}) to a build directory, navigate to that directory, edit the PKGBUILD (if desired/necessary) and do '''makepkg'''. According to instructions in the PKGBUILD, makepkg will download the appropriate source tarball, unpack it, patch if desired, compile according to CFLAGS specified in {{Filename|makepkg.conf}}, and finally compress the built files into a package with the extension {{Filename|.pkg.tar.gz}}. PKGBUILDs may be customized to suit your unique configuration needs, or for applying patches. Installing is as easy as doing {{Codeline|pacman -U <.pkg.tar.gz file>}}. Package removal is also handled by pacman.<br />
<br />
You may also use makepkg to make your own custom packages from the [[AUR]] or third-party sources. (See the [[Creating Packages]] wiki article.)<br />
<br />
=== Details ===<br />
<br />
To use abs, you first need to install '''abs''' from the [core] repository. This can be done simply by:<br />
<br />
# pacman -S abs<br />
<br />
This will grab the abs-sync scripts, various build scipts, and [[rsync]] (as a dependency, if you don't already have it).<br />
<br />
Before you can actually build anything, however, you will also need to grab basic compiling tools. These are handily collected in the package group '''base-devel'''. This group can be installed with:<br />
<br />
# pacman -S base-devel<br />
<br />
{{Warning | Remember this before complaining about missing (make)dependencies. The "base" group is assumed already installed in all Arch setups. The group "base-devel" is assumed already installed when building with makepkg.}}<br />
<br />
=== {{Filename|/etc/abs.conf}} ===<br />
<br />
As root, edit {{Filename|/etc/abs.conf}} to include your desired repositories:<br />
<br />
# vim /etc/abs.conf<br />
<br />
or:<br />
<br />
# nano /etc/abs.conf<br />
<br />
Remove the ! in front of the appropriate repos, e.g.:<br />
<br />
REPOS=(core extra community !testing)<br />
<br />
=== Download the ABS tree ===<br />
<br />
As root, run:<br />
<br />
# abs<br />
<br />
Your ABS tree is now created under {{Filename|/var/abs}}. Note the appropriate branches of the ABS tree now exist and correspond to the ones you specified in {{Filename|/etc/abs.conf}}. <br />
<br />
If you are an active developer, the abs command should also be run periodically to be in sync with the official repositories. If you are a casual developer, individual ABS package files can be downloaded by:<br />
<br />
# abs repository/package<br />
<br />
=== {{Filename|/etc/makepkg.conf}} ===<br />
<br />
{{Filename|/etc/makepkg.conf}} specifies global environment variables and compiler flags which you may wish to edit if you are using an SMP system, or to specify other desired optimizations. The default settings are for i686 and x86_64 optimizations which will work fine for those architectures on single-CPU systems. (The defaults will work on SMP machines, but will only use one core/CPU when compiling -- see [[makepkg.conf]].)<br />
<br />
=== The ABS tree ===<br />
<br />
When you run {{Codeline|abs}} for the first time, it synchronizes the ABS tree on the Arch Linux server to your computer. The ABS tree is an SVN directory hierarchy located under {{Filename|/var/abs}} and looks like this:<br />
<br />
<pre><br />
| -- core/<br />
| || -- base/<br />
| || || -- acl/<br />
| || || || -- PKGBUILD<br />
| || || -- attr/<br />
| || || || -- PKGBUILD<br />
| || || -- ...<br />
| || -- devel/<br />
| || || -- abs/<br />
| || || || -- PKGBUILD<br />
| || || -- autoconf/<br />
| || || || -- PKGBUILD<br />
| || || -- ...<br />
| || -- ...<br />
| -- extra/<br />
| || -- daemons/<br />
| || || -- acpid/<br />
| || || || -- PKGBUILD<br />
| || || || -- ...<br />
| || || -- apache/<br />
| || || || -- ...<br />
| || || -- ...<br />
| || -- ...<br />
| -- community/<br />
| || -- ...<br />
</pre><br />
<br />
The ABS tree has exactly the same structure as the package database:<br />
<br />
* First-level: Category directories<br />
* Second-level: Package name directories<br />
* Third level: PKGBUILD (contains information needed to build a package) and other related files (patches, other files needed for building the package)<br />
<br />
The source code for the package is not present in the ABS directory. Instead, the '''PKGBUILD''' file contains a URL that will download the source code when the package is built.<br />
<br />
=== Create a build directory ===<br />
<br />
You must create a build directory where the actual compiling will take place. This is where you'll do everything; you should never modify the ABS tree by building within it, as data will be lost (overwritten) on each ABS update. It is good practice to use your home directory, though some Arch users prefer to create a 'local' directory under {{Filename|/var/abs/}}, owned by a normal user. Copy the ABS from the tree ({{Filename|/var/abs/branch/category/pkgname}}) to the build directory, {{Filename|/path/to/build/dir}}.<br />
<br />
Create your build directory. e.g.:<br />
<br />
$ mkdir -p $HOME/abs<br />
<br />
{{Note | The first download of the abs tree is the biggest, then only minor updates are needed. Don't be afraid about the data to download if you've got only a 56K connection; it's only text files and is compressed during the transfer. For example, as of November 24, 2009, the abs tree that includes core, extra and community repositories is a ~16MB download (~56MB on disk).}}<br />
<br />
=== The build function, traditional method ===<br />
<br />
If you're not familiar with compiling from source, you should know that most packages (but not all) can be built from source in this '''traditional way''':<br />
<br />
* Download source tarball from remote server, using web browser, ftp, wget or alternate method.<br />
<br />
* Decompress the source file:<br />
$ tar -xzf foo-0.99.tar.gz<br />
or<br />
$ tar -xjf foo-0.99.tar.bz2<br />
<br />
* Enter the directory:<br />
$ cd foo-0.99<br />
<br />
* Configure the package. Generally, there is a script called {{Filename|configure}} in the source directory that is used to configure the package (add or remove support for things, choose the install destination, etc.) and check that your computer has all the software needed by the package. It can be run by:<br />
$ ./configure [option]<br />
<br />
You should first try the help to better understand how it works:<br />
$ ./configure --help<br />
<br />
If a {{Codeline|--prefix}} option is not passed to the script, ''most'' scripts will use {{Filename|/usr/local}} as the install path, but others will use {{Filename|/usr}}. For the sake of consistency, it is generally advised to pass the {{Codeline|1=--prefix=/usr/local}} option. It is good practice to install personal programs in {{Filename|/usr/local}}, and to have the ones being managed by the distro in {{Filename|/usr}}. This ensures personal program versions can coexist with those being managed by the distro's package manager -- in Arch's case, ''pacman''.<br />
$ ./configure --prefix=/usr/local<br />
<br />
* Compile the sources:<br />
<br />
$ make<br />
<br />
* Install:<br />
<br />
# make install<br />
<br />
* Removal would be accomplished by entering the source directory and running:<br />
<br />
# make uninstall<br />
<br />
However, you should always read the {{Filename|INSTALL}} file to know how the package should be built and installed! '''Not all packages use the <code>configure; make; make install</code> system!'''<br />
<br />
{{Note | The above traditional method of compiling source tarballs can, of course, still be used on Arch Linux. However, if you are not careful, files may become scattered throughout the filesystem that pacman (or any other package manager) will be unaware of. You should only use this method if you are experienced at manual compilation and system software tracking, as it can lead to future problems on Arch (or any distribution) if using a package manager.}}<br />
<br />
=== The build function, the ABS way ===<br />
<br />
ABS is an elegant tool which allows for powerful assistance and customization for the build process and creates a ''pacman-trackable'' package file for installation. The ABS method involves copying an ABS from the tree to a build directory, and doing makepkg. In our example, we will build the ''slim'' display manager package.<br />
<br />
Copy the slim ABS from the ABS tree to a build directory:<br />
$ cp -r /var/abs/extra/slim/ ~/abs<br />
<br />
Navigate to the build directory:<br />
$ cd ~/abs/slim<br />
<br />
Modify the PKGBUILD to add or remove support for components, to patch or to change package versions, etc. (optional):<br />
$ nano PKGBUILD<br />
<br />
Run makepkg as normal user (with {{Codeline|-s}} switch to install with automatic dependency handling):<br />
$ makepkg -s<br />
<br />
Install as root:<br />
# pacman -U slim-1.3.0-2-i686.pkg.tar.gz<br />
<br />
That's it. You have just built slim from source and cleanly installed it to your system with pacman. Package removal is also handled by pacman -- ({{Codeline|pacman -R slim}}).<br />
<br />
Essentially, the same steps are being executed as described in the traditional method (generally including the <code>./configure, make, make install</code> steps) but the software is installed into a ''fake root'' environment. (A ''fake root'' is simply a subdirectory within the build directory that functions and behaves as the system's root directory. In conjunction with the '''''fakeroot''''' program, makepkg creates a fake root directory, and installs the compiled binaries and associated files into it, with '''root''' as owner.) The ''fake root'', or subdirectory tree containing the compiled software, is then compressed into an archive with the extension {{Filename|.pkg.tar.gz}}, or a ''package''. When invoked, pacman then extracts the package (installs it) into the system's real root directory ({{Filename|/}}). Simple.<br />
<br />
''The ABS method adds a level of convenience and automation, while still maintaining complete transparency and control of the build and installation functions by including them in the PKGBUILD.''</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Talk:Pacman/Rosetta&diff=97347Talk:Pacman/Rosetta2010-02-18T20:58:30Z<p>Bhobbit: A little praise :)</p>
<hr />
<div>This is one the most useful references of them all. I could never remember apt-get options (which is one of the reasons I switched from Ubuntu to Arch), but I can remember pacman commands just fine. Rather than google how to do a package management task with apt-get, I look up equivalents of pacman commands on this page. --[[User:Bhobbit|Bhobbit]] 15:58, 18 February 2010 (EST)</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Talk:Kernel_Compilation_with_ABS&diff=93651Talk:Kernel Compilation with ABS2010-01-26T07:11:16Z<p>Bhobbit: moved Talk:Kernel Compilation with ABS to Talk:IceRAM's Kernel PKGBUILD:&#32;Confusing page title. The article has nothing to do with ABS.</p>
<hr />
<div>#REDIRECT [[Talk:IceRAM's Kernel PKGBUILD]]</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Kernel_Compilation_with_ABS&diff=93649Kernel Compilation with ABS2010-01-26T07:11:16Z<p>Bhobbit: moved Kernel Compilation with ABS to IceRAM's Kernel PKGBUILD:&#32;Confusing page title. The article has nothing to do with ABS.</p>
<hr />
<div>#REDIRECT [[IceRAM's Kernel PKGBUILD]]</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Accents_on_US_keyboards&diff=88517Accents on US keyboards2009-12-21T21:53:56Z<p>Bhobbit: Added a note that xkeycaps is in repo</p>
<hr />
<div>[[Category: Input devices (English)]]<br />
{{i18n_links_start}}<br />
{{i18n_entry|English|Accents on US keyboards}}<br />
{{i18n_entry|Español|Acentos en teclados US (Español)}}<br />
{{i18n_links_end}}<br />
Typing in foreign languages such as French, Italian and German can be problematic on an American keyboard. To remedy this, the Xmodmap utility that is supplied with Xorg allows user to completely remap the keyboard. The following is an example configuration:<br />
<br />
Note: AltGr is the Alt key on the right-hand side of the space bar.<br />
<br />
AltGr + e -> é<br />
AltGr + r -> è<br />
AltGr + a -> à<br />
AltGr + u -> ù<br />
AltGr + i -> ì<br />
AltGr + o -> ò<br />
AltGr + c -> ç<br />
AltGr + [ -> «<br />
AltGr + ] -> »<br />
AltGr + ; -> dead diaresis (ï, ü, etc.)<br />
AltGr + 6 -> dead circumflex (î, ê, etc.) <br />
<br />
= A useful utility to produce a xmodmap file =<br />
<br />
On [http://www.jwz.org/xkeycaps this page] you'll find XKeyCaps, a graphical front-end to xmodmap which makes it easier to produce an ideal xmodmap file. XKeyCaps is available from the community repository and can be installed with ''pacman'':<br />
# pacman -S xkeycaps<br />
<br />
= Example xmodmap file =<br />
<br />
This is an xmodmap file which remaps keys to match the above example.<br />
<br />
clear Mod1<br />
clear Mod2<br />
! us.map with a few redefinitions<br />
keycode 9 = Escape Escape<br />
keycode 10 = 1 exclam<br />
keycode 11 = 2 at at<br />
keycode 12 = 3 numbersign<br />
keycode 13 = 4 dollar dollar<br />
keycode 14 = 5 percent currency<br />
keycode 15 = 6 asciicircum dead_circumflex<br />
keycode 16 = 7 ampersand braceleft<br />
keycode 17 = 8 asterisk bracketleft<br />
keycode 18 = 9 parenleft bracketright<br />
keycode 19 = 0 parenright braceright<br />
keycode 20 = minus underscore backslash<br />
keycode 21 = equal plus<br />
keycode 22 = BackSpace Delete<br />
keycode 23 = Tab Tab<br />
keycode 24 = q<br />
keycode 25 = w<br />
keycode 26 = e E eacute<br />
keycode 27 = r R egrave<br />
keycode 28 = t<br />
keycode 29 = y<br />
keycode 30 = u U ugrave<br />
keycode 31 = i I igrave<br />
keycode 32 = o O ograve<br />
keycode 33 = p<br />
keycode 34 = bracketleft braceleft guillemotleft<br />
keycode 35 = bracketright braceright guillemotright<br />
keycode 36 = Return<br />
keycode 37 = Control_L<br />
keycode 38 = a A agrave<br />
keycode 39 = s<br />
keycode 40 = d<br />
keycode 41 = f<br />
keycode 42 = g<br />
keycode 43 = h<br />
keycode 44 = j<br />
keycode 45 = k<br />
keycode 46 = l<br />
keycode 47 = semicolon colon dead_diaeresis<br />
keycode 48 = apostrophe quotedbl<br />
keycode 49 = grave asciitilde dead_grave<br />
keycode 50 = Shift_L<br />
keycode 51 = backslash bar<br />
keycode 52 = z<br />
keycode 53 = x<br />
keycode 54 = c C ccedilla<br />
keycode 55 = v<br />
keycode 56 = b<br />
keycode 57 = n<br />
keycode 58 = m<br />
keycode 59 = comma less apostrophe<br />
keycode 60 = period greater quotedbl<br />
keycode 61 = slash question<br />
keycode 62 = Shift_R<br />
keycode 63 = KP_Multiply<br />
keycode 64 = Alt_L Meta_L<br />
keycode 65 = space space<br />
keycode 66 = Caps_Lock<br />
keycode 67 = F1 F11<br />
keycode 68 = F2 F12<br />
keycode 69 = F3 F13<br />
keycode 70 = F4 F14<br />
keycode 71 = F5 F15<br />
keycode 72 = F6 F16<br />
keycode 73 = F7 F17<br />
keycode 74 = F8 F18<br />
keycode 75 = F9 F19<br />
keycode 76 = F10 F20<br />
keycode 77 = Num_Lock<br />
keycode 78 = Scroll_Lock<br />
keycode 79 = KP_7<br />
keycode 80 = KP_8<br />
keycode 81 = KP_9<br />
keycode 82 = KP_Subtract<br />
keycode 83 = KP_4<br />
keycode 84 = KP_5<br />
keycode 85 = KP_6<br />
keycode 86 = KP_Add<br />
keycode 87 = KP_1<br />
keycode 88 = KP_2<br />
keycode 89 = KP_3<br />
keycode 90 = KP_0<br />
keycode 94 = less greater bar<br />
keycode 95 = F11 F11<br />
keycode 96 = F12 F12<br />
keycode 108 = KP_Enter<br />
keycode 109 = Control_R<br />
keycode 112 = KP_Divide<br />
keycode 113 = Mode_switch<br />
keycode 114 = Break<br />
keycode 110 = Find<br />
keycode 98 = Up<br />
keycode 99 = Prior<br />
keycode 100 = Left<br />
keycode 102 = Right<br />
keycode 115 = Select<br />
keycode 104 = Down<br />
keycode 105 = Next<br />
keycode 106 = Insert<br />
keycode 116 = Mode_switch<br />
! right windows-menu key, redefined as Compose key<br />
keycode 117 = Multi_key<br />
add Mod1 = Alt_L<br />
add Mod2 = Mode_switc<br />
<br />
= What to do with the xmodmap file =<br />
<br />
To use this configuration, put it in a hidden file called xmodmaprc in your home directory:<br />
<br />
~/.xmodmaprc<br />
<br />
Some desktop environments such as [[GNOME]] will automatically detect the file and ask you if you want to use it. If you are using a desktop environment or a window manager which does not do this, you will have to add a line to an executable file called .xinitrc, located in your home directory. This file contains a list of commands that are executed after you log in. <br />
<br />
If you already have a .xinitrc file, type these commands in a terminal:<br />
<br />
cd<br />
echo "xmodmap ~/.xmodmaprc" >> .xinitrc<br />
<br />
If you don't have a .xinitrc file, do this:<br />
<br />
cd<br />
echo "xmodmap ~/.xmodmaprc" > .xinitrc<br />
chmod 755 .xinitrc</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Talk:Namcap&diff=85939Talk:Namcap2009-12-02T04:28:44Z<p>Bhobbit: Section removal suggestion</p>
<hr />
<div>I think the whole section listing namcap tags should be removed - all the tags are listed and documented in namcap manpage. --[[User:Bhobbit|Bhobbit]] 23:28, 1 December 2009 (EST)</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Talk:CurlFtpFS&diff=85938Talk:CurlFtpFS2009-12-02T04:25:40Z<p>Bhobbit: Expansion suggestion</p>
<hr />
<div>This is page is the first result in Google if one searches for 'mount ftp'. It would be nice to expand it. --[[User:Bhobbit|Bhobbit]] 23:25, 1 December 2009 (EST)</div>Bhobbithttps://wiki.archlinux.org/index.php?title=CurlFtpFS&diff=85937CurlFtpFS2009-12-02T04:24:12Z<p>Bhobbit: Deleted outdated info and replaced with an introduction; removed misleading link; formatting</p>
<hr />
<div>[[Category:File systems (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{Expansion}}<br />
<br />
There are several packages available from the community repository or [[AUR]] that allow to mount FTP shares and interact with them just as if they were local file systems.<br />
<br />
== Packages ==<br />
These are the packages that provide a way to mount FTP shares:<br />
<br />
* curlftpfs [recommended]<br />
* fuseftp<br />
* lufs [outdated]<br />
<br />
All three packages are based on FUSE library.<br />
<br />
=== Example using curlftpfs to mount a FTP folder ===<br />
<br />
Install curlftpfs (from the community repo)<br />
# pacman -S curlftpfs<br />
<br />
If needed, make sure that fuse has been started.<br />
# modprobe fuse<br />
Create the mount point and then mount the FTP folder.<br />
# mkdir /mnt/ftp<br />
# curlftpfs ftp.yourserver.com /mnt/ftp/ -o user=username:password<br />
If you want regular user access, use the following instead:<br />
# curlftpfs ftp.yourserver.com /mnt/ftp/ -o user=username:password,allow_other<br />
Do not add space after the comma or the ''allow_other'' argument won't be recognized.<br />
<br />
You can add this line to /etc/fstab to mount automatically.<br />
curlftpfs#user:password@my.domain.com /mnt/mydomaincom fuse rw,uid=500,user 0 0</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Creating_packages&diff=85667Creating packages2009-11-29T06:57:53Z<p>Bhobbit: file template</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:Package development (English)]]<br />
[[Category:Guidelines (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|A detailed HOWTO covering the entire package building process.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Building Packages in Arch Linux}}<br />
{{Article summary heading|Related articles}}<br />
{{Article summary wiki|ABS - The Arch Build System}}<br />
{{Article summary wiki|Arch Linux User-Community Repository (AUR)}}<br />
{{Article summary wiki|makepkg}}<br />
{{Article summary wiki|pacman}}<br />
{{Article summary wiki|PKGBUILD Tricks}}<br />
{{Article summary wiki|PKGBUILD Variables}}<br />
{{Article summary wiki|VCS PKGBUILD guidelines}}<br />
{{Article summary end}}<br />
<br />
All information for creating a package is placed in a {{Filename|PKGBUILD}} file. When you run {{Codeline|makepkg}}, it will look for a {{Filename|PKGBUILD}} file in the current working directory, and compile the software's source code according to the instructions in the {{Filename|PKGBUILD}} file. After successfully finishing the compilation, the resulting binaries, as well as all available meta-information like package version and dependencies, are packed in the {{Filename|name.pkg.tar.gz}} package file that can be cleanly installed with {{Codeline|pacman -U <package file>}}.<br />
<br />
== Setting up ==<br />
<br />
First, verify that you have the necessary tools installed. You need the following packages:<br />
*'''base-devel''' (a package group): Contains ''make'' and additional tools for compiling from the source.<br />
*'''fakeroot''' (part of 'base-devel'): Allows a normal user the necessary root permissions to create packages in the build environment without being able to alter the wider system. If the build process attempts to alter files outside of the build environment, errors are produced and the build fails. This is very useful for checking the quality, safety and integrity of the packages for distribution.<br />
<br />
If you do not have them, install them using ''pacman'':<br />
# pacman -S base-devel fakeroot<br />
<br />
One of the key tools for building packages is ''makepkg''. It does the following:<br />
#Checks if package dependencies are installed.<br />
#Downloads the source file(s) from the specified server(s).<br />
#Unpacks the source file(s).<br />
#Compiles the software and installs it under a fakeroot environment.<br />
#Strips symbols from binaries and libraries.<br />
#Generates the package meta file which is included with each package.<br />
#Compress the fakeroot environment into a package file.<br />
#Stores the package file in the configured destination directory, which is the present working directory by default.<br />
<br />
=== ABS ===<br />
<br />
If you want to rebuild binary packages from the official Arch Linux repositories, you should also install the [[Arch Build System]], {{Codeline|abs}}:<br />
# pacman -S abs<br />
<br />
The {{Codeline|abs}} package allows you to sync all the {{Filename|PKGBUILD}}s and local source files used to build the official packages. You do not need {{Codeline|abs}} to use {{Codeline|makepkg}} and if you only need a few {{Filename|PKGBUILD}}s, you can retrieve the latest versions from the web interface directly or via other available tools such as [http://xyne.archlinux.ca/info/pbget pbget]<br />
<br />
{{Codeline|abs}} also helps you keep all of your {{Filename|PKGBUILD}} files, both official and unofficial in a centralized location. You can specify which repositories to include in your ABS tree in the {{Filename|/etc/abs.conf}} file. To obtain the ABS tree which contains all of the {{Filename|PKGBUILD}} files, just run the {{Codeline|abs}} command as root:<br />
# abs<br />
<br />
Create an ABS build directory under the {{Filename|/home}} of your non-root user, if you have not done so already: <br />
$ mkdir ~/abs<br />
<br />
== Package file ==<br />
<br />
An Arch package is, in fact, no more than a gzipped tar archive or 'tarball' which contains:<br />
<br />
* The files to install<br />
<br />
* {{Filename|.PKGINFO}}: contains all the metadata needed by pacman to deal with packages, dependencies, etc.<br />
<br />
* {{Filename|.INSTALL}}: a file used to execute commands after the install/upgrade/remove stage. (This file is present only if specified in the {{Filename|PKGBUILD}}.)<br />
<br />
* {{Filename|.Changelog}}: a file kept by the package maintainer documenting the changes of the package. It is not present in all packages.<br />
<br />
== Preparing the files ==<br />
<br />
Download the source tarball of the software you want to package, extract it, and note all commands needed to compile and install it. You will be repeating the same commands in the ''PKGBUILD'' file. Most software authors stick to the 3-step build cycle:<br />
./configure<br />
make<br />
make install<br />
When you run {{Codeline|makepkg}}, it will look for a {{Filename|PKGBUILD}} file in the present working directory. If a {{Filename|PKGBUILD}} file is found it will download the software's source code and compile it according to the instructions specified in the {{Filename|PKGBUILD}} file. The instructions must be fully interpretable by [[Wikipedia:Bash|Bash]]. After successful compilation, the resulting binaries and metadata of the package, i.e. package version and dependencies, are packed in a {{Filename|pkgname.pkg.tar.gz}} package file that can be cleanly installed with {{Codeline|pacman -U [package file]}}.<br />
To start out with a new package, you should first create an empty working directory, preferably named {{Filename|~/abs/'''pkgname'''}}. Once you make the directory and change into it, create a {{Filename|PKGBUILD}} file to work with either by copying the prototype from {{Filename|/usr/share/pacman/PKGBUILD.proto}} or by copying a {{Filename|PKGBUILD}} from another package. The latter is quite useful if you want to modify compilation options of a package instead of creating an entirely new one.<br />
<br />
== Defining PKGBUILD variables ==<br />
<br />
The {{Filename|PKGBUILD}} file contains metadata about a package. It is a plain text file. The following is a prototype {{Filename|PKGBUILD}}. It can be found in {{Filename|/usr/share/pacman}} along with other templates.<br />
<br />
{{File|name=/usr/share/pacman/PKGBUILD.proto|content=<br />
# This is an example PKGBUILD file. Use this as a start to creating your own,<br />
# and remove these comments. For more information, see 'man PKGBUILD'.<br />
# Note: Please fill out the license field for your package. If it is unknown,<br />
# then please put 'unknown'.<br />
<br />
# Contributor: Your Name <youremail@domain.com><br />
pkgname=NAME<br />
pkgver=VERSION<br />
pkgrel=1<br />
pkgdesc=""<br />
arch=()<br />
url=""<br />
license=('GPL')<br />
groups=()<br />
depends=()<br />
makedepends=()<br />
provides=()<br />
conflicts=()<br />
replaces=()<br />
backup=()<br />
install=<br />
source=($pkgname-$pkgver.tar.gz)<br />
noextract=()<br />
md5sums=() #generate with 'makepkg -g'<br />
<br />
build() {<br />
cd "$srcdir/$pkgname-$pkgver"<br />
<br />
./configure --prefix=/usr<br />
make || return 1<br />
make DESTDIR="$pkgdir/" install<br />
}<br />
}}<br />
<br />
A listing of possible {{Filename|PKGBUILD}} variables and their meaning can be found on [[PKGBUILD Variables]] page.<br />
<br />
== The build() function ==<br />
<br />
Now you need to implement the ''build()'' function in the ''PKGBUILD'' file. This function uses common shell commands in the [http://en.wikipedia.org/wiki/Bash Bash] syntax to automatically compile software and create a ''pkg/'' directory to install the software to. This allows ''makepkg'' to pack it up without having to pick all the necessary files from your actual filesystem.<br />
The first step in the ''build()'' function is to change into the directory created by uncompressing the source tarball. In most common cases the first command will look like this:<br />
cd $srcdir/$pkgname-$pkgver<br />
<br />
Now, you need to list the same commands you used when you manually compiled the software. The ''build()'' function in essence automates everything you did by hand and compiles the software in the fakeroot build environment. If the software you are packaging uses a configure script, it is good practice to use ''--prefix=/usr'' when building packages for ''pacman''. A lot of software install their files relative to the ''/usr/local'' directory, which should only be done if you are manually building from source. All Arch Linux packages should use the ''/usr'' directory. As seen in the ''/usr/share/pacman/PKGBUILD.proto'' file, the next two lines should look like this:<br />
./configure --prefix=/usr<br />
make || return 1<br />
<br />
The final step in the ''build()'' funciton is to put the compiled files in a directory where ''makepkg'' can retrieve to create a package. This by default is the ''pkg/'' directory - a simple fakeroot environment. It imitates the root of your filesystem to the software's installation procedure. If you have to manually install files under the root of your filesystem, you should instead install it in the ''pkg/'' directory under the same directory structure, e.g. if you want to install a file to ''/usr/bin'', it should instead be placed under ''$pkgdir/usr/bin''. Very few software require the user to copy dozens of files manually, and you usually will not have to worry about this. Instead, for most software you will have to call ''make install''. The final line should look like the following in order to correctly install the software in the ''pkg/'' directory:<br />
make DESTDIR=$pkgdir install || return 1<br />
<br />
'''Note''': It is sometimes the case where <code>DESTDIR</code> is not used in the <code>Makefile</code>; you may need to use <code>prefix</code> instead. If the package is built with autoconf/automake, use <code>DESTDIR</code>; this is what is [http://sources.redhat.com/automake/automake.html#Install documented] in the manuals. If <code>DESTDIR</code> does not work, try building with <code>make prefix="$pkgdir/usr/" install</code>. If that does not work, you'll have to look further into the install commands that are executed by "<code>make <...> install</code>".<br />
<br />
In some odd cases, the software expects to be run from a single directory. In such cases it is wise to simply copy these to ''$pkgdir/opt''.<br />
More often than not the installation process of the software will create any subdirectories below the ''pkg/'' directory. If it does not, however, ''makepkg'' will generate a lot of errors and you will need to manually create subdirectories by adding the appropriate ''mkdir -p'' commands in the ''build()'' function before the installation procedure is run.<br />
Also, ''makepkg'' defines three variables that you should use as part of the build and install process:<br />
*'''''startdir''''' - This contains the absolute path to the directory where the ''PKGBUILD'' file is located, which is the present working directory. This variable is almost always used in combination with ''/src'' or ''/pkg'' postfixes, but the use of ''srcdir'' and ''pkgdir'' variables is preferred.<br />
*'''''srcdir''''' - This points to the directory where ''makepkg'' extracts or copies all source files. It is currently an alias for ''$startdir/src''.<br />
*'''''pkgdir''''' - This points to the directory where ''makepkg'' bundles the installed package, which becomes the root directory of your built package. It is currently an alias for ''$startdir/pkg''.<br />
<br />
'''Note:''' makepkg, and thus the build() function, is intended to be non-interactive. Interactive utilities or scripts called in the build() function may break makepkg, particularly if it is invoked with build-logging enabled (-l). (see [http://bugs.archlinux.org/task/13214 Arch Linux Bug #13214].)<br />
<br />
== Additional guidelines ==<br />
<br />
Here are some additional guidelines that you should adhere to:<br />
*All elements in an array variable '''must be separated by spaces'''.<br />
*If possible, remove empty lines from the ''PKGBUILD'' including fields that have empty values.<br />
*Wherever possible, use ''|| return 1'' for critical build functions: make || return 1 make DESTDIR=$pkgdir install || return 1 <br />
*'''Do not introduce new variables''' into your ''PKGBUILD'' file unless the package cannot be built without doing so, as these could possibly conflict with variables used in ''makepkg'' itself. If a new variable is absolutely required, '''prefix the variable name with an underscore''': _customvariable= <br />
*'''Avoid''' using ''/usr/libexec/'' for anything. Use ''/usr/lib/pkgname'' instead.<br />
*The ''packager'' field from the package meta file can be customized by the package builder by modifying the appropriate option in the ''/etc/makepkg.conf'' file, or alternatively by exporting the ''PACKAGER'' environment variable before building packages with ''makepkg'': # export PACKAGER="Your Name &lt;email@domain.com&gt;" <br />
* '''Configuration files''' should be placed in the ''/etc'' directory. If there is more than one configuration file, it is customary to use a subdirectory in order to keep the ''/etc'' area as clean as possible. Use ''/etc/'''pkgname''''' or a suitable alternative, e.g., [http://httpd.apache.org/ Apache] uses ''/etc/httpd/''. <br />
*Package files should follow these '''general directory guidelines''': <br />
**''/etc/'' - System essential configuration files<br />
**''/usr/bin'' - Application binaries<br />
**''/usr/sbin'' - System binaries<br />
**''/usr/lib'' - Libraries<br />
**''/usr/include'' - Header files<br />
**''/usr/lib/pkgname'' - Modules, plugins, etc.<br />
**''/usr/share/man'' - Manpages<br />
**''/usr/share/pkgname'' - Application data<br />
**''/usr/share/licenses/pkgname'' - Package license, if not included under common<br />
**''/etc/pkgname'' - Configuration files<br />
**''/opt'' - Large self-contained packages such as Java, etc.<br />
<br />
*Packages should not contain the following directories: <br />
**''/dev''<br />
**''/home''<br />
**''/media''<br />
**''/mnt''<br />
**''/proc''<br />
**''/root''<br />
**''/selinux''<br />
**''/sys''<br />
**''/tmp''<br />
**''/var/tmp''<br />
<br />
== Testing the PKGBUILD ==<br />
<br />
As you are writing the ''build()'' function, you will want to test your changes frequently to ensure there are no bugs. You can do this using the ''makepkg'' command in the directory containing the ''PKGBUILD'' file. With a properly formatted ''PKGBUILD'', this will create a package, but with a broken or unfinished one it will throw an error.<br />
If ''makepkg'' finishes successfully, it will place a file named ''pkgname-pkgver.pkg.tar.gz'' in your working directory. This is package that can be installed with the ''pacman -U'' command. However, just because a package file was built does not imply that it is fully functional. It might conceivably contain only the directory and no files whatsoever if, for example, a prefix was specified improperly. You can use ''pacman'''s query functions to display a list of files contained in the package and the dependencies it requires with ''pacman -Qlp [package file]'' and ''pacman -Qip [package file]'' respectively.<br />
If the package looks sane, then you are done! However, if you plan on release the ''PKGBUILD'' file, it is imperative that you check and double check the contents of the ''depends'' array. <br />
<br />
== {{Codeline|ldd}} and {{Codeline|namcap}} ==<br />
<br />
Dependencies are the most common packaging error. There are two excellent tools you can use to check dependencies. The first one is ''ldd'', which will show you the shared library dependencies of dynamic executables:<br />
$ ldd gcc<br />
linux-gate.so.1 => (0xb7f33000)<br />
libc.so.6 => /lib/libc.so.6 (0xb7de0000)<br />
/lib/ld-linux.so.2 (0xb7f34000)<br />
<br />
The other tool is ''namcap'' which not only checks for dependencies but the overall sanity of your package. It can be used on both the ''PKGBUILD'' file to check for things like missing tags or variables, and the ''pkg.tar.gz'' packages to verify dependencies or permissions. You can install ''namcap'' via ''pacman'':<br />
$ pacman -S namcap<br />
<br />
To check a PKGBUILD file with ''namcap'', simply supply a ''PKGBUILD'' file as the argument:<br />
$ namcap PKGBUILD<br />
Similarly, to check a package do:<br />
$ namcap pkgname.tar.gz<br />
<br />
Although ''namcap'' can help detect dependencies, it is not always correct. Verify dependencies by looking at the documentation of the software.<br />
<br />
=== Testing the package ===<br />
<br />
Also make sure that the package binaries actually ''run'' flawlessly! It's really annoying to release a package that contains all necessary files, but dumps core because of some obscure configuration option that doesn't quite work well with the rest of the system. If you're only going to compile packages for your own system, though, you don't need to worry too much about this quality assurance step, as you're the only person suffering from mistakes after all.<br />
<br />
== Submitting packages to the AUR ==<br />
<br />
Follow these steps to submit a package into the [[AUR]]:<br />
#Register a new account if you do not already have one.<br />
#Check all of the official repositories ({{Codeline|[core]}}, {{Codeline|[extra]}}, and {{Codeline|[community]}}) and see if the package already exists. If it is inside any of those repositories, '''DO NOT''' submit the package. If the package is broken, file a bug report.<br />
#Check the {{Codeline|[unsupported]}} repository for the package. If it is currently maintained, changes can be submitted in a comment for the maintainer's attention. If it is unmaintained, the package can be adopted and updated.<br />
#To upload the package to the AUR, the directory containing the {{Filename|PKGBUILD}} file and any other required files must be compressed as a tarball. The archive name should contain the name of the package, e.g. {{Filename|foo.tar.gz}}. You can easily build a tarball by using {{Codeline|makepkg --source}} in the directory. This makes a tarball named {{Filename|pkgname-pkver-pkrel.src.tar.gz}}, which you can then upload to the AUR. The tarball '''cannot''' contain the binary tarball created by {{Codeline|makepkg}} or the source tarball of the software. Packages that contain binaries or that are very poorly written will be deleted without warning.<br />
#Click the '''Submit''' link by the menu in the AUR. Choose the appropriate category for your package and upload.<br />
<br />
== Summary ==<br />
#Download the source tarball of the software you want to package.<br />
#Try compiling the package and installing it into an arbitrary directory.<br />
#Copy over the prototype {{Filename|/usr/share/pacman/PKGBUILD.proto}} and rename it to {{Filename|PKGBUILD}} in a temporary working directory -- preferably {{Filename|~/abs/}}.<br />
#Edit the {{Filename|PKGBUILD}} according to the needs of your package.<br />
#Run {{Codeline|makepkg}} and see whether the resulting package is built correctly.<br />
#If not, repeat the last two steps.<br />
<br />
=== Warnings ===<br />
* Before you can automate the package building process, you should have done it manually at least once unless you know ''exactly'' what you're doing ''in advance'', in which case you would not be reading this in the first place. Unfortunately, although a good bunch of program authors stick to the 3-step build cycle of "{{Codeline|./configure}}; {{Codeline|make}}; {{Codeline|make install}}", this is not always the case, and things can get real ugly if you have to apply patches to make everything work at all. Rule of thumb: If you can't get the program to compile from the source tarball, and make it install itself to a defined, temporary subdirectory, you don't even need to try packaging it. There isn't any magic pixie dust in {{Codeline|makepkg}} that makes source problems go away.<br />
* In a few cases, the packages are not even available as source and you have to use something like {{Codeline|sh installer.run}} to get it to work. You will have to do quite a bit of research (read READMEs, INSTALL instructions, man pages, perhaps ebuilds from Gentoo or other package installers, possibly even the MAKEFILEs or source code) to get it working. In some really bad cases, you have to edit the source files to get it to work at all. However, {{Codeline|makepkg}} needs to be completely autonomous, with no user input. Therefore if you need to edit the makefiles, you may have to bundle a custom patch with the {{Filename|PKGBUILD}} and install it from inside the {{Codeline|build()}} function, or you might have to issue some {{Codeline|sed}} commands from inside the {{Codeline|build()}} function.</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Talk:Creating_packages&diff=85666Talk:Creating packages2009-11-29T06:49:49Z<p>Bhobbit: re: duplication of effort</p>
<hr />
<div>Guys, if I'm going to see even more of this useless PKGBUILD variable reordering stuff, I'll go completely insane, submit my own standard of those to upstream (oh, that's right here! :) and put every wiki article on my watchlist containing the word "pkgname"... ''-.-''<br />
:--[[User:Byte|byte]]<br />
<br />
I think the title of this article is somewhat misleading: it discusses building packages from the abs tree, while using abs is not necessary to either build, install or remove packages. This fact mentioned in the article itself, but it doesn't make the title less confusing for those who are just starting to get familiarized with building packages in Arch.<br />
--[[User:Bhobbit|Bhobbit]] 23:30, 24 November 2009 (EST)<br />
:Update: This article has been merged with other similar articles; [[Building Packages in Arch Linux#Setting up]] was rearranged and, hopefully, the article is now clearer about ABS. On the other hand, I think the title could still be improved - 'in Arch Linux' portion of the title seems redundant.--[[User:Bhobbit|Bhobbit]] 00:54, 26 November 2009 (EST)<br />
::I agree to renaming the page; should be a simple matter to move to "Building Packages". -- [[User:Pointone|pointone]] 12:16, 27 November 2009 (EST)<br />
<br />
==Duplication==<br />
<br />
I would suggest the "Additional guidelines" section be erased in favour of a link to [[Arch Packaging Standards]].<br />
<br />
Also, I suggest the "Submitting packages to the AUR" section be erased in favour of a link to [[AUR User Guidelines#Submitting Packages to UNSUPPORTED]].<br />
<br />
The goal being to reduce duplication of effort. Thoughts?<br />
<br />
-- [[User:Pointone|pointone]] 12:16, 27 November 2009 (EST)<br />
:I agree on both counts. Besides, both sections are not essential reading for vanilla package building. [[Building Packages in Arch Linux#ldd and namcap | Section on namcap]] should also probably be merged with [[Namcap]] article and substituted with a link. --[[User:Bhobbit|Bhobbit]] 01:49, 29 November 2009 (EST)</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Creating_packages&diff=85275Creating packages2009-11-26T08:53:58Z<p>Bhobbit: Clarification of namcap usage</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:Package development (English)]]<br />
[[Category:Guidelines (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|A detailed HOWTO covering the entire package building process.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Building Packages in Arch Linux}}<br />
{{Article summary heading|Related articles}}<br />
{{Article summary wiki|ABS - The Arch Build System}}<br />
{{Article summary wiki|Arch Linux User-Community Repository (AUR)}}<br />
{{Article summary wiki|makepkg}}<br />
{{Article summary wiki|pacman}}<br />
{{Article summary wiki|PKGBUILD Tricks}}<br />
{{Article summary wiki|PKGBUILD Variables}}<br />
{{Article summary wiki|VCS PKGBUILD guidelines}}<br />
{{Article summary end}}<br />
<br />
All information for creating a package is placed in a {{Filename|PKGBUILD}} file. When you run {{Codeline|makepkg}}, it will look for a {{Filename|PKGBUILD}} file in the current working directory, and compile the software's source code according to the instructions in the {{Filename|PKGBUILD}} file. After successfully finishing the compilation, the resulting binaries, as well as all available meta-information like package version and dependencies, are packed in the {{Filename|name.pkg.tar.gz}} package file that can be cleanly installed with {{Codeline|pacman -U <package file>}}.<br />
<br />
== Setting up ==<br />
<br />
First, verify that you have the necessary tools installed. You need the following packages:<br />
*'''base-devel''' (a package group): Contains ''make'' and additional tools for compiling from the source.<br />
*'''fakeroot''' (part of 'base-devel'): Allows a normal user the necessary root permissions to create packages in the build environment without being able to alter the wider system. If the build process attempts to alter files outside of the build environment, errors are produced and the build fails. This is very useful for checking the quality, safety and integrity of the packages for distribution.<br />
<br />
If you do not have them, install them using ''pacman'':<br />
# pacman -S base-devel fakeroot<br />
<br />
One of the key tools for building packages is ''makepkg''. It does the following:<br />
#Checks if package dependencies are installed.<br />
#Downloads the source file(s) from the specified server(s).<br />
#Unpacks the source file(s).<br />
#Compiles the software and installs it under a fakeroot environment.<br />
#Strips symbols from binaries and libraries.<br />
#Generates the package meta file which is included with each package.<br />
#Compress the fakeroot environment into a package file.<br />
#Stores the package file in the configured destination directory, which is the present working directory by default.<br />
<br />
=== ABS ===<br />
<br />
If you want to rebuild binary packages from the official Arch Linux repositories, you should also install the [[Arch Build System]], ''abs'':<br />
# pacman -S abs<br />
<br />
The ''abs'' package will install all of the PKGBUILDs and local source files used to build the official packages. You do not need ''abs'' to use ''makepkg'' and if you only need a few PKGBUILDs, you can retrieve the latest versions from the web interface directly or via other available tools such as [http://xyne.archlinux.ca/info/pbget pbget]<br />
<br />
''abs'' also helps you keep all of your ''PKGBUILD'' files, both official and unofficial in a centralized location. You can specify which repositories to include in your ABS tree in the ''/etc/abs.conf'' file. To obtain the ABS tree which contains all of the ''PKGBUILD'' files, just run the ''abs'' command as root:<br />
# abs<br />
Create an ABS build directory under the /home of your non-root user, if you have not done so already: <br />
$ mkdir ~/abs<br />
<br />
== Package file ==<br />
<br />
An Arch package is, in fact, no more than a gzipped tar archive or 'tarball' which contains:<br />
<br />
* The files to install<br />
<br />
*.PKGINFO: contains all the metadata needed by pacman to deal with packages, dependencies, etc.<br />
<br />
*.FILELIST: lists all the files of the archive. It's used in order to uninstall the software or to check for file conflicts.<br />
{{ Note | .FILELIST file is now obsolete; it was used for pacman-2.x }}<br />
<br />
*.INSTALL: a file used to execute commands after the install/upgrade/remove stage. (This file is present only if specified in the PKGBUILD.)<br />
<br />
== Preparing the files ==<br />
<br />
Download the source tarball of the software you want to package, extract it, and note all commands needed to compile and install it. You will be repeating the same commands in the ''PKGBUILD'' file. Most software authors stick to the 3-step build cycle:<br />
./configure<br />
make<br />
make install<br />
When you run ''makepkg'', it will look for a ''PKGBUILD'' file in the present working directory. If a ''PKGBUILD'' file is found it will download the software's source code and compile it according to the instructions specified in the ''PKGBUILD'' file. The instructions must be fully interpretable by [[Wikipedia:Bash|Bash]]. After successful compilation, the resulting binaries and metadata of the package, i.e. package version and dependencies, are packed in a ''pkgname.pkg.tar.gz'' package file that can be cleanly installed with ''pacman -U [package file]''.<br />
To start out with a new package, you should first create an empty working directory, preferably named ''~/abs/'''pkgname'''''. Once you make the directory and change into it, create a ''PKGBUILD'' file to work with either by copying the prototype from ''/usr/share/pacman/PKGBUILD.proto'' or by copying a ''PKGBUILD'' from another package. The latter is quite useful if you want to modify compilation options of a package instead of creating an entirely new one.<br />
<br />
== Defining PKGBUILD variables ==<br />
<br />
The PKGBUILD file contains metadata about a package. It is a plain text file. The following is a prototype PKGBUILD. It can be found in /usr/share/pacman along with other templates.<br />
<br />
<pre><br />
# This is an example PKGBUILD file. Use this as a start to creating your own,<br />
# and remove these comments. For more information, see 'man PKGBUILD'.<br />
# Note: Please fill out the license field for your package. If it is unknown,<br />
# then please put 'unknown'.<br />
<br />
# Contributor: Your Name <youremail@domain.com><br />
pkgname=NAME<br />
pkgver=VERSION<br />
pkgrel=1<br />
pkgdesc=""<br />
arch=()<br />
url=""<br />
license=('GPL')<br />
groups=()<br />
depends=()<br />
makedepends=()<br />
provides=()<br />
conflicts=()<br />
replaces=()<br />
backup=()<br />
install=<br />
source=($pkgname-$pkgver.tar.gz)<br />
noextract=()<br />
md5sums=() #generate with 'makepkg -g'<br />
<br />
build() {<br />
cd "$srcdir/$pkgname-$pkgver"<br />
<br />
./configure --prefix=/usr<br />
make || return 1<br />
make DESTDIR="$pkgdir/" install<br />
}<br />
</pre><br />
<br />
A listing of possible PKGBUILD variables and their meaning can be found on [[PKGBUILD Variables]] page.<br />
<br />
== The build() function ==<br />
<br />
Now you need to implement the ''build()'' function in the ''PKGBUILD'' file. This function uses common shell commands in the [http://en.wikipedia.org/wiki/Bash Bash] syntax to automatically compile software and create a ''pkg/'' directory to install the software to. This allows ''makepkg'' to pack it up without having to pick all the necessary files from your actual filesystem.<br />
The first step in the ''build()'' function is to change into the directory created by uncompressing the source tarball. In most common cases the first command will look like this:<br />
cd $srcdir/$pkgname-$pkgver<br />
<br />
Now, you need to list the same commands you used when you manually compiled the software. The ''build()'' function in essence automates everything you did by hand and compiles the software in the fakeroot build environment. If the software you are packaging uses a configure script, it is good practice to use ''--prefix=/usr'' when building packages for ''pacman''. A lot of software install their files relative to the ''/usr/local'' directory, which should only be done if you are manually building from source. All Arch Linux packages should use the ''/usr'' directory. As seen in the ''/usr/share/pacman/PKGBUILD.proto'' file, the next two lines should look like this:<br />
./configure --prefix=/usr<br />
make || return 1<br />
<br />
The final step in the ''build()'' funciton is to put the compiled files in a directory where ''makepkg'' can retrieve to create a package. This by default is the ''pkg/'' directory - a simple fakeroot environment. It imitates the root of your filesystem to the software's installation procedure. If you have to manually install files under the root of your filesystem, you should instead install it in the ''pkg/'' directory under the same directory structure, e.g. if you want to install a file to ''/usr/bin'', it should instead be placed under ''$pkgdir/usr/bin''. Very few software require the user to copy dozens of files manually, and you usually will not have to worry about this. Instead, for most software you will have to call ''make install''. The final line should look like the following in order to correctly install the software in the ''pkg/'' directory:<br />
make DESTDIR=$pkgdir install || return 1<br />
<br />
'''Note''': It is sometimes the case where <code>DESTDIR</code> is not used in the <code>Makefile</code>; you may need to use <code>prefix</code> instead. If the package is built with autoconf/automake, use <code>DESTDIR</code>; this is what is [http://sources.redhat.com/automake/automake.html#Install documented] in the manuals. If <code>DESTDIR</code> does not work, try building with <code>make prefix="$pkgdir/usr/" install</code>. If that does not work, you'll have to look further into the install commands that are executed by "<code>make <...> install</code>".<br />
<br />
In some odd cases, the software expects to be run from a single directory. In such cases it is wise to simply copy these to ''$pkgdir/opt''.<br />
More often than not the installation process of the software will create any subdirectories below the ''pkg/'' directory. If it does not, however, ''makepkg'' will generate a lot of errors and you will need to manually create subdirectories by adding the appropriate ''mkdir -p'' commands in the ''build()'' function before the installation procedure is run.<br />
Also, ''makepkg'' defines three variables that you should use as part of the build and install process:<br />
*'''''startdir''''' - This contains the absolute path to the directory where the ''PKGBUILD'' file is located, which is the present working directory. This variable is almost always used in combination with ''/src'' or ''/pkg'' postfixes, but the use of ''srcdir'' and ''pkgdir'' variables is preferred.<br />
*'''''srcdir''''' - This points to the directory where ''makepkg'' extracts or copies all source files. It is currently an alias for ''$startdir/src''.<br />
*'''''pkgdir''''' - This points to the directory where ''makepkg'' bundles the installed package, which becomes the root directory of your built package. It is currently an alias for ''$startdir/pkg''.<br />
<br />
'''Note:''' makepkg, and thus the build() function, is intended to be non-interactive. Interactive utilities or scripts called in the build() function may break makepkg, particularly if it is invoked with build-logging enabled (-l). (see [http://bugs.archlinux.org/task/13214 Arch Linux Bug #13214].)<br />
<br />
== Additional guidelines ==<br />
<br />
Here are some additional guidelines that you should adhere to:<br />
*All elements in an array variable '''must be separated by spaces'''.<br />
*If possible, remove empty lines from the ''PKGBUILD'' including fields that have empty values.<br />
*Wherever possible, use ''|| return 1'' for critical build functions: make || return 1 make DESTDIR=$pkgdir install || return 1 <br />
*'''Do not introduce new variables''' into your ''PKGBUILD'' file unless the package cannot be built without doing so, as these could possibly conflict with variables used in ''makepkg'' itself. If a new variable is absolutely required, '''prefix the variable name with an underscore''': _customvariable= <br />
*'''Avoid''' using ''/usr/libexec/'' for anything. Use ''/usr/lib/pkgname'' instead.<br />
*The ''packager'' field from the package meta file can be customized by the package builder by modifying the appropriate option in the ''/etc/makepkg.conf'' file, or alternatively by exporting the ''PACKAGER'' environment variable before building packages with ''makepkg'': # export PACKAGER="Your Name &lt;email@domain.com&gt;" <br />
* '''Configuration files''' should be placed in the ''/etc'' directory. If there is more than one configuration file, it is customary to use a subdirectory in order to keep the ''/etc'' area as clean as possible. Use ''/etc/'''pkgname''''' or a suitable alternative, e.g., [http://httpd.apache.org/ Apache] uses ''/etc/httpd/''. <br />
*Package files should follow these '''general directory guidelines''': <br />
**''/etc/'' - System essential configuration files<br />
**''/usr/bin'' - Application binaries<br />
**''/usr/sbin'' - System binaries<br />
**''/usr/lib'' - Libraries<br />
**''/usr/include'' - Header files<br />
**''/usr/lib/pkgname'' - Modules, plugins, etc.<br />
**''/usr/share/man'' - Manpages<br />
**''/usr/share/pkgname'' - Application data<br />
**''/usr/share/licenses/pkgname'' - Package license, if not included under common<br />
**''/etc/pkgname'' - Configuration files<br />
**''/opt'' - Large self-contained packages such as Java, etc.<br />
<br />
*Packages should not contain the following directories: <br />
**''/dev''<br />
**''/home''<br />
**''/media''<br />
**''/mnt''<br />
**''/proc''<br />
**''/root''<br />
**''/selinux''<br />
**''/sys''<br />
**''/tmp''<br />
**''/var/tmp''<br />
<br />
== Testing the PKGBUILD ==<br />
<br />
As you are writing the ''build()'' function, you will want to test your changes frequently to ensure there are no bugs. You can do this using the ''makepkg'' command in the directory containing the ''PKGBUILD'' file. With a properly formatted ''PKGBUILD'', this will create a package, but with a broken or unfinished one it will throw an error.<br />
If ''makepkg'' finishes successfully, it will place a file named ''pkgname-pkgver.pkg.tar.gz'' in your working directory. This is package that can be installed with the ''pacman -U'' command. However, just because a package file was built does not imply that it is fully functional. It might conceivably contain only the directory and no files whatsoever if, for example, a prefix was specified improperly. You can use ''pacman'''s query functions to display a list of files contained in the package and the dependencies it requires with ''pacman -Qlp [package file]'' and ''pacman -Qip [package file]'' respectively.<br />
If the package looks sane, then you are done! However, if you plan on release the ''PKGBUILD'' file, it is imperative that you check and double check the contents of the ''depends'' array. <br />
<br />
== {{Codeline|ldd}} and {{Codeline|namcap}} ==<br />
<br />
Dependencies are the most common packaging error. There are two excellent tools you can use to check dependencies. The first one is ''ldd'', which will show you the shared library dependencies of dynamic executables:<br />
$ ldd gcc<br />
linux-gate.so.1 => (0xb7f33000)<br />
libc.so.6 => /lib/libc.so.6 (0xb7de0000)<br />
/lib/ld-linux.so.2 (0xb7f34000)<br />
<br />
The other tool is ''namcap'' which not only checks for dependencies but the overall sanity of your package. It can be used on both the ''PKGBUILD'' file to check for things like missing tags or variables, and the ''pkg.tar.gz'' packages to verify dependencies or permissions. You can install ''namcap'' via ''pacman'':<br />
$ pacman -S namcap<br />
<br />
To check a PKGBUILD file with ''namcap'', simply supply a ''PKGBUILD'' file as the argument:<br />
$ namcap PKGBUILD<br />
Similarly, to check a package do:<br />
$ namcap pkgname.tar.gz<br />
<br />
Although ''namcap'' can help detect dependencies, it is not always correct. Verify dependencies by looking at the documentation of the software.<br />
<br />
=== Testing the package ===<br />
<br />
Also make sure that the package binaries actually ''run'' flawlessly! It's really annoying to release a package that contains all necessary files, but dumps core because of some obscure configuration option that doesn't quite work well with the rest of the system. If you're only going to compile packages for your own system, though, you don't need to worry too much about this quality assurance step, as you're the only person suffering from mistakes after all.<br />
<br />
== Submitting packages to the AUR ==<br />
<br />
Follow these steps to submit a package into the AUR:<br />
#Register a new account if you do not already have one.<br />
#Check all of the official repositories (''[core]'', ''[extra]'', and ''[community]'') and see if the package already exists. If it is inside any of those repositories, '''DO NOT''' submit the package. If the package is broken, file a bug report.<br />
#Check the ''[unsupported]'' repository for the package. If it is currently maintained, changes can be submitted in a comment for the maintaner's attention. If it is unmaintained, the package can be adopted and updated.<br />
#To upload the package to the AUR, the directory containing the ''PKGBUILD'' file and any other required files must be compressed as a tarball. The archive name should contain the name of the package, e.g. ''foo.tar.gz.''. You can easily build a tarball by using ''makepkg --source'' in the directory. This makes a tarball named ''pkgname-pkver-pkrel.src.tar.gz'', which you can then upload to the AUR. The tarball '''cannot''' contain the binary tarball created by ''makepkg'' or the source tarball of the software. Packages that contain binaries or that are very poorly written will be deleted without warning.<br />
#Click the '''Submit''' link by the menu in the AUR. Choose the appropriate category for your package and upload.<br />
<br />
== Summary ==<br />
#Download the source tarball of the software you want to package.<br />
#Try compiling the package and installing it into an arbitrary directory.<br />
#Copy over the prototype ''/usr/share/pacman/PKGBUILD.proto'' and rename it to ''PKGBUILD'' in a temporary working directory - preferably ''~/abs/''.<br />
#Edit the ''PKGBUILD'' according to the needs of your package.<br />
#Run ''makepkg'' and see whether the resulting package is built correctly.<br />
#If not, repeat the last two steps.<br />
<br />
=== Warnings ===<br />
* Before you can automate the package building process, you should have done it manually at least once unless you know ''exactly'' what you're doing ''in advance'', in which case you would not be reading this in the first place. Unfortunately, although a good bunch of program authors stick to the 3-step build cycle of "./configure; make; make install", this is not always the case, and things can get real ugly if you have to apply patches to make everything work at all. Rule of thumb: If you can't get the program to compile from the source tarball, and make it install itself to a defined, temporary subdirectory, you don't even need to try packaging it. There isn't any magic pixie dust in <code>makepkg</code> that makes source problems go away.<br />
* In a few cases, the packages are not even available as source and you have to use something like <code>sh installer.run</code> to get it to work. You will have to do quite a bit of research (read READMEs, INSTALL instructions, man pages, perhaps ebuilds from gentoo or other package installers, possibly even the MAKEFILEs or source code) to get it working. In some really bad cases, you have to edit the source files to get it to work at all. However, <code>makepkg</code> needs to be completely autonomous, with no user input. Therefore if you need to edit the Makefiles, you may have to bundle a custom patch with the <code>PKGBUILD</code> and install it from inside the <code>build()</code> function, or you might have to issue some <code>sed</code> commands from inside the <code>build()</code> function.</div>Bhobbithttps://wiki.archlinux.org/index.php?title=User_talk:Pointone&diff=85258User talk:Pointone2009-11-26T05:57:05Z<p>Bhobbit: </p>
<hr />
<div>Hi and thanks for the good work wrt templates.<br />
I wanted first to get the green/red light for my idea and then proceed w/ adding the templates to the articles that beg for them. Many wiki pages are just a wall of grey text.<br />
<br />
[[User:Karol|Karol]] 17:05, 31 May 2009 (EDT)<br />
<br />
----<br />
<br />
Thanks for fixing Compact TOC! I don't know much about templates/markup. [[User:Manolo|manolo]] 18:49, 10 November 2009 (EST)<br />
<br />
----<br />
<br />
Kudos for cleaning up package-building articles! --[[User:Bhobbit|Bhobbit]] 00:57, 26 November 2009 (EST)</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Talk:Creating_packages&diff=85255Talk:Creating packages2009-11-26T05:54:54Z<p>Bhobbit: </p>
<hr />
<div>Guys, if I'm going to see even more of this useless PKGBUILD variable reordering stuff, I'll go completely insane, submit my own standard of those to upstream (oh, that's right here! :) and put every wiki article on my watchlist containing the word "pkgname"... ''-.-''<br />
:--[[User:Byte|byte]]<br />
<br />
I think the title of this article is somewhat misleading: it discusses building packages from the abs tree, while using abs is not necessary to either build, install or remove packages. This fact mentioned in the article itself, but it doesn't make the title less confusing for those who are just starting to get familiarized with building packages in Arch.<br />
--[[User:Bhobbit|Bhobbit]] 23:30, 24 November 2009 (EST)<br />
:Update: This article has been merged with other similar articles; [[Building Packages in Arch Linux#Setting up]] was rearranged and, hopefully, the article is now clearer about ABS. On the other hand, I think the title could still be improved - 'in Arch Linux' portion of the title seems redundant.--[[User:Bhobbit|Bhobbit]] 00:54, 26 November 2009 (EST)</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Creating_packages&diff=85241Creating packages2009-11-26T05:50:18Z<p>Bhobbit: Rearranged Setting Up section to emphasize that using ABS is optional</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:Package development (English)]]<br />
[[Category:Guidelines (English)]]<br />
{{Article summary start}}<br />
{{Article summary text|A detailed HOWTO covering the entire package building process.}}<br />
{{Article summary heading|Available in languages}}<br />
{{i18n entry|English|Building Packages in Arch Linux}}<br />
{{Article summary heading|Related articles}}<br />
{{Article summary wiki|ABS - The Arch Build System}}<br />
{{Article summary wiki|Arch Linux User-Community Repository (AUR)}}<br />
{{Article summary wiki|makepkg}}<br />
{{Article summary wiki|pacman}}<br />
{{Article summary wiki|PKGBUILD Tricks}}<br />
{{Article summary wiki|PKGBUILD Variables}}<br />
{{Article summary wiki|VCS PKGBUILD guidelines}}<br />
{{Article summary end}}<br />
<br />
All information for creating a package is placed in a {{Filename|PKGBUILD}} file. When you run {{Codeline|makepkg}}, it will look for a {{Filename|PKGBUILD}} file in the current working directory, and compile the software's source code according to the instructions in the {{Filename|PKGBUILD}} file. After successfully finishing the compilation, the resulting binaries, as well as all available meta-information like package version and dependencies, are packed in the {{Filename|name.pkg.tar.gz}} package file that can be cleanly installed with {{Codeline|pacman -U <package file>}}.<br />
<br />
== Setting up ==<br />
<br />
First, verify that you have the necessary tools installed. You need the following packages:<br />
*'''base-devel''' (a package group): Contains ''make'' and additional tools for compiling from the source.<br />
*'''fakeroot''' (part of 'base-devel'): Allows a normal user the necessary root permissions to create packages in the build environment without being able to alter the wider system. If the build process attempts to alter files outside of the build environment, errors are produced and the build fails. This is very useful for checking the quality, safety and integrity of the packages for distribution.<br />
<br />
If you do not have them, install them using ''pacman'':<br />
# pacman -S base-devel fakeroot<br />
<br />
One of the key tools for building packages is ''makepkg''. It does the following:<br />
#Checks if package dependencies are installed.<br />
#Downloads the source file(s) from the specified server(s).<br />
#Unpacks the source file(s).<br />
#Compiles the software and installs it under a fakeroot environment.<br />
#Strips symbols from binaries and libraries.<br />
#Generates the package meta file which is included with each package.<br />
#Compress the fakeroot environment into a package file.<br />
#Stores the package file in the configured destination directory, which is the present working directory by default.<br />
<br />
=== ABS ===<br />
<br />
If you want to rebuild binary packages from the official Arch Linux repositories, you should also install the [[Arch Build System]], ''abs'':<br />
# pacman -S abs<br />
<br />
The ''abs'' package will install all of the PKGBUILDs and local source files used to build the official packages. You do not need ''abs'' to use ''makepkg'' and if you only need a few PKGBUILDs, you can retrieve the latest versions from the web interface directly or via other available tools such as [http://xyne.archlinux.ca/info/pbget pbget]<br />
<br />
''abs'' also helps you keep all of your ''PKGBUILD'' files, both official and unofficial in a centralized location. You can specify which repositories to include in your ABS tree in the ''/etc/abs.conf'' file. To obtain the ABS tree which contains all of the ''PKGBUILD'' files, just run the ''abs'' command as root:<br />
# abs<br />
Create an ABS build directory under the /home of your non-root user, if you have not done so already: <br />
$ mkdir ~/abs<br />
<br />
== Package file ==<br />
<br />
An Arch package is, in fact, no more than a gzipped tar archive or 'tarball' which contains:<br />
<br />
* The files to install<br />
<br />
*.PKGINFO: contains all the metadata needed by pacman to deal with packages, dependencies, etc.<br />
<br />
*.FILELIST: lists all the files of the archive. It's used in order to uninstall the software or to check for file conflicts.<br />
{{ Note | .FILELIST file is now obsolete; it was used for pacman-2.x }}<br />
<br />
*.INSTALL: a file used to execute commands after the install/upgrade/remove stage. (This file is present only if specified in the PKGBUILD.)<br />
<br />
== Preparing the files ==<br />
<br />
Download the source tarball of the software you want to package, extract it, and note all commands needed to compile and install it. You will be repeating the same commands in the ''PKGBUILD'' file. Most software authors stick to the 3-step build cycle:<br />
./configure<br />
make<br />
make install<br />
When you run ''makepkg'', it will look for a ''PKGBUILD'' file in the present working directory. If a ''PKGBUILD'' file is found it will download the software's source code and compile it according to the instructions specified in the ''PKGBUILD'' file. The instructions must be fully interpretable by [[Wikipedia:Bash|Bash]]. After successful compilation, the resulting binaries and metadata of the package, i.e. package version and dependencies, are packed in a ''pkgname.pkg.tar.gz'' package file that can be cleanly installed with ''pacman -U [package file]''.<br />
To start out with a new package, you should first create an empty working directory, preferably named ''~/abs/'''pkgname'''''. Once you make the directory and change into it, create a ''PKGBUILD'' file to work with either by copying the prototype from ''/usr/share/pacman/PKGBUILD.proto'' or by copying a ''PKGBUILD'' from another package. The latter is quite useful if you want to modify compilation options of a package instead of creating an entirely new one.<br />
<br />
== Defining PKGBUILD variables ==<br />
<br />
The PKGBUILD file contains metadata about a package. It is a plain text file. The following is a prototype PKGBUILD. It can be found in /usr/share/pacman along with other templates.<br />
<br />
<pre><br />
# This is an example PKGBUILD file. Use this as a start to creating your own,<br />
# and remove these comments. For more information, see 'man PKGBUILD'.<br />
# Note: Please fill out the license field for your package. If it is unknown,<br />
# then please put 'unknown'.<br />
<br />
# Contributor: Your Name <youremail@domain.com><br />
pkgname=NAME<br />
pkgver=VERSION<br />
pkgrel=1<br />
pkgdesc=""<br />
arch=()<br />
url=""<br />
license=('GPL')<br />
groups=()<br />
depends=()<br />
makedepends=()<br />
provides=()<br />
conflicts=()<br />
replaces=()<br />
backup=()<br />
install=<br />
source=($pkgname-$pkgver.tar.gz)<br />
noextract=()<br />
md5sums=() #generate with 'makepkg -g'<br />
<br />
build() {<br />
cd "$srcdir/$pkgname-$pkgver"<br />
<br />
./configure --prefix=/usr<br />
make || return 1<br />
make DESTDIR="$pkgdir/" install<br />
}<br />
</pre><br />
<br />
A listing of possible PKGBUILD variables and their meaning can be found on [[PKGBUILD Variables]] page.<br />
<br />
== The build() function ==<br />
<br />
Now you need to implement the ''build()'' function in the ''PKGBUILD'' file. This function uses common shell commands in the [http://en.wikipedia.org/wiki/Bash Bash] syntax to automatically compile software and create a ''pkg/'' directory to install the software to. This allows ''makepkg'' to pack it up without having to pick all the necessary files from your actual filesystem.<br />
The first step in the ''build()'' function is to change into the directory created by uncompressing the source tarball. In most common cases the first command will look like this:<br />
cd $srcdir/$pkgname-$pkgver<br />
<br />
Now, you need to list the same commands you used when you manually compiled the software. The ''build()'' function in essence automates everything you did by hand and compiles the software in the fakeroot build environment. If the software you are packaging uses a configure script, it is good practice to use ''--prefix=/usr'' when building packages for ''pacman''. A lot of software install their files relative to the ''/usr/local'' directory, which should only be done if you are manually building from source. All Arch Linux packages should use the ''/usr'' directory. As seen in the ''/usr/share/pacman/PKGBUILD.proto'' file, the next two lines should look like this:<br />
./configure --prefix=/usr<br />
make || return 1<br />
<br />
The final step in the ''build()'' funciton is to put the compiled files in a directory where ''makepkg'' can retrieve to create a package. This by default is the ''pkg/'' directory - a simple fakeroot environment. It imitates the root of your filesystem to the software's installation procedure. If you have to manually install files under the root of your filesystem, you should instead install it in the ''pkg/'' directory under the same directory structure, e.g. if you want to install a file to ''/usr/bin'', it should instead be placed under ''$pkgdir/usr/bin''. Very few software require the user to copy dozens of files manually, and you usually will not have to worry about this. Instead, for most software you will have to call ''make install''. The final line should look like the following in order to correctly install the software in the ''pkg/'' directory:<br />
make DESTDIR=$pkgdir install || return 1<br />
<br />
'''Note''': It is sometimes the case where <code>DESTDIR</code> is not used in the <code>Makefile</code>; you may need to use <code>prefix</code> instead. If the package is built with autoconf/automake, use <code>DESTDIR</code>; this is what is [http://sources.redhat.com/automake/automake.html#Install documented] in the manuals. If <code>DESTDIR</code> does not work, try building with <code>make prefix="$pkgdir/usr/" install</code>. If that does not work, you'll have to look further into the install commands that are executed by "<code>make <...> install</code>".<br />
<br />
In some odd cases, the software expects to be run from a single directory. In such cases it is wise to simply copy these to ''$pkgdir/opt''.<br />
More often than not the installation process of the software will create any subdirectories below the ''pkg/'' directory. If it does not, however, ''makepkg'' will generate a lot of errors and you will need to manually create subdirectories by adding the appropriate ''mkdir -p'' commands in the ''build()'' function before the installation procedure is run.<br />
Also, ''makepkg'' defines three variables that you should use as part of the build and install process:<br />
*'''''startdir''''' - This contains the absolute path to the directory where the ''PKGBUILD'' file is located, which is the present working directory. This variable is almost always used in combination with ''/src'' or ''/pkg'' postfixes, but the use of ''srcdir'' and ''pkgdir'' variables is preferred.<br />
*'''''srcdir''''' - This points to the directory where ''makepkg'' extracts or copies all source files. It is currently an alias for ''$startdir/src''.<br />
*'''''pkgdir''''' - This points to the directory where ''makepkg'' bundles the installed package, which becomes the root directory of your built package. It is currently an alias for ''$startdir/pkg''.<br />
<br />
'''Note:''' makepkg, and thus the build() function, is intended to be non-interactive. Interactive utilities or scripts called in the build() function may break makepkg, particularly if it is invoked with build-logging enabled (-l). (see [http://bugs.archlinux.org/task/13214 Arch Linux Bug #13214].)<br />
<br />
== Additional guidelines ==<br />
<br />
Here are some additional guidelines that you should adhere to:<br />
*All elements in an array variable '''must be separated by spaces'''.<br />
*If possible, remove empty lines from the ''PKGBUILD'' including fields that have empty values.<br />
*Wherever possible, use ''|| return 1'' for critical build functions: make || return 1 make DESTDIR=$pkgdir install || return 1 <br />
*'''Do not introduce new variables''' into your ''PKGBUILD'' file unless the package cannot be built without doing so, as these could possibly conflict with variables used in ''makepkg'' itself. If a new variable is absolutely required, '''prefix the variable name with an underscore''': _customvariable= <br />
*'''Avoid''' using ''/usr/libexec/'' for anything. Use ''/usr/lib/pkgname'' instead.<br />
*The ''packager'' field from the package meta file can be customized by the package builder by modifying the appropriate option in the ''/etc/makepkg.conf'' file, or alternatively by exporting the ''PACKAGER'' environment variable before building packages with ''makepkg'': # export PACKAGER="Your Name &lt;email@domain.com&gt;" <br />
* '''Configuration files''' should be placed in the ''/etc'' directory. If there is more than one configuration file, it is customary to use a subdirectory in order to keep the ''/etc'' area as clean as possible. Use ''/etc/'''pkgname''''' or a suitable alternative, e.g., [http://httpd.apache.org/ Apache] uses ''/etc/httpd/''. <br />
*Package files should follow these '''general directory guidelines''': <br />
**''/etc/'' - System essential configuration files<br />
**''/usr/bin'' - Application binaries<br />
**''/usr/sbin'' - System binaries<br />
**''/usr/lib'' - Libraries<br />
**''/usr/include'' - Header files<br />
**''/usr/lib/pkgname'' - Modules, plugins, etc.<br />
**''/usr/share/man'' - Manpages<br />
**''/usr/share/pkgname'' - Application data<br />
**''/usr/share/licenses/pkgname'' - Package license, if not included under common<br />
**''/etc/pkgname'' - Configuration files<br />
**''/opt'' - Large self-contained packages such as Java, etc.<br />
<br />
*Packages should not contain the following directories: <br />
**''/dev''<br />
**''/home''<br />
**''/media''<br />
**''/mnt''<br />
**''/proc''<br />
**''/root''<br />
**''/selinux''<br />
**''/sys''<br />
**''/tmp''<br />
**''/var/tmp''<br />
<br />
== Testing the PKGBUILD ==<br />
<br />
As you are writing the ''build()'' function, you will want to test your changes frequently to ensure there are no bugs. You can do this using the ''makepkg'' command in the directory containing the ''PKGBUILD'' file. With a properly formatted ''PKGBUILD'', this will create a package, but with a broken or unfinished one it will throw an error.<br />
If ''makepkg'' finishes successfully, it will place a file named ''pkgname-pkgver.pkg.tar.gz'' in your working directory. This is package that can be installed with the ''pacman -U'' command. However, just because a package file was built does not imply that it is fully functional. It might conceivably contain only the directory and no files whatsoever if, for example, a prefix was specified improperly. You can use ''pacman'''s query functions to display a list of files contained in the package and the dependencies it requires with ''pacman -Qlp [package file]'' and ''pacman -Qip [package file]'' respectively.<br />
If the package looks sane, then you are done! However, if you plan on release the ''PKGBUILD'' file, it is imperative that you check and double check the contents of the ''depends'' array. <br />
<br />
== {{Codeline|ldd}} and {{Codeline|namcap}} ==<br />
<br />
Dependencies are the most common packaging error. There are two excellent tools you can use to check dependencies. The first one is ''ldd'', which will show you the shared library dependencies of dynamic executables:<br />
$ ldd gcc<br />
linux-gate.so.1 => (0xb7f33000)<br />
libc.so.6 => /lib/libc.so.6 (0xb7de0000)<br />
/lib/ld-linux.so.2 (0xb7f34000)<br />
<br />
The other tool is ''namcap'' which not only checks for dependencies but the overall sanity of your package. It can be used on both the ''PKGBUILD'' file and the ''pkg.tar.gz'' package. It will report any bad permissions, missing dependencies, unnecessary dependencies and other common mistakes. You can install ''namcap'' via ''pacman'':<br />
$ pacman -S namcap<br />
<br />
To use ''namcap'', simply supply a ''PKGBUILD'' file or a ''pkg.tar.gz'' package as the argument:<br />
$ namcap PKGBUILD<br />
or $ namcap pkgname.tar.gz<br />
<br />
Although ''namcap'' can help detect dependencies, it is not always correct. Verify dependencies by looking at the documentation of the software.<br />
<br />
=== Testing the package ===<br />
<br />
Also make sure that the package binaries actually ''run'' flawlessly! It's really annoying to release a package that contains all necessary files, but dumps core because of some obscure configuration option that doesn't quite work well with the rest of the system. If you're only going to compile packages for your own system, though, you don't need to worry too much about this quality assurance step, as you're the only person suffering from mistakes after all.<br />
<br />
== Submitting packages to the AUR ==<br />
<br />
Follow these steps to submit a package into the AUR:<br />
#Register a new account if you do not already have one.<br />
#Check all of the official repositories (''[core]'', ''[extra]'', and ''[community]'') and see if the package already exists. If it is inside any of those repositories, '''DO NOT''' submit the package. If the package is broken, file a bug report.<br />
#Check the ''[unsupported]'' repository for the package. If it is currently maintained, changes can be submitted in a comment for the maintaner's attention. If it is unmaintained, the package can be adopted and updated.<br />
#To upload the package to the AUR, the directory containing the ''PKGBUILD'' file and any other required files must be compressed as a tarball. The archive name should contain the name of the package, e.g. ''foo.tar.gz.''. You can easily build a tarball by using ''makepkg --source'' in the directory. This makes a tarball named ''pkgname-pkver-pkrel.src.tar.gz'', which you can then upload to the AUR. The tarball '''cannot''' contain the binary tarball created by ''makepkg'' or the source tarball of the software. Packages that contain binaries or that are very poorly written will be deleted without warning.<br />
#Click the '''Submit''' link by the menu in the AUR. Choose the appropriate category for your package and upload.<br />
<br />
== Summary ==<br />
#Download the source tarball of the software you want to package.<br />
#Try compiling the package and installing it into an arbitrary directory.<br />
#Copy over the prototype ''/usr/share/pacman/PKGBUILD.proto'' and rename it to ''PKGBUILD'' in a temporary working directory - preferably ''~/abs/''.<br />
#Edit the ''PKGBUILD'' according to the needs of your package.<br />
#Run ''makepkg'' and see whether the resulting package is built correctly.<br />
#If not, repeat the last two steps.<br />
<br />
=== Warnings ===<br />
* Before you can automate the package building process, you should have done it manually at least once unless you know ''exactly'' what you're doing ''in advance'', in which case you would not be reading this in the first place. Unfortunately, although a good bunch of program authors stick to the 3-step build cycle of "./configure; make; make install", this is not always the case, and things can get real ugly if you have to apply patches to make everything work at all. Rule of thumb: If you can't get the program to compile from the source tarball, and make it install itself to a defined, temporary subdirectory, you don't even need to try packaging it. There isn't any magic pixie dust in <code>makepkg</code> that makes source problems go away.<br />
* In a few cases, the packages are not even available as source and you have to use something like <code>sh installer.run</code> to get it to work. You will have to do quite a bit of research (read READMEs, INSTALL instructions, man pages, perhaps ebuilds from gentoo or other package installers, possibly even the MAKEFILEs or source code) to get it working. In some really bad cases, you have to edit the source files to get it to work at all. However, <code>makepkg</code> needs to be completely autonomous, with no user input. Therefore if you need to edit the Makefiles, you may have to bundle a custom patch with the <code>PKGBUILD</code> and install it from inside the <code>build()</code> function, or you might have to issue some <code>sed</code> commands from inside the <code>build()</code> function.</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Makepkg&diff=85186Makepkg2009-11-26T01:00:24Z<p>Bhobbit: /* Useful Links */</p>
<hr />
<div>[[Category:Package development (English)]]<br />
[[Category:About Arch (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{i18n_links_start}}<br />
{{i18n_entry|English|Makepkg}}<br />
{{i18n_entry|Italiano|Makepkg (Italiano)}}<br />
{{i18n_entry|Ελληνικά|Makepkg_(Ελληνικά)}}<br />
{{i18n_entry|简体中文|Makepkg_(简体中文)}}<br />
{{i18n_entry|Русский|Makepkg (Русский)}}<br />
{{i18n_entry|Türkçe|Makepkg (Türkçe)}}<br />
{{i18n_entry|Nederlands|Makepkg (Nederlands)}}<br />
{{i18n_links_end}}<br />
<br />
<code>makepkg</code> is used for compiling your own packages suitable for [[Pacman]] to use. It uses a script-based build system which can download and validate source files, check dependencies, configure build time settings, compile the sources, install into a temporary root, make customizations, generate meta-info and package the whole thing up.<br />
<br />
== Setting Things Up ==<br />
<br />
=== Makepkg ===<br />
<br />
If you want to be able to install dependencies with makepkg as user (with makepkg -s, see below) you need to install [[sudo]] and add yourself to /etc/sudoers:<br />
<br />
USER_NAME ALL=(ALL) NOPASSWD: /usr/bin/pacman<br />
<br />
The above will negate the need to enter a password with pacman. See the [[Sudo]] wiki for detailed information.<br />
<br />
Next you need to decide where you want your finished packages to be placed, for instance you could have them under your home directory under a separate folder. You can also skip this step, and your packages will be created in the same directory where you've started makepkg.<br />
<br />
Create the directory:<br />
<br />
mkdir /home/$USER/packages<br />
<br />
Then modify the PKGDEST variable in /etc/makepkg.conf accordingly.<br />
<br />
While you're at it, you could also have a look at the other values in makepkg.conf. For example, you could edit PACKAGER, or remove the ! from docs in the default OPTIONS array, in case you don't want the /usr/share/doc/<package> directory to be deleted by makepkg. See [[Makepkg.conf]] for more.<br />
<br />
== Building a Package ==<br />
<br />
Before you continue, make sure you have the base-devel group installed. Packages belonging to this group are not required to be listed as dependencies in <code>PKGBUILD</code> files. You can install the base-devel group by issuing (as root):<br />
<br />
pacman -Sy base-devel<br />
<br />
{{Warning | Remember this before complaining about missing (make)dependencies. The "base" group is assumed already installed in all Arch setups . The group "base-devel" is assumed already installed when building with makepkg .}}<br />
<br />
To build a package you either need to create one as described at [[Building_Packages_in_Arch_Linux|"Building Packages in Arch Linux"]], or obtain one from [http://aur.archlinux.org AUR] or [[ABS]] (see above) or some other source. You should be careful where you obtain your packages from and only install those from people and sources you trust.<br />
<br />
Say you found an excellent package on AUR that you wanted to build and install (in this example we will use "rufus", a Python based bit torrent client). You can obtain the <code>PKGBUILD</code> and all files needed from [http://aur.archlinux.org/packages.php?do_Details=1&ID=3394 its AUR page], click on the "Tarball" link.<br />
<br />
cd /path/to/file<br />
tar -zxf rufus.tar.gz<br />
cd rufus<br />
<br />
You will notice there are a number of files located under this directory, including the <code>PKGBUILD</code> script that is used to build your package. To build this package just issue (as your normal user):<br />
<br />
makepkg<br />
<br />
which will then set up, download and attempt to build your package. If you don't have all the required dependencies installed, <code>makepkg</code> will warn you before failing. To build your package and install these dependencies, simply use the command:<br />
<br />
makepkg -s<br />
<br />
Note that these dependences will need to be in your configured repositories. Alternatively, you can manually download the packages first using <code>pacman -Sy dep1 dep2 etc</code>.<br />
<br />
Once you have satisfied all the dependencies and your package builds successfully you should now have the rufus-0.7.0-1.pkg.tar.gz file in the directory you run <code>makepkg</code> in. To install it (as the root user) issue:<br />
<br />
pacman -U rufus-0.7.0-1.pkg.tar.gz<br />
<br />
=== [[ABS - The Arch Build System]] ===<br />
Note that you do '''not''' need abs installed to use makepkg. Makepkg comes with pacman and is used to build packages from PKGBUILDs. The ABS system is just the full tree of PKGBUILDs used to build the binary packages in the official Arch Linux repositories. If you only want to build a few packages, there are other tools available to retrieve individual PKGBUILDs and local source files such as [http://xyne.archlinux.ca/info/pbget pbget].<br />
<br />
First make sure you have all the necessary tools installed in order to run abs/makepkg and to actually compile software from their sources:<br />
<br />
pacman -Sy base-devel<br />
pacman -S abs<br />
<br />
Answer 'Y' or just press Enter.<br />
<br />
You could now run <code>abs</code> to fetch all the PKGBUILDs and associated files from which the original Arch packages are being built:<br />
<br />
abs<br />
<br />
That will recreate an SVN hierarchy of the repos under /var/abs on your hard drive. By default some repositories are disabled; you'd have to edit /etc/abs.conf first and remove the exclamation marks.<br />
<br />
Create a build directory. Example:<br />
$ mkdir ~/abs<br />
<br />
== Installing from buildscripts ==<br />
Sometimes from 3rd party repos we get *.pkgbuild file only. In that case use:<br />
$ makepkg -p <file><br />
<br />
<br />
Congratulations! You now have successfully installed your own package!<br />
<br />
== Useful Links ==<br />
<br />
* [http://aur.archlinux.org AUR]<br />
* [http://www.archlinux.org/pacman/makepkg.8.html the Makepkg man page]<br />
* [[Arch CVS & SVN PKGBUILD guidelines]]<br />
* [[Building Packages in Arch Linux]]<br />
* [[Makepkg.conf]]<br />
* [[PKGBUILD Variables]]</div>Bhobbithttps://wiki.archlinux.org/index.php?title=PKGBUILD&diff=85185PKGBUILD2009-11-26T00:40:33Z<p>Bhobbit: Added categories</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:Package development (English)]]<br />
[[Category:Guidelines (English)]]<br />
<br />
=Variables=<br />
<br />
The following are variables that can be filled out in the ''PKGBUILD'' file:<br />
* '''''pkgname'''''<br />
** The name of the package. It should consist of '''alphanumeric characters only''' and all letters should be '''lowercase'''. For the sake of consistency, ''pkgname'' should match the name of the source tarball of the software you are packaging. For instance, if the software is in ''foobar-2.5.tar.gz'', the ''pkgname'' value should be ''foobar''. The present working directory the ''PKGBUILD'' file is in should also match the ''pkgname''.<br />
<br />
* '''''pkgver'''''<br />
** The version of the package. The value should be the same as the version released by the author of the package. It can contain letters, numbers and periods but '''CANNOT''' contain a hyphen. If the author of the package uses a hyphen in their version numbering scheme, replace it with an underscore. For instance, if the version is ''0.99-10'', it should be changed to ''0.99_10''. <br />
<br />
* '''''pkgrel'''''<br />
** The release number of the package specific to Arch Linux. This value allows users to differentiate between consecutive builds of the same version of a package. When a new package version is first released, the '''release number starts at 1'''. As fixes and optimizations are made to the ''PKGBUILD'' file, the package will be '''re-released''' and the '''release number''' will increment by 1. When a new version of the package comes out, the release number resets to 1.<br />
<br />
* '''''pkgdesc'''''<br />
** The description of the package. The description should be about 80 character or less and should not include the package name in a self-referencing way. For instance, "Nedit is a text editor for X11" should be written as "A text editor for X11."<br />
<br />
* '''''arch'''''<br />
** An array of architectures that the ''PKGBUILD'' file is known to build and work on. Currently, it should contain '''i686''' and/or '''x86_64''', arch=('i686' 'x86_64'). The value '''any''' can also be used for independent packages, but the official repositories of Arch does not support this value. You can access this value with the variable <code>$CARCH</code> during the build.<br />
<br />
* '''''url'''''<br />
** The URL of the official site of the software being packaged.<br />
* '''''license'''''<br />
** The license under which the software is distributed. A ''licenses'' package has been created in ''[core]'' that stores common licenses in ''/usr/share/licenses/common'', i.e. ''/usr/share/licenses/common/GPL''. If a package is licensed under one of these licenses, the value should be set to the directory name, e.g. ''license=('GPL')''. If the appropriate license is not included in the official ''licenses'' package, several things must be done:<br />
**# The license file(s) should be included in: ''/usr/share/licenses/'''pkgname'''/'', e.g. ''/usr/share/licenses/foobar/LICENSE''.<br />
**# If the source tarball does '''NOT''' contain the license details and the license is only displayed elsewhere, e.g. a website, then you need to copy the license to a file and include it.<br />
**# Add '''custom''' to the ''licenses'' array. Optionally, you can replace '''custom''' with '''custom:name of license'''. Once a license is used in two or more packages in an official repository (including ''[community]''), it becomes a part of the ''licenses'' package.<br />
** The [[Wikipedia:BSD_License|BSD]], [[Wikipedia:MIT_License|MIT]], [[Wikipedia:ZLIB_license|zlib/png]] and [[Wikipedia:Python_License|Python]] licenses are special cases and could not be included in the ''licenses'' package. For the sake of the ''license'' array, it is treated as a common license (''license=('BSD')'', ''license=('MIT')'', ''license=('ZLIB')'' and ''license=('Python')'') but technically each one is a custom license because each one has its own copyright line. Any packages licensed under these four should have its own unique license stored in ''/usr/share/licenses/'''pkgname'''''. Some packages may not be covered by a single license. In these cases, multiple entries may be made in the license array, e.g. ''license=('GPL' 'custom:name of license')''.<br />
** Additionally, the (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:<br />
*** (L)GPL - (L)GPLv2 or any later version<br />
*** (L)GPL2 - (L)GPL2 only<br />
*** (L)GPL3 - (L)GPL3 or any later version<br />
<br />
* '''''groups'''''<br />
** The group the package belongs in. For instance, when you install the ''kdebase'' package, it installs all packages that belongs in the ''kde'' group.<br />
<br />
* '''''depends'''''<br />
** An array of package names that must be installed before this software can be run. If a software requires a minimum version of a dependency, the '''>=''' operator should be used to point this out, e.g. ''depends=('foobar>=1.8.0')''. You do not need to list packages that your software depends on if other packages your software depends on already have those packages listed in their dependency. For instance, ''gtk2'' depends on ''glib2'' and ''glibc''. However, ''glibc'' does not need to be listed as a dependency for ''gtk2'' because it is a dependency for ''glib2''.<br />
<br />
* '''''makedepends'''''<br />
** An array of package names that must be installed to build the software but unnecessary for using the software after installation. You can specify the minimum version dependency of the packages in the same format as the ''depends'' array.<br />
<br />
{{Warning | The "base" group is assumed already installed in all Arch setups . The group "base-devel" is assumed already installed when building with makepkg . Members of "base" or "base-devel" '''should not''' be included in (make)depends arrays.}}<br />
<br />
* '''''optdepends'''''<br />
** An array of package names that are not needed for the software to function but provides additional features. A short description of what each package provides should also be noted. An ''optdepends'' may look like this:<br />
optdepends=('cups: printing support'<br />
'sane: scanners support'<br />
'libgphoto2: digital cameras support'<br />
'alsa-lib: sound support'<br />
'giflib: GIF images support'<br />
'libjpeg: JPEG images support'<br />
'libpng: PNG images support')<br />
<br />
* '''''provides'''''<br />
** An array of package names that this package provies the features of (or a virtual package such as ''cron'' or ''sh''). If you use this variable, you should add the version (''pkgver'' and perhaps the ''pkgrel'') that this package will provide if dependencies may be affected by it. For instance, if you are providing a modified ''qt'' package named ''qt-foobar'' version 3.3.8 which provides ''qt'' then the ''provides'' array should look like ''provides=('qt=3.3.8')''. Putting ''provides=('qt')'' will cause to fail those dependencies that require a specific version of ''qt''. Do not add pkgname to your provides array, this is done automatically.<br />
{{ Note | This functionality is slightly broken in pacman 3.1.0 and will be fixed in 3.1.1. This documentation refers to the 3.1.1 syntax which will soon be in use.}}<br />
<br />
* '''''conflicts'''''<br />
** An array of package names that may cause problems with this package if installed. You can also specify the version properties of the conflicting packages in the same format as the ''depends'' array.<br />
* '''''replaces'''''<br />
** An array of obsolete package name that are replaced by this package, e.g. ''replaces=('ethereal')'' for the ''wireshark'' package. After syncing with ''pacman -Sy'', it will immediately replace an installed package upon encountering another package with the matching ''replaces'' in the repositories. If you are providing an alternate version of an already existing package, use the ''conflicts'' variable which is only evaluated when actually installing the conflicting package.<br />
<br />
* '''''backup'''''<br />
** An array of files to be backed up as ''file.pacsave'' when the package is removed. This is commonly used for packages placing configuration files in ''/etc''. The file paths in this array should be relative paths (e.g. etc/pacman.conf) not absolute paths (e.g. /etc/pacman.conf).<br />
<br />
* '''''options'''''<br />
** This array allows you to override some of the default behavior of ''makepkg''. To set an option, include the option name in the array. To reverse the default behavior, place an '''!''' at the front of the option. The following options may be placed in the array:<br />
*** '''''strip''''' - Strips symbols from binaries and libraries.<br />
*** '''''docs''''' - Save ''/doc'' directories.<br />
*** '''''libtool''''' - Leave ''libtool'' (.la) files in packages.<br />
*** '''''emptydirs''''' - Leave empty directories in packages.<br />
*** '''''zipman''''' - Compress ''man'' and ''info'' pages with ''gzip''.<br />
*** '''''ccache''''' - Allow the use of ''ccache'' during build. More useful in its negative form ''!ccache'' with select packages that have problems building with ''ccache''.<br />
*** '''''distcc''''' - Allow the use of ''distcc'' during build. More useful in its negative form ''!distcc'' with select packages that have problems building with ''distcc''.<br />
*** '''''makeflags''''' - Allow the use of user-specific ''makeflags'' during build. More useful in its negative form ''!makeflags'' with select packages that have problems building with custom ''makeflags''.<br />
*** '''''force''''' - Force the package to be upgraded by a ''pacman'' system upgrade operation, even if the version number would normally not trigger such an upgrade. This is useful when the version numbering scheme of a package changes (or is alphanumeric).<br />
<br />
* '''''install'''''<br />
** The name of the ''.install'' script to be included in the package. ''pacman'' has the ability to store and execute a package-specific script when it installs, removes or upgrades a package. The script contains the following functions which run at different times:<br />
*** '''''pre_install''''' - The script is run right before files are extracted. One argument is passed: new package version.<br />
*** '''''post_install''''' - The script is run right after files are extracted. One argument is passed: new package version.<br />
*** '''''pre_upgrade''''' - The script is run right before files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
*** '''''post_upgrade''''' - The script is run after files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
*** '''''pre_remove''''' - The script is run right before files are removed. One argument is passed: old package version.<br />
*** '''''post_remove''''' - The script is run right after files are removed. One argument is passed: old package version.<br />
** {{ Note | A prototype ''.install'' is provided at ''/usr/share/pacman/proto.install''. }}<br />
<br />
* '''''source'''''<br />
** An array of files which are needed to build the package. It must contain the location of the software source, which in most cases is a full HTTP or FTP URL. The previously set variables ''pkgname'' and ''pkgver'' can be used effectively here:<br />
*** <pre>source=(http://example.com/$pkgname-$pkgver.tar.gz)</pre><br />
** If you need to supply which are not downloadable on the fly, e.g. self-made patches, you simply put those into the same directory where your ''PKGBUILD'' file is in and add the filename to this array. Any paths you add here are resolved relative to the directory where the ''PKGBUILD'' lies. Before the actual build process is started, all of the files referenced in this array will be downloaded or checked for existence, and ''makepkg'' will not proceed if any are missing.<br />
<br />
* '''''noextract'''''<br />
** An array of files listed under the ''source'' array which should not be extracted from their archive format by ''makepkg''. This most commonly applies to certain zip files which cannot be handled by ''bsdtar'' because ''libarchive'' processes all files as streams rather than random access as ''unzip'' does. In these situations ''unzip'' should be added in the ''makedepends'' array and the first line of the ''build()'' function should contain:<br />
<pre><br />
cd $srcdir/$pkgname-$pkgver<br />
unzip [source].zip<br />
</pre><br />
<br />
* '''''md5sums'''''<br />
** An array of md5 checksums of the files listed in the ''source'' array. Once all files in the ''source'' array are available, an md5 hash of each file will be automatically generated and compared with the values of this array in the same order they appear in the ''source'' array. While the order of the source files itself does not matter, it is important that it matches the order of this array since ''makepkg'' cannot guess which md5sum belongs to what source file. You can generate this array quickly and easily using the command ''makepkg -g'' in the directory that contains the ''PKGBUILD'' file.<br />
<br />
It is common practice to preserve the order of the ''PKGBUILD'' variables as shown above. However, this is not mandatory, as the only requirement in this context is correct [[Wikipedia:Bash|Bash]] syntax.<br />
<br />
=See also=<br />
<br />
* [[ABS]] The Arch Build System<br />
* [[Arch CVS & SVN PKGBUILD guidelines]]<br />
* [[Makepkg]]<br />
* [[Safe Cflags]]<br />
* [[PKGBUILD Tricks]]</div>Bhobbithttps://wiki.archlinux.org/index.php?title=PKGBUILD&diff=85182PKGBUILD2009-11-26T00:26:28Z<p>Bhobbit: Added See also</p>
<hr />
<div>=Variables=<br />
<br />
The following are variables that can be filled out in the ''PKGBUILD'' file:<br />
* '''''pkgname'''''<br />
** The name of the package. It should consist of '''alphanumeric characters only''' and all letters should be '''lowercase'''. For the sake of consistency, ''pkgname'' should match the name of the source tarball of the software you are packaging. For instance, if the software is in ''foobar-2.5.tar.gz'', the ''pkgname'' value should be ''foobar''. The present working directory the ''PKGBUILD'' file is in should also match the ''pkgname''.<br />
<br />
* '''''pkgver'''''<br />
** The version of the package. The value should be the same as the version released by the author of the package. It can contain letters, numbers and periods but '''CANNOT''' contain a hyphen. If the author of the package uses a hyphen in their version numbering scheme, replace it with an underscore. For instance, if the version is ''0.99-10'', it should be changed to ''0.99_10''. <br />
<br />
* '''''pkgrel'''''<br />
** The release number of the package specific to Arch Linux. This value allows users to differentiate between consecutive builds of the same version of a package. When a new package version is first released, the '''release number starts at 1'''. As fixes and optimizations are made to the ''PKGBUILD'' file, the package will be '''re-released''' and the '''release number''' will increment by 1. When a new version of the package comes out, the release number resets to 1.<br />
<br />
* '''''pkgdesc'''''<br />
** The description of the package. The description should be about 80 character or less and should not include the package name in a self-referencing way. For instance, "Nedit is a text editor for X11" should be written as "A text editor for X11."<br />
<br />
* '''''arch'''''<br />
** An array of architectures that the ''PKGBUILD'' file is known to build and work on. Currently, it should contain '''i686''' and/or '''x86_64''', arch=('i686' 'x86_64'). The value '''any''' can also be used for independent packages, but the official repositories of Arch does not support this value. You can access this value with the variable <code>$CARCH</code> during the build.<br />
<br />
* '''''url'''''<br />
** The URL of the official site of the software being packaged.<br />
* '''''license'''''<br />
** The license under which the software is distributed. A ''licenses'' package has been created in ''[core]'' that stores common licenses in ''/usr/share/licenses/common'', i.e. ''/usr/share/licenses/common/GPL''. If a package is licensed under one of these licenses, the value should be set to the directory name, e.g. ''license=('GPL')''. If the appropriate license is not included in the official ''licenses'' package, several things must be done:<br />
**# The license file(s) should be included in: ''/usr/share/licenses/'''pkgname'''/'', e.g. ''/usr/share/licenses/foobar/LICENSE''.<br />
**# If the source tarball does '''NOT''' contain the license details and the license is only displayed elsewhere, e.g. a website, then you need to copy the license to a file and include it.<br />
**# Add '''custom''' to the ''licenses'' array. Optionally, you can replace '''custom''' with '''custom:name of license'''. Once a license is used in two or more packages in an official repository (including ''[community]''), it becomes a part of the ''licenses'' package.<br />
** The [[Wikipedia:BSD_License|BSD]], [[Wikipedia:MIT_License|MIT]], [[Wikipedia:ZLIB_license|zlib/png]] and [[Wikipedia:Python_License|Python]] licenses are special cases and could not be included in the ''licenses'' package. For the sake of the ''license'' array, it is treated as a common license (''license=('BSD')'', ''license=('MIT')'', ''license=('ZLIB')'' and ''license=('Python')'') but technically each one is a custom license because each one has its own copyright line. Any packages licensed under these four should have its own unique license stored in ''/usr/share/licenses/'''pkgname'''''. Some packages may not be covered by a single license. In these cases, multiple entries may be made in the license array, e.g. ''license=('GPL' 'custom:name of license')''.<br />
** Additionally, the (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:<br />
*** (L)GPL - (L)GPLv2 or any later version<br />
*** (L)GPL2 - (L)GPL2 only<br />
*** (L)GPL3 - (L)GPL3 or any later version<br />
<br />
* '''''groups'''''<br />
** The group the package belongs in. For instance, when you install the ''kdebase'' package, it installs all packages that belongs in the ''kde'' group.<br />
<br />
* '''''depends'''''<br />
** An array of package names that must be installed before this software can be run. If a software requires a minimum version of a dependency, the '''>=''' operator should be used to point this out, e.g. ''depends=('foobar>=1.8.0')''. You do not need to list packages that your software depends on if other packages your software depends on already have those packages listed in their dependency. For instance, ''gtk2'' depends on ''glib2'' and ''glibc''. However, ''glibc'' does not need to be listed as a dependency for ''gtk2'' because it is a dependency for ''glib2''.<br />
<br />
* '''''makedepends'''''<br />
** An array of package names that must be installed to build the software but unnecessary for using the software after installation. You can specify the minimum version dependency of the packages in the same format as the ''depends'' array.<br />
<br />
{{Warning | The "base" group is assumed already installed in all Arch setups . The group "base-devel" is assumed already installed when building with makepkg . Members of "base" or "base-devel" '''should not''' be included in (make)depends arrays.}}<br />
<br />
* '''''optdepends'''''<br />
** An array of package names that are not needed for the software to function but provides additional features. A short description of what each package provides should also be noted. An ''optdepends'' may look like this:<br />
optdepends=('cups: printing support'<br />
'sane: scanners support'<br />
'libgphoto2: digital cameras support'<br />
'alsa-lib: sound support'<br />
'giflib: GIF images support'<br />
'libjpeg: JPEG images support'<br />
'libpng: PNG images support')<br />
<br />
* '''''provides'''''<br />
** An array of package names that this package provies the features of (or a virtual package such as ''cron'' or ''sh''). If you use this variable, you should add the version (''pkgver'' and perhaps the ''pkgrel'') that this package will provide if dependencies may be affected by it. For instance, if you are providing a modified ''qt'' package named ''qt-foobar'' version 3.3.8 which provides ''qt'' then the ''provides'' array should look like ''provides=('qt=3.3.8')''. Putting ''provides=('qt')'' will cause to fail those dependencies that require a specific version of ''qt''. Do not add pkgname to your provides array, this is done automatically.<br />
{{ Note | This functionality is slightly broken in pacman 3.1.0 and will be fixed in 3.1.1. This documentation refers to the 3.1.1 syntax which will soon be in use.}}<br />
<br />
* '''''conflicts'''''<br />
** An array of package names that may cause problems with this package if installed. You can also specify the version properties of the conflicting packages in the same format as the ''depends'' array.<br />
* '''''replaces'''''<br />
** An array of obsolete package name that are replaced by this package, e.g. ''replaces=('ethereal')'' for the ''wireshark'' package. After syncing with ''pacman -Sy'', it will immediately replace an installed package upon encountering another package with the matching ''replaces'' in the repositories. If you are providing an alternate version of an already existing package, use the ''conflicts'' variable which is only evaluated when actually installing the conflicting package.<br />
<br />
* '''''backup'''''<br />
** An array of files to be backed up as ''file.pacsave'' when the package is removed. This is commonly used for packages placing configuration files in ''/etc''. The file paths in this array should be relative paths (e.g. etc/pacman.conf) not absolute paths (e.g. /etc/pacman.conf).<br />
<br />
* '''''options'''''<br />
** This array allows you to override some of the default behavior of ''makepkg''. To set an option, include the option name in the array. To reverse the default behavior, place an '''!''' at the front of the option. The following options may be placed in the array:<br />
*** '''''strip''''' - Strips symbols from binaries and libraries.<br />
*** '''''docs''''' - Save ''/doc'' directories.<br />
*** '''''libtool''''' - Leave ''libtool'' (.la) files in packages.<br />
*** '''''emptydirs''''' - Leave empty directories in packages.<br />
*** '''''zipman''''' - Compress ''man'' and ''info'' pages with ''gzip''.<br />
*** '''''ccache''''' - Allow the use of ''ccache'' during build. More useful in its negative form ''!ccache'' with select packages that have problems building with ''ccache''.<br />
*** '''''distcc''''' - Allow the use of ''distcc'' during build. More useful in its negative form ''!distcc'' with select packages that have problems building with ''distcc''.<br />
*** '''''makeflags''''' - Allow the use of user-specific ''makeflags'' during build. More useful in its negative form ''!makeflags'' with select packages that have problems building with custom ''makeflags''.<br />
*** '''''force''''' - Force the package to be upgraded by a ''pacman'' system upgrade operation, even if the version number would normally not trigger such an upgrade. This is useful when the version numbering scheme of a package changes (or is alphanumeric).<br />
<br />
* '''''install'''''<br />
** The name of the ''.install'' script to be included in the package. ''pacman'' has the ability to store and execute a package-specific script when it installs, removes or upgrades a package. The script contains the following functions which run at different times:<br />
*** '''''pre_install''''' - The script is run right before files are extracted. One argument is passed: new package version.<br />
*** '''''post_install''''' - The script is run right after files are extracted. One argument is passed: new package version.<br />
*** '''''pre_upgrade''''' - The script is run right before files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
*** '''''post_upgrade''''' - The script is run after files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
*** '''''pre_remove''''' - The script is run right before files are removed. One argument is passed: old package version.<br />
*** '''''post_remove''''' - The script is run right after files are removed. One argument is passed: old package version.<br />
** {{ Note | A prototype ''.install'' is provided at ''/usr/share/pacman/proto.install''. }}<br />
<br />
* '''''source'''''<br />
** An array of files which are needed to build the package. It must contain the location of the software source, which in most cases is a full HTTP or FTP URL. The previously set variables ''pkgname'' and ''pkgver'' can be used effectively here:<br />
*** <pre>source=(http://example.com/$pkgname-$pkgver.tar.gz)</pre><br />
** If you need to supply which are not downloadable on the fly, e.g. self-made patches, you simply put those into the same directory where your ''PKGBUILD'' file is in and add the filename to this array. Any paths you add here are resolved relative to the directory where the ''PKGBUILD'' lies. Before the actual build process is started, all of the files referenced in this array will be downloaded or checked for existence, and ''makepkg'' will not proceed if any are missing.<br />
<br />
* '''''noextract'''''<br />
** An array of files listed under the ''source'' array which should not be extracted from their archive format by ''makepkg''. This most commonly applies to certain zip files which cannot be handled by ''bsdtar'' because ''libarchive'' processes all files as streams rather than random access as ''unzip'' does. In these situations ''unzip'' should be added in the ''makedepends'' array and the first line of the ''build()'' function should contain:<br />
<pre><br />
cd $srcdir/$pkgname-$pkgver<br />
unzip [source].zip<br />
</pre><br />
<br />
* '''''md5sums'''''<br />
** An array of md5 checksums of the files listed in the ''source'' array. Once all files in the ''source'' array are available, an md5 hash of each file will be automatically generated and compared with the values of this array in the same order they appear in the ''source'' array. While the order of the source files itself does not matter, it is important that it matches the order of this array since ''makepkg'' cannot guess which md5sum belongs to what source file. You can generate this array quickly and easily using the command ''makepkg -g'' in the directory that contains the ''PKGBUILD'' file.<br />
<br />
It is common practice to preserve the order of the ''PKGBUILD'' variables as shown above. However, this is not mandatory, as the only requirement in this context is correct [[Wikipedia:Bash|Bash]] syntax.<br />
<br />
=See also=<br />
<br />
* [[ABS]] The Arch Build System<br />
* [[Arch CVS & SVN PKGBUILD guidelines]]<br />
* [[Makepkg]]<br />
* [[Safe Cflags]]<br />
* [[PKGBUILD Tricks]]</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Creating_packages&diff=85181Creating packages2009-11-26T00:21:46Z<p>Bhobbit: /* See also */</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:Package development (English)]]<br />
[[Category:Guidelines (English)]]<br />
<br />
=Introduction=<br />
All information for creating a package is placed in a <code>PKGBUILD</code> file. When you run <code>makepkg</code>, it will look for a <code>PKGBUILD</code> file in the current working directory, and compile the software's source code according to the instructions in the <code>PKGBUILD</code> file. After successfully finishing the compilation, the resulting binaries, as well as all available meta-information like package version and dependencies, are packed in the <code>name.pkg.tar.gz</code> package file that can be cleanly installed with <code>pacman -U <package file></code>.<br />
<br />
=Setting Up=<br />
<br />
First, verify that you have the necessary tools installed. You need the following packages:<br />
*'''base-devel''' (a package group): Contains ''make'' and additional tools for compiling from the source.<br />
*'''fakeroot''' (part of 'base-devel'): Allows a normal user the necessary root permissions to create packages in the build environment without being able to alter the wider system. If the build process attempts to alter files outside of the build environment, errors are produced and the build fails. This is very useful for checking the quality, safety and integrity of the packages for distribution.<br />
*'''abs''': [[ABS|Arch Build System]]. The abs package will install all of the PKGBUILDs and local source files needed to rebuild the binary packages in the official Arch Linux repositories. You do not need abs to use makepkg and you should only install abs if you intend to rebuild man packages in the ABS tree. If you only need a few PKGBUILDs, you can retrieve the latest versions from the web interface directly or via other available tools such as [http://xyne.archlinux.ca/info/pbget pbget]<br />
<br />
If you do not have them, install them using ''pacman'':<br />
# pacman -S abs base-devel fakeroot<br />
<br />
One of the key tools for building packages is ''makepkg''. It does the following:<br />
#Checks if package dependencies are installed.<br />
#Downloads the source file(s) from the specified server(s).<br />
#Unpacks the source file(s).<br />
#Compiles the software and installs it under a fakeroot environment.<br />
#Strips symbols from binaries and libraries.<br />
#Generates the package meta file which is included with each package.<br />
#Compress the fakeroot environment into a package file.<br />
#Stores the package file in the configured destination directory, which is the present working directory by default.<br />
<br />
''abs'' is optional to use, but it gives you the option to build official packages directly from source instead of downloading the pre-built, binary copy. It also helps you keep all of your ''PKGBUILD'' files, both official and unofficial in a centralized location. A ''PKGBUILD'' file contains metadata about a package, and is the essential component for building packages. You can specify which repositories to include in your ABS tree in the ''/etc/abs.conf'' file. To obtain the ABS tree which contains all of the ''PKGBUILD'' files, just run the ''abs'' command as root:<br />
# abs<br />
Create an ABS build directory under the /home of your non-root user, if you have not done so already: <br />
$ mkdir ~/abs<br />
<br />
= Package file =<br />
<br />
ABS automatically downloads the source code for the particular software you are compiling. It then unpacks, compiles the sources and squeezes everything into an installable package.<br />
Typically, the resulting package file is a file called ''foo''.pkg.tar.gz. <br />
<br />
In fact, it is no more than a gzipped tar archive or 'tarball' which contains:<br />
<br />
* The files to install<br />
<br />
*.PKGINFO: contains all the metadata needed by pacman to deal with packages, dependencies, etc.<br />
<br />
*.FILELIST: lists all the files of the archive. It's used in order to uninstall the software or to check for file conflicts. (Obsolete now; used for pacman-2.x)<br />
<br />
*.INSTALL: a file used to execute commands after the install/upgrade/remove stage. (This file is present only if specified in the PKGBUILD.)<br />
<br />
Since pacman manages tar.gz packages, foo.pkg.tar.gz can now easily be installed/removed.<br />
<br />
=Preparing the Files=<br />
<br />
Now download the source tarball of the software you want to package, extract it, and note all commands needed to compile and install it. You will be repeating the same commands in the ''PKGBUILD'' file. Most software authors stick to the 3-step build cycle:<br />
./configure<br />
make<br />
make install<br />
When you run ''makepkg'', it will look for a ''PKGBUILD'' file in the present working directory. If a ''PKGBUILD'' file is found it will download the software's source code and compile it according to the instructions specified in the ''PKGBUILD'' file. The instructions must be fully interpretable by [[Wikipedia:Bash|Bash]]. After successful compilation, the resulting binaries and metadata of the package, i.e. package version and dependencies, are packed in a ''pkgname.pkg.tar.gz'' package file that can be cleanly installed with ''pacman -U [package file]''.<br />
To start out with a new package, you should first create an empty working directory, preferably named ''~/abs/'''pkgname'''''. Once you make the directory and change into it, create a ''PKGBUILD'' file to work with either by copying the prototype from ''/usr/share/pacman/PKGBUILD.proto'' or by copying a ''PKGBUILD'' from another package. The latter is quite useful if you want to modify compilation options of a package instead of creating an entirely new one.<br />
<br />
=Defining PKGBUILD Variables=<br />
The PKGBUILD file contains metadata about a package. It is a plain text file. The following is a prototype PKGBUILD. It can be found in /usr/share/pacman along with other templates.<br />
<br />
<pre><br />
# This is an example PKGBUILD file. Use this as a start to creating your own,<br />
# and remove these comments. For more information, see 'man PKGBUILD'.<br />
# Note: Please fill out the license field for your package. If it is unknown,<br />
# then please put 'unknown'.<br />
<br />
# Contributor: Your Name <youremail@domain.com><br />
pkgname=NAME<br />
pkgver=VERSION<br />
pkgrel=1<br />
pkgdesc=""<br />
arch=()<br />
url=""<br />
license=('GPL')<br />
groups=()<br />
depends=()<br />
makedepends=()<br />
provides=()<br />
conflicts=()<br />
replaces=()<br />
backup=()<br />
install=<br />
source=($pkgname-$pkgver.tar.gz)<br />
noextract=()<br />
md5sums=() #generate with 'makepkg -g'<br />
<br />
build() {<br />
cd "$srcdir/$pkgname-$pkgver"<br />
<br />
./configure --prefix=/usr<br />
make || return 1<br />
make DESTDIR="$pkgdir/" install<br />
}<br />
</pre><br />
<br />
A listing of possible PKGBUILD variables and their meaning can be found on [[PKGBUILD Variables]] page.<br />
<br />
=The build() function=<br />
<br />
Now you need to implement the ''build()'' function in the ''PKGBUILD'' file. This function uses common shell commands in the [http://en.wikipedia.org/wiki/Bash Bash] syntax to automatically compile software and create a ''pkg/'' directory to install the software to. This allows ''makepkg'' to pack it up without having to pick all the necessary files from your actual filesystem.<br />
The first step in the ''build()'' function is to change into the directory created by uncompressing the source tarball. In most common cases the first command will look like this:<br />
cd $srcdir/$pkgname-$pkgver<br />
<br />
Now, you need to list the same commands you used when you manually compiled the software. The ''build()'' function in essence automates everything you did by hand and compiles the software in the fakeroot build environment. If the software you are packaging uses a configure script, it is good practice to use ''--prefix=/usr'' when building packages for ''pacman''. A lot of software install their files relative to the ''/usr/local'' directory, which should only be done if you are manually building from source. All Arch Linux packages should use the ''/usr'' directory. As seen in the ''/usr/share/pacman/PKGBUILD.proto'' file, the next two lines should look like this:<br />
./configure --prefix=/usr<br />
make || return 1<br />
<br />
The final step in the ''build()'' funciton is to put the compiled files in a directory where ''makepkg'' can retrieve to create a package. This by default is the ''pkg/'' directory - a simple fakeroot environment. It imitates the root of your filesystem to the software's installation procedure. If you have to manually install files under the root of your filesystem, you should instead install it in the ''pkg/'' directory under the same directory structure, e.g. if you want to install a file to ''/usr/bin'', it should instead be placed under ''$pkgdir/usr/bin''. Very few software require the user to copy dozens of files manually, and you usually will not have to worry about this. Instead, for most software you will have to call ''make install''. The final line should look like the following in order to correctly install the software in the ''pkg/'' directory:<br />
make DESTDIR=$pkgdir install || return 1<br />
<br />
'''Note''': It is sometimes the case where <code>DESTDIR</code> is not used in the <code>Makefile</code>; you may need to use <code>prefix</code> instead. If the package is built with autoconf/automake, use <code>DESTDIR</code>; this is what is [http://sources.redhat.com/automake/automake.html#Install documented] in the manuals. If <code>DESTDIR</code> does not work, try building with <code>make prefix="$pkgdir/usr/" install</code>. If that does not work, you'll have to look further into the install commands that are executed by "<code>make <...> install</code>".<br />
<br />
In some odd cases, the software expects to be run from a single directory. In such cases it is wise to simply copy these to ''$pkgdir/opt''.<br />
More often than not the installation process of the software will create any subdirectories below the ''pkg/'' directory. If it does not, however, ''makepkg'' will generate a lot of errors and you will need to manually create subdirectories by adding the appropriate ''mkdir -p'' commands in the ''build()'' function before the installation procedure is run.<br />
Also, ''makepkg'' defines three variables that you should use as part of the build and install process:<br />
*'''''startdir''''' - This contains the absolute path to the directory where the ''PKGBUILD'' file is located, which is the present working directory. This variable is almost always used in combination with ''/src'' or ''/pkg'' postfixes, but the use of ''srcdir'' and ''pkgdir'' variables is preferred.<br />
*'''''srcdir''''' - This points to the directory where ''makepkg'' extracts or copies all source files. It is currently an alias for ''$startdir/src''.<br />
*'''''pkgdir''''' - This points to the directory where ''makepkg'' bundles the installed package, which becomes the root directory of your built package. It is currently an alias for ''$startdir/pkg''.<br />
<br />
'''Note:''' makepkg, and thus the build() function, is intended to be non-interactive. Interactive utilities or scripts called in the build() function may break makepkg, particularly if it is invoked with build-logging enabled (-l). (see [http://bugs.archlinux.org/task/13214 Arch Linux Bug #13214].)<br />
<br />
=Additional Guidelines=<br />
<br />
Here are some additional guidelines that you should adhere to:<br />
*All elements in an array variable '''must be separated by spaces'''.<br />
*If possible, remove empty lines from the ''PKGBUILD'' including fields that have empty values.<br />
*Wherever possible, use ''|| return 1'' for critical build functions: make || return 1 make DESTDIR=$pkgdir install || return 1 <br />
*'''Do not introduce new variables''' into your ''PKGBUILD'' file unless the package cannot be built without doing so, as these could possibly conflict with variables used in ''makepkg'' itself. If a new variable is absolutely required, '''prefix the variable name with an underscore''': _customvariable= <br />
*'''Avoid''' using ''/usr/libexec/'' for anything. Use ''/usr/lib/pkgname'' instead.<br />
*The ''packager'' field from the package meta file can be customized by the package builder by modifying the appropriate option in the ''/etc/makepkg.conf'' file, or alternatively by exporting the ''PACKAGER'' environment variable before building packages with ''makepkg'': # export PACKAGER="Your Name &lt;email@domain.com&gt;" <br />
* '''Configuration files''' should be placed in the ''/etc'' directory. If there is more than one configuration file, it is customary to use a subdirectory in order to keep the ''/etc'' area as clean as possible. Use ''/etc/'''pkgname''''' or a suitable alternative, e.g., [http://httpd.apache.org/ Apache] uses ''/etc/httpd/''. <br />
*Package files should follow these '''general directory guidelines''': <br />
**''/etc/'' - System essential configuration files<br />
**''/usr/bin'' - Application binaries<br />
**''/usr/sbin'' - System binaries<br />
**''/usr/lib'' - Libraries<br />
**''/usr/include'' - Header files<br />
**''/usr/lib/pkgname'' - Modules, plugins, etc.<br />
**''/usr/share/man'' - Manpages<br />
**''/usr/share/pkgname'' - Application data<br />
**''/usr/share/licenses/pkgname'' - Package license, if not included under common<br />
**''/etc/pkgname'' - Configuration files<br />
**''/opt'' - Large self-contained packages such as Java, etc.<br />
<br />
*Packages should not contain the following directories: <br />
**''/dev''<br />
**''/home''<br />
**''/media''<br />
**''/mnt''<br />
**''/proc''<br />
**''/root''<br />
**''/selinux''<br />
**''/sys''<br />
**''/tmp''<br />
**''/var/tmp''<br />
<br />
=Testing the PKGBUILD=<br />
<br />
As you are writing the ''build()'' function, you will want to test your changes frequently to ensure there are no bugs. You can do this using the ''makepkg'' command in the directory containing the ''PKGBUILD'' file. With a properly formatted ''PKGBUILD'', this will create a package, but with a broken or unfinished one it will throw an error.<br />
If ''makepkg'' finishes successfully, it will place a file named ''pkgname-pkgver.pkg.tar.gz'' in your working directory. This is package that can be installed with the ''pacman -U'' command. However, just because a package file was built does not imply that it is fully functional. It might conceivably contain only the directory and no files whatsoever if, for example, a prefix was specified improperly. You can use ''pacman'''s query functions to display a list of files contained in the package and the dependencies it requires with ''pacman -Qlp [package file]'' and ''pacman -Qip [package file]'' respectively.<br />
If the package looks sane, then you are done! However, if you plan on release the ''PKGBUILD'' file, it is imperative that you check and double check the contents of the ''depends'' array. <br />
<br />
=ldd and namcap=<br />
<br />
Dependencies are the most common packaging error. There are two excellent tools you can use to check dependencies. The first one is ''ldd'', which will show you the shared library dependencies of dynamic executables:<br />
$ ldd gcc<br />
linux-gate.so.1 => (0xb7f33000)<br />
libc.so.6 => /lib/libc.so.6 (0xb7de0000)<br />
/lib/ld-linux.so.2 (0xb7f34000)<br />
<br />
The other tool is ''namcap'' which not only checks for dependencies but the overall sanity of your package. It can be used on both the ''PKGBUILD'' file and the ''pkg.tar.gz'' package. It will report any bad permissions, missing dependencies, unnecessary dependencies and other common mistakes. You can install ''namcap'' via ''pacman'':<br />
$ pacman -S namcap<br />
<br />
To use ''namcap'', simply supply a ''PKGBUILD'' file or a ''pkg.tar.gz'' package as the argument:<br />
$ namcap PKGBUILD<br />
or $ namcap pkgname.tar.gz<br />
<br />
Although ''namcap'' can help detect dependencies, it is not always correct. Verify dependencies by looking at the documentation of the software.<br />
<br />
==Testing the package==<br />
Also make sure that the package binaries actually ''run'' flawlessly! It's really annoying to release a package that contains all necessary files, but dumps core because of some obscure configuration option that doesn't quite work well with the rest of the system. If you're only going to compile packages for your own system, though, you don't need to worry too much about this quality assurance step, as you're the only person suffering from mistakes after all.<br />
<br />
=Submitting Packages to the AUR=<br />
<br />
Follow these steps to submit a package into the AUR:<br />
#Register a new account if you do not already have one.<br />
#Check all of the official repositories (''[core]'', ''[extra]'', and ''[community]'') and see if the package already exists. If it is inside any of those repositories, '''DO NOT''' submit the package. If the package is broken, file a bug report.<br />
#Check the ''[unsupported]'' repository for the package. If it is currently maintained, changes can be submitted in a comment for the maintaner's attention. If it is unmaintained, the package can be adopted and updated.<br />
#To upload the package to the AUR, the directory containing the ''PKGBUILD'' file and any other required files must be compressed as a tarball. The archive name should contain the name of the package, e.g. ''foo.tar.gz.''. You can easily build a tarball by using ''makepkg --source'' in the directory. This makes a tarball named ''pkgname-pkver-pkrel.src.tar.gz'', which you can then upload to the AUR. The tarball '''cannot''' contain the binary tarball created by ''makepkg'' or the source tarball of the software. Packages that contain binaries or that are very poorly written will be deleted without warning.<br />
#Click the '''Submit''' link by the menu in the AUR. Choose the appropriate category for your package and upload.<br />
<br />
=Summary=<br />
#Download the source tarball of the software you want to package.<br />
#Try compiling the package and installing it into an arbitrary directory.<br />
#Copy over the prototype ''/usr/share/pacman/PKGBUILD.proto'' and rename it to ''PKGBUILD'' in a temporary working directory - preferably ''~/abs/''.<br />
#Edit the ''PKGBUILD'' according to the needs of your package.<br />
#Run ''makepkg'' and see whether the resulting package is built correctly.<br />
#If not, repeat the last two steps.<br />
<br />
==Warnings==<br />
* Before you can automate the package building process, you should have done it manually at least once unless you know ''exactly'' what you're doing ''in advance'', in which case you would not be reading this in the first place. Unfortunately, although a good bunch of program authors stick to the 3-step build cycle of "./configure; make; make install", this is not always the case, and things can get real ugly if you have to apply patches to make everything work at all. Rule of thumb: If you can't get the program to compile from the source tarball, and make it install itself to a defined, temporary subdirectory, you don't even need to try packaging it. There isn't any magic pixie dust in <code>makepkg</code> that makes source problems go away.<br />
* In a few cases, the packages are not even available as source and you have to use something like <code>sh installer.run</code> to get it to work. You will have to do quite a bit of research (read READMEs, INSTALL instructions, man pages, perhaps ebuilds from gentoo or other package installers, possibly even the MAKEFILEs or source code) to get it working. In some really bad cases, you have to edit the source files to get it to work at all. However, <code>makepkg</code> needs to be completely autonomous, with no user input. Therefore if you need to edit the Makefiles, you may have to bundle a custom patch with the <code>PKGBUILD</code> and install it from inside the <code>build()</code> function, or you might have to issue some <code>sed</code> commands from inside the <code>build()</code> function.<br />
<br />
=See also=<br />
* [[ABS]] The Arch Build System<br />
* [[Arch CVS & SVN PKGBUILD guidelines]]<br />
* [[ArchLinux User-community Repository (AUR)]]<br />
* [[Kernel Compilation with ABS]]<br />
* [[Makepkg]]<br />
* [[Safe Cflags]]<br />
* [[PKGBUILD Tricks]]<br />
* [[PKGBUILD Variables]]</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Creating_packages&diff=85180Creating packages2009-11-26T00:19:20Z<p>Bhobbit: Moved PKGBUILD variables section to PKGBUILD Variables</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:Package development (English)]]<br />
[[Category:Guidelines (English)]]<br />
<br />
=Introduction=<br />
All information for creating a package is placed in a <code>PKGBUILD</code> file. When you run <code>makepkg</code>, it will look for a <code>PKGBUILD</code> file in the current working directory, and compile the software's source code according to the instructions in the <code>PKGBUILD</code> file. After successfully finishing the compilation, the resulting binaries, as well as all available meta-information like package version and dependencies, are packed in the <code>name.pkg.tar.gz</code> package file that can be cleanly installed with <code>pacman -U <package file></code>.<br />
<br />
=Setting Up=<br />
<br />
First, verify that you have the necessary tools installed. You need the following packages:<br />
*'''base-devel''' (a package group): Contains ''make'' and additional tools for compiling from the source.<br />
*'''fakeroot''' (part of 'base-devel'): Allows a normal user the necessary root permissions to create packages in the build environment without being able to alter the wider system. If the build process attempts to alter files outside of the build environment, errors are produced and the build fails. This is very useful for checking the quality, safety and integrity of the packages for distribution.<br />
*'''abs''': [[ABS|Arch Build System]]. The abs package will install all of the PKGBUILDs and local source files needed to rebuild the binary packages in the official Arch Linux repositories. You do not need abs to use makepkg and you should only install abs if you intend to rebuild man packages in the ABS tree. If you only need a few PKGBUILDs, you can retrieve the latest versions from the web interface directly or via other available tools such as [http://xyne.archlinux.ca/info/pbget pbget]<br />
<br />
If you do not have them, install them using ''pacman'':<br />
# pacman -S abs base-devel fakeroot<br />
<br />
One of the key tools for building packages is ''makepkg''. It does the following:<br />
#Checks if package dependencies are installed.<br />
#Downloads the source file(s) from the specified server(s).<br />
#Unpacks the source file(s).<br />
#Compiles the software and installs it under a fakeroot environment.<br />
#Strips symbols from binaries and libraries.<br />
#Generates the package meta file which is included with each package.<br />
#Compress the fakeroot environment into a package file.<br />
#Stores the package file in the configured destination directory, which is the present working directory by default.<br />
<br />
''abs'' is optional to use, but it gives you the option to build official packages directly from source instead of downloading the pre-built, binary copy. It also helps you keep all of your ''PKGBUILD'' files, both official and unofficial in a centralized location. A ''PKGBUILD'' file contains metadata about a package, and is the essential component for building packages. You can specify which repositories to include in your ABS tree in the ''/etc/abs.conf'' file. To obtain the ABS tree which contains all of the ''PKGBUILD'' files, just run the ''abs'' command as root:<br />
# abs<br />
Create an ABS build directory under the /home of your non-root user, if you have not done so already: <br />
$ mkdir ~/abs<br />
<br />
= Package file =<br />
<br />
ABS automatically downloads the source code for the particular software you are compiling. It then unpacks, compiles the sources and squeezes everything into an installable package.<br />
Typically, the resulting package file is a file called ''foo''.pkg.tar.gz. <br />
<br />
In fact, it is no more than a gzipped tar archive or 'tarball' which contains:<br />
<br />
* The files to install<br />
<br />
*.PKGINFO: contains all the metadata needed by pacman to deal with packages, dependencies, etc.<br />
<br />
*.FILELIST: lists all the files of the archive. It's used in order to uninstall the software or to check for file conflicts. (Obsolete now; used for pacman-2.x)<br />
<br />
*.INSTALL: a file used to execute commands after the install/upgrade/remove stage. (This file is present only if specified in the PKGBUILD.)<br />
<br />
Since pacman manages tar.gz packages, foo.pkg.tar.gz can now easily be installed/removed.<br />
<br />
=Preparing the Files=<br />
<br />
Now download the source tarball of the software you want to package, extract it, and note all commands needed to compile and install it. You will be repeating the same commands in the ''PKGBUILD'' file. Most software authors stick to the 3-step build cycle:<br />
./configure<br />
make<br />
make install<br />
When you run ''makepkg'', it will look for a ''PKGBUILD'' file in the present working directory. If a ''PKGBUILD'' file is found it will download the software's source code and compile it according to the instructions specified in the ''PKGBUILD'' file. The instructions must be fully interpretable by [[Wikipedia:Bash|Bash]]. After successful compilation, the resulting binaries and metadata of the package, i.e. package version and dependencies, are packed in a ''pkgname.pkg.tar.gz'' package file that can be cleanly installed with ''pacman -U [package file]''.<br />
To start out with a new package, you should first create an empty working directory, preferably named ''~/abs/'''pkgname'''''. Once you make the directory and change into it, create a ''PKGBUILD'' file to work with either by copying the prototype from ''/usr/share/pacman/PKGBUILD.proto'' or by copying a ''PKGBUILD'' from another package. The latter is quite useful if you want to modify compilation options of a package instead of creating an entirely new one.<br />
<br />
=Defining PKGBUILD Variables=<br />
The PKGBUILD file contains metadata about a package. It is a plain text file. The following is a prototype PKGBUILD. It can be found in /usr/share/pacman along with other templates.<br />
<br />
<pre><br />
# This is an example PKGBUILD file. Use this as a start to creating your own,<br />
# and remove these comments. For more information, see 'man PKGBUILD'.<br />
# Note: Please fill out the license field for your package. If it is unknown,<br />
# then please put 'unknown'.<br />
<br />
# Contributor: Your Name <youremail@domain.com><br />
pkgname=NAME<br />
pkgver=VERSION<br />
pkgrel=1<br />
pkgdesc=""<br />
arch=()<br />
url=""<br />
license=('GPL')<br />
groups=()<br />
depends=()<br />
makedepends=()<br />
provides=()<br />
conflicts=()<br />
replaces=()<br />
backup=()<br />
install=<br />
source=($pkgname-$pkgver.tar.gz)<br />
noextract=()<br />
md5sums=() #generate with 'makepkg -g'<br />
<br />
build() {<br />
cd "$srcdir/$pkgname-$pkgver"<br />
<br />
./configure --prefix=/usr<br />
make || return 1<br />
make DESTDIR="$pkgdir/" install<br />
}<br />
</pre><br />
<br />
A listing of possible PKGBUILD variables and their meaning can be found on [[PKGBUILD Variables]] page.<br />
<br />
=The build() function=<br />
<br />
Now you need to implement the ''build()'' function in the ''PKGBUILD'' file. This function uses common shell commands in the [http://en.wikipedia.org/wiki/Bash Bash] syntax to automatically compile software and create a ''pkg/'' directory to install the software to. This allows ''makepkg'' to pack it up without having to pick all the necessary files from your actual filesystem.<br />
The first step in the ''build()'' function is to change into the directory created by uncompressing the source tarball. In most common cases the first command will look like this:<br />
cd $srcdir/$pkgname-$pkgver<br />
<br />
Now, you need to list the same commands you used when you manually compiled the software. The ''build()'' function in essence automates everything you did by hand and compiles the software in the fakeroot build environment. If the software you are packaging uses a configure script, it is good practice to use ''--prefix=/usr'' when building packages for ''pacman''. A lot of software install their files relative to the ''/usr/local'' directory, which should only be done if you are manually building from source. All Arch Linux packages should use the ''/usr'' directory. As seen in the ''/usr/share/pacman/PKGBUILD.proto'' file, the next two lines should look like this:<br />
./configure --prefix=/usr<br />
make || return 1<br />
<br />
The final step in the ''build()'' funciton is to put the compiled files in a directory where ''makepkg'' can retrieve to create a package. This by default is the ''pkg/'' directory - a simple fakeroot environment. It imitates the root of your filesystem to the software's installation procedure. If you have to manually install files under the root of your filesystem, you should instead install it in the ''pkg/'' directory under the same directory structure, e.g. if you want to install a file to ''/usr/bin'', it should instead be placed under ''$pkgdir/usr/bin''. Very few software require the user to copy dozens of files manually, and you usually will not have to worry about this. Instead, for most software you will have to call ''make install''. The final line should look like the following in order to correctly install the software in the ''pkg/'' directory:<br />
make DESTDIR=$pkgdir install || return 1<br />
<br />
'''Note''': It is sometimes the case where <code>DESTDIR</code> is not used in the <code>Makefile</code>; you may need to use <code>prefix</code> instead. If the package is built with autoconf/automake, use <code>DESTDIR</code>; this is what is [http://sources.redhat.com/automake/automake.html#Install documented] in the manuals. If <code>DESTDIR</code> does not work, try building with <code>make prefix="$pkgdir/usr/" install</code>. If that does not work, you'll have to look further into the install commands that are executed by "<code>make <...> install</code>".<br />
<br />
In some odd cases, the software expects to be run from a single directory. In such cases it is wise to simply copy these to ''$pkgdir/opt''.<br />
More often than not the installation process of the software will create any subdirectories below the ''pkg/'' directory. If it does not, however, ''makepkg'' will generate a lot of errors and you will need to manually create subdirectories by adding the appropriate ''mkdir -p'' commands in the ''build()'' function before the installation procedure is run.<br />
Also, ''makepkg'' defines three variables that you should use as part of the build and install process:<br />
*'''''startdir''''' - This contains the absolute path to the directory where the ''PKGBUILD'' file is located, which is the present working directory. This variable is almost always used in combination with ''/src'' or ''/pkg'' postfixes, but the use of ''srcdir'' and ''pkgdir'' variables is preferred.<br />
*'''''srcdir''''' - This points to the directory where ''makepkg'' extracts or copies all source files. It is currently an alias for ''$startdir/src''.<br />
*'''''pkgdir''''' - This points to the directory where ''makepkg'' bundles the installed package, which becomes the root directory of your built package. It is currently an alias for ''$startdir/pkg''.<br />
<br />
'''Note:''' makepkg, and thus the build() function, is intended to be non-interactive. Interactive utilities or scripts called in the build() function may break makepkg, particularly if it is invoked with build-logging enabled (-l). (see [http://bugs.archlinux.org/task/13214 Arch Linux Bug #13214].)<br />
<br />
=Additional Guidelines=<br />
<br />
Here are some additional guidelines that you should adhere to:<br />
*All elements in an array variable '''must be separated by spaces'''.<br />
*If possible, remove empty lines from the ''PKGBUILD'' including fields that have empty values.<br />
*Wherever possible, use ''|| return 1'' for critical build functions: make || return 1 make DESTDIR=$pkgdir install || return 1 <br />
*'''Do not introduce new variables''' into your ''PKGBUILD'' file unless the package cannot be built without doing so, as these could possibly conflict with variables used in ''makepkg'' itself. If a new variable is absolutely required, '''prefix the variable name with an underscore''': _customvariable= <br />
*'''Avoid''' using ''/usr/libexec/'' for anything. Use ''/usr/lib/pkgname'' instead.<br />
*The ''packager'' field from the package meta file can be customized by the package builder by modifying the appropriate option in the ''/etc/makepkg.conf'' file, or alternatively by exporting the ''PACKAGER'' environment variable before building packages with ''makepkg'': # export PACKAGER="Your Name &lt;email@domain.com&gt;" <br />
* '''Configuration files''' should be placed in the ''/etc'' directory. If there is more than one configuration file, it is customary to use a subdirectory in order to keep the ''/etc'' area as clean as possible. Use ''/etc/'''pkgname''''' or a suitable alternative, e.g., [http://httpd.apache.org/ Apache] uses ''/etc/httpd/''. <br />
*Package files should follow these '''general directory guidelines''': <br />
**''/etc/'' - System essential configuration files<br />
**''/usr/bin'' - Application binaries<br />
**''/usr/sbin'' - System binaries<br />
**''/usr/lib'' - Libraries<br />
**''/usr/include'' - Header files<br />
**''/usr/lib/pkgname'' - Modules, plugins, etc.<br />
**''/usr/share/man'' - Manpages<br />
**''/usr/share/pkgname'' - Application data<br />
**''/usr/share/licenses/pkgname'' - Package license, if not included under common<br />
**''/etc/pkgname'' - Configuration files<br />
**''/opt'' - Large self-contained packages such as Java, etc.<br />
<br />
*Packages should not contain the following directories: <br />
**''/dev''<br />
**''/home''<br />
**''/media''<br />
**''/mnt''<br />
**''/proc''<br />
**''/root''<br />
**''/selinux''<br />
**''/sys''<br />
**''/tmp''<br />
**''/var/tmp''<br />
<br />
=Testing the PKGBUILD=<br />
<br />
As you are writing the ''build()'' function, you will want to test your changes frequently to ensure there are no bugs. You can do this using the ''makepkg'' command in the directory containing the ''PKGBUILD'' file. With a properly formatted ''PKGBUILD'', this will create a package, but with a broken or unfinished one it will throw an error.<br />
If ''makepkg'' finishes successfully, it will place a file named ''pkgname-pkgver.pkg.tar.gz'' in your working directory. This is package that can be installed with the ''pacman -U'' command. However, just because a package file was built does not imply that it is fully functional. It might conceivably contain only the directory and no files whatsoever if, for example, a prefix was specified improperly. You can use ''pacman'''s query functions to display a list of files contained in the package and the dependencies it requires with ''pacman -Qlp [package file]'' and ''pacman -Qip [package file]'' respectively.<br />
If the package looks sane, then you are done! However, if you plan on release the ''PKGBUILD'' file, it is imperative that you check and double check the contents of the ''depends'' array. <br />
<br />
=ldd and namcap=<br />
<br />
Dependencies are the most common packaging error. There are two excellent tools you can use to check dependencies. The first one is ''ldd'', which will show you the shared library dependencies of dynamic executables:<br />
$ ldd gcc<br />
linux-gate.so.1 => (0xb7f33000)<br />
libc.so.6 => /lib/libc.so.6 (0xb7de0000)<br />
/lib/ld-linux.so.2 (0xb7f34000)<br />
<br />
The other tool is ''namcap'' which not only checks for dependencies but the overall sanity of your package. It can be used on both the ''PKGBUILD'' file and the ''pkg.tar.gz'' package. It will report any bad permissions, missing dependencies, unnecessary dependencies and other common mistakes. You can install ''namcap'' via ''pacman'':<br />
$ pacman -S namcap<br />
<br />
To use ''namcap'', simply supply a ''PKGBUILD'' file or a ''pkg.tar.gz'' package as the argument:<br />
$ namcap PKGBUILD<br />
or $ namcap pkgname.tar.gz<br />
<br />
Although ''namcap'' can help detect dependencies, it is not always correct. Verify dependencies by looking at the documentation of the software.<br />
<br />
==Testing the package==<br />
Also make sure that the package binaries actually ''run'' flawlessly! It's really annoying to release a package that contains all necessary files, but dumps core because of some obscure configuration option that doesn't quite work well with the rest of the system. If you're only going to compile packages for your own system, though, you don't need to worry too much about this quality assurance step, as you're the only person suffering from mistakes after all.<br />
<br />
=Submitting Packages to the AUR=<br />
<br />
Follow these steps to submit a package into the AUR:<br />
#Register a new account if you do not already have one.<br />
#Check all of the official repositories (''[core]'', ''[extra]'', and ''[community]'') and see if the package already exists. If it is inside any of those repositories, '''DO NOT''' submit the package. If the package is broken, file a bug report.<br />
#Check the ''[unsupported]'' repository for the package. If it is currently maintained, changes can be submitted in a comment for the maintaner's attention. If it is unmaintained, the package can be adopted and updated.<br />
#To upload the package to the AUR, the directory containing the ''PKGBUILD'' file and any other required files must be compressed as a tarball. The archive name should contain the name of the package, e.g. ''foo.tar.gz.''. You can easily build a tarball by using ''makepkg --source'' in the directory. This makes a tarball named ''pkgname-pkver-pkrel.src.tar.gz'', which you can then upload to the AUR. The tarball '''cannot''' contain the binary tarball created by ''makepkg'' or the source tarball of the software. Packages that contain binaries or that are very poorly written will be deleted without warning.<br />
#Click the '''Submit''' link by the menu in the AUR. Choose the appropriate category for your package and upload.<br />
<br />
=Summary=<br />
#Download the source tarball of the software you want to package.<br />
#Try compiling the package and installing it into an arbitrary directory.<br />
#Copy over the prototype ''/usr/share/pacman/PKGBUILD.proto'' and rename it to ''PKGBUILD'' in a temporary working directory - preferably ''~/abs/''.<br />
#Edit the ''PKGBUILD'' according to the needs of your package.<br />
#Run ''makepkg'' and see whether the resulting package is built correctly.<br />
#If not, repeat the last two steps.<br />
<br />
==Warnings==<br />
* Before you can automate the package building process, you should have done it manually at least once unless you know ''exactly'' what you're doing ''in advance'', in which case you would not be reading this in the first place. Unfortunately, although a good bunch of program authors stick to the 3-step build cycle of "./configure; make; make install", this is not always the case, and things can get real ugly if you have to apply patches to make everything work at all. Rule of thumb: If you can't get the program to compile from the source tarball, and make it install itself to a defined, temporary subdirectory, you don't even need to try packaging it. There isn't any magic pixie dust in <code>makepkg</code> that makes source problems go away.<br />
* In a few cases, the packages are not even available as source and you have to use something like <code>sh installer.run</code> to get it to work. You will have to do quite a bit of research (read READMEs, INSTALL instructions, man pages, perhaps ebuilds from gentoo or other package installers, possibly even the MAKEFILEs or source code) to get it working. In some really bad cases, you have to edit the source files to get it to work at all. However, <code>makepkg</code> needs to be completely autonomous, with no user input. Therefore if you need to edit the Makefiles, you may have to bundle a custom patch with the <code>PKGBUILD</code> and install it from inside the <code>build()</code> function, or you might have to issue some <code>sed</code> commands from inside the <code>build()</code> function.<br />
<br />
=See also=<br />
* [[ABS]] The Arch Build System<br />
* [[Arch CVS & SVN PKGBUILD guidelines]]<br />
* [[ArchLinux User-community Repository (AUR)]]<br />
* [[Kernel Compilation with ABS]]<br />
* [[Makepkg]]<br />
* [[Safe Cflags]]<br />
* [[PKGBUILD Tricks]]</div>Bhobbithttps://wiki.archlinux.org/index.php?title=PKGBUILD&diff=85178PKGBUILD2009-11-26T00:14:14Z<p>Bhobbit: Added info on variables from Building Packages in Arch Linux</p>
<hr />
<div>=Variables=<br />
<br />
The following are variables that can be filled out in the ''PKGBUILD'' file:<br />
* '''''pkgname'''''<br />
** The name of the package. It should consist of '''alphanumeric characters only''' and all letters should be '''lowercase'''. For the sake of consistency, ''pkgname'' should match the name of the source tarball of the software you are packaging. For instance, if the software is in ''foobar-2.5.tar.gz'', the ''pkgname'' value should be ''foobar''. The present working directory the ''PKGBUILD'' file is in should also match the ''pkgname''.<br />
<br />
* '''''pkgver'''''<br />
** The version of the package. The value should be the same as the version released by the author of the package. It can contain letters, numbers and periods but '''CANNOT''' contain a hyphen. If the author of the package uses a hyphen in their version numbering scheme, replace it with an underscore. For instance, if the version is ''0.99-10'', it should be changed to ''0.99_10''. <br />
<br />
* '''''pkgrel'''''<br />
** The release number of the package specific to Arch Linux. This value allows users to differentiate between consecutive builds of the same version of a package. When a new package version is first released, the '''release number starts at 1'''. As fixes and optimizations are made to the ''PKGBUILD'' file, the package will be '''re-released''' and the '''release number''' will increment by 1. When a new version of the package comes out, the release number resets to 1.<br />
<br />
* '''''pkgdesc'''''<br />
** The description of the package. The description should be about 80 character or less and should not include the package name in a self-referencing way. For instance, "Nedit is a text editor for X11" should be written as "A text editor for X11."<br />
<br />
* '''''arch'''''<br />
** An array of architectures that the ''PKGBUILD'' file is known to build and work on. Currently, it should contain '''i686''' and/or '''x86_64''', arch=('i686' 'x86_64'). The value '''any''' can also be used for independent packages, but the official repositories of Arch does not support this value. You can access this value with the variable <code>$CARCH</code> during the build.<br />
<br />
* '''''url'''''<br />
** The URL of the official site of the software being packaged.<br />
* '''''license'''''<br />
** The license under which the software is distributed. A ''licenses'' package has been created in ''[core]'' that stores common licenses in ''/usr/share/licenses/common'', i.e. ''/usr/share/licenses/common/GPL''. If a package is licensed under one of these licenses, the value should be set to the directory name, e.g. ''license=('GPL')''. If the appropriate license is not included in the official ''licenses'' package, several things must be done:<br />
**# The license file(s) should be included in: ''/usr/share/licenses/'''pkgname'''/'', e.g. ''/usr/share/licenses/foobar/LICENSE''.<br />
**# If the source tarball does '''NOT''' contain the license details and the license is only displayed elsewhere, e.g. a website, then you need to copy the license to a file and include it.<br />
**# Add '''custom''' to the ''licenses'' array. Optionally, you can replace '''custom''' with '''custom:name of license'''. Once a license is used in two or more packages in an official repository (including ''[community]''), it becomes a part of the ''licenses'' package.<br />
** The [[Wikipedia:BSD_License|BSD]], [[Wikipedia:MIT_License|MIT]], [[Wikipedia:ZLIB_license|zlib/png]] and [[Wikipedia:Python_License|Python]] licenses are special cases and could not be included in the ''licenses'' package. For the sake of the ''license'' array, it is treated as a common license (''license=('BSD')'', ''license=('MIT')'', ''license=('ZLIB')'' and ''license=('Python')'') but technically each one is a custom license because each one has its own copyright line. Any packages licensed under these four should have its own unique license stored in ''/usr/share/licenses/'''pkgname'''''. Some packages may not be covered by a single license. In these cases, multiple entries may be made in the license array, e.g. ''license=('GPL' 'custom:name of license')''.<br />
** Additionally, the (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:<br />
*** (L)GPL - (L)GPLv2 or any later version<br />
*** (L)GPL2 - (L)GPL2 only<br />
*** (L)GPL3 - (L)GPL3 or any later version<br />
<br />
* '''''groups'''''<br />
** The group the package belongs in. For instance, when you install the ''kdebase'' package, it installs all packages that belongs in the ''kde'' group.<br />
<br />
* '''''depends'''''<br />
** An array of package names that must be installed before this software can be run. If a software requires a minimum version of a dependency, the '''>=''' operator should be used to point this out, e.g. ''depends=('foobar>=1.8.0')''. You do not need to list packages that your software depends on if other packages your software depends on already have those packages listed in their dependency. For instance, ''gtk2'' depends on ''glib2'' and ''glibc''. However, ''glibc'' does not need to be listed as a dependency for ''gtk2'' because it is a dependency for ''glib2''.<br />
<br />
* '''''makedepends'''''<br />
** An array of package names that must be installed to build the software but unnecessary for using the software after installation. You can specify the minimum version dependency of the packages in the same format as the ''depends'' array.<br />
<br />
{{Warning | The "base" group is assumed already installed in all Arch setups . The group "base-devel" is assumed already installed when building with makepkg . Members of "base" or "base-devel" '''should not''' be included in (make)depends arrays.}}<br />
<br />
* '''''optdepends'''''<br />
** An array of package names that are not needed for the software to function but provides additional features. A short description of what each package provides should also be noted. An ''optdepends'' may look like this:<br />
optdepends=('cups: printing support'<br />
'sane: scanners support'<br />
'libgphoto2: digital cameras support'<br />
'alsa-lib: sound support'<br />
'giflib: GIF images support'<br />
'libjpeg: JPEG images support'<br />
'libpng: PNG images support')<br />
<br />
* '''''provides'''''<br />
** An array of package names that this package provies the features of (or a virtual package such as ''cron'' or ''sh''). If you use this variable, you should add the version (''pkgver'' and perhaps the ''pkgrel'') that this package will provide if dependencies may be affected by it. For instance, if you are providing a modified ''qt'' package named ''qt-foobar'' version 3.3.8 which provides ''qt'' then the ''provides'' array should look like ''provides=('qt=3.3.8')''. Putting ''provides=('qt')'' will cause to fail those dependencies that require a specific version of ''qt''. Do not add pkgname to your provides array, this is done automatically.<br />
{{ Note | This functionality is slightly broken in pacman 3.1.0 and will be fixed in 3.1.1. This documentation refers to the 3.1.1 syntax which will soon be in use.}}<br />
<br />
* '''''conflicts'''''<br />
** An array of package names that may cause problems with this package if installed. You can also specify the version properties of the conflicting packages in the same format as the ''depends'' array.<br />
* '''''replaces'''''<br />
** An array of obsolete package name that are replaced by this package, e.g. ''replaces=('ethereal')'' for the ''wireshark'' package. After syncing with ''pacman -Sy'', it will immediately replace an installed package upon encountering another package with the matching ''replaces'' in the repositories. If you are providing an alternate version of an already existing package, use the ''conflicts'' variable which is only evaluated when actually installing the conflicting package.<br />
<br />
* '''''backup'''''<br />
** An array of files to be backed up as ''file.pacsave'' when the package is removed. This is commonly used for packages placing configuration files in ''/etc''. The file paths in this array should be relative paths (e.g. etc/pacman.conf) not absolute paths (e.g. /etc/pacman.conf).<br />
<br />
* '''''options'''''<br />
** This array allows you to override some of the default behavior of ''makepkg''. To set an option, include the option name in the array. To reverse the default behavior, place an '''!''' at the front of the option. The following options may be placed in the array:<br />
*** '''''strip''''' - Strips symbols from binaries and libraries.<br />
*** '''''docs''''' - Save ''/doc'' directories.<br />
*** '''''libtool''''' - Leave ''libtool'' (.la) files in packages.<br />
*** '''''emptydirs''''' - Leave empty directories in packages.<br />
*** '''''zipman''''' - Compress ''man'' and ''info'' pages with ''gzip''.<br />
*** '''''ccache''''' - Allow the use of ''ccache'' during build. More useful in its negative form ''!ccache'' with select packages that have problems building with ''ccache''.<br />
*** '''''distcc''''' - Allow the use of ''distcc'' during build. More useful in its negative form ''!distcc'' with select packages that have problems building with ''distcc''.<br />
*** '''''makeflags''''' - Allow the use of user-specific ''makeflags'' during build. More useful in its negative form ''!makeflags'' with select packages that have problems building with custom ''makeflags''.<br />
*** '''''force''''' - Force the package to be upgraded by a ''pacman'' system upgrade operation, even if the version number would normally not trigger such an upgrade. This is useful when the version numbering scheme of a package changes (or is alphanumeric).<br />
<br />
* '''''install'''''<br />
** The name of the ''.install'' script to be included in the package. ''pacman'' has the ability to store and execute a package-specific script when it installs, removes or upgrades a package. The script contains the following functions which run at different times:<br />
*** '''''pre_install''''' - The script is run right before files are extracted. One argument is passed: new package version.<br />
*** '''''post_install''''' - The script is run right after files are extracted. One argument is passed: new package version.<br />
*** '''''pre_upgrade''''' - The script is run right before files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
*** '''''post_upgrade''''' - The script is run after files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
*** '''''pre_remove''''' - The script is run right before files are removed. One argument is passed: old package version.<br />
*** '''''post_remove''''' - The script is run right after files are removed. One argument is passed: old package version.<br />
** {{ Note | A prototype ''.install'' is provided at ''/usr/share/pacman/proto.install''. }}<br />
<br />
* '''''source'''''<br />
** An array of files which are needed to build the package. It must contain the location of the software source, which in most cases is a full HTTP or FTP URL. The previously set variables ''pkgname'' and ''pkgver'' can be used effectively here:<br />
*** <pre>source=(http://example.com/$pkgname-$pkgver.tar.gz)</pre><br />
** If you need to supply which are not downloadable on the fly, e.g. self-made patches, you simply put those into the same directory where your ''PKGBUILD'' file is in and add the filename to this array. Any paths you add here are resolved relative to the directory where the ''PKGBUILD'' lies. Before the actual build process is started, all of the files referenced in this array will be downloaded or checked for existence, and ''makepkg'' will not proceed if any are missing.<br />
<br />
* '''''noextract'''''<br />
** An array of files listed under the ''source'' array which should not be extracted from their archive format by ''makepkg''. This most commonly applies to certain zip files which cannot be handled by ''bsdtar'' because ''libarchive'' processes all files as streams rather than random access as ''unzip'' does. In these situations ''unzip'' should be added in the ''makedepends'' array and the first line of the ''build()'' function should contain:<br />
<pre><br />
cd $srcdir/$pkgname-$pkgver<br />
unzip [source].zip<br />
</pre><br />
<br />
* '''''md5sums'''''<br />
** An array of md5 checksums of the files listed in the ''source'' array. Once all files in the ''source'' array are available, an md5 hash of each file will be automatically generated and compared with the values of this array in the same order they appear in the ''source'' array. While the order of the source files itself does not matter, it is important that it matches the order of this array since ''makepkg'' cannot guess which md5sum belongs to what source file. You can generate this array quickly and easily using the command ''makepkg -g'' in the directory that contains the ''PKGBUILD'' file.<br />
<br />
It is common practice to preserve the order of the ''PKGBUILD'' variables as shown above. However, this is not mandatory, as the only requirement in this context is correct [[Wikipedia:Bash|Bash]] syntax.</div>Bhobbithttps://wiki.archlinux.org/index.php?title=PKGBUILD&diff=85175PKGBUILD2009-11-26T00:07:06Z<p>Bhobbit: moved PKGBUILD to PKGBUILD Variables:&#32;The purpose of PKBUILD files is discussed in Building Packages in Arch Linux, however the listing of all the variables makes that page bulky.</p>
<hr />
<div>#REDIRECT [[Making packages in Arch]]</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Creating_packages&diff=85173Creating packages2009-11-25T23:58:41Z<p>Bhobbit: Merged info from Making Packages in Arch</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:Package development (English)]]<br />
[[Category:Guidelines (English)]]<br />
<br />
=Introduction=<br />
All information for creating a package is placed in a <code>PKGBUILD</code> file. When you run <code>makepkg</code>, it will look for a <code>PKGBUILD</code> file in the current working directory, and compile the software's source code according to the instructions in the <code>PKGBUILD</code> file. After successfully finishing the compilation, the resulting binaries, as well as all available meta-information like package version and dependencies, are packed in the <code>name.pkg.tar.gz</code> package file that can be cleanly installed with <code>pacman -U <package file></code>.<br />
<br />
=Setting Up=<br />
<br />
First, verify that you have the necessary tools installed. You need the following packages:<br />
*'''base-devel''' (a package group): Contains ''make'' and additional tools for compiling from the source.<br />
*'''fakeroot''' (part of 'base-devel'): Allows a normal user the necessary root permissions to create packages in the build environment without being able to alter the wider system. If the build process attempts to alter files outside of the build environment, errors are produced and the build fails. This is very useful for checking the quality, safety and integrity of the packages for distribution.<br />
*'''abs''': [[ABS|Arch Build System]]. The abs package will install all of the PKGBUILDs and local source files needed to rebuild the binary packages in the official Arch Linux repositories. You do not need abs to use makepkg and you should only install abs if you intend to rebuild man packages in the ABS tree. If you only need a few PKGBUILDs, you can retrieve the latest versions from the web interface directly or via other available tools such as [http://xyne.archlinux.ca/info/pbget pbget]<br />
<br />
If you do not have them, install them using ''pacman'':<br />
# pacman -S abs base-devel fakeroot<br />
<br />
One of the key tools for building packages is ''makepkg''. It does the following:<br />
#Checks if package dependencies are installed.<br />
#Downloads the source file(s) from the specified server(s).<br />
#Unpacks the source file(s).<br />
#Compiles the software and installs it under a fakeroot environment.<br />
#Strips symbols from binaries and libraries.<br />
#Generates the package meta file which is included with each package.<br />
#Compress the fakeroot environment into a package file.<br />
#Stores the package file in the configured destination directory, which is the present working directory by default.<br />
<br />
''abs'' is optional to use, but it gives you the option to build official packages directly from source instead of downloading the pre-built, binary copy. It also helps you keep all of your ''PKGBUILD'' files, both official and unofficial in a centralized location. A ''PKGBUILD'' file contains metadata about a package, and is the essential component for building packages. You can specify which repositories to include in your ABS tree in the ''/etc/abs.conf'' file. To obtain the ABS tree which contains all of the ''PKGBUILD'' files, just run the ''abs'' command as root:<br />
# abs<br />
Create an ABS build directory under the /home of your non-root user, if you have not done so already: <br />
$ mkdir ~/abs<br />
<br />
= Package file =<br />
<br />
ABS automatically downloads the source code for the particular software you are compiling. It then unpacks, compiles the sources and squeezes everything into an installable package.<br />
Typically, the resulting package file is a file called ''foo''.pkg.tar.gz. <br />
<br />
In fact, it is no more than a gzipped tar archive or 'tarball' which contains:<br />
<br />
* The files to install<br />
<br />
*.PKGINFO: contains all the metadata needed by pacman to deal with packages, dependencies, etc.<br />
<br />
*.FILELIST: lists all the files of the archive. It's used in order to uninstall the software or to check for file conflicts. (Obsolete now; used for pacman-2.x)<br />
<br />
*.INSTALL: a file used to execute commands after the install/upgrade/remove stage. (This file is present only if specified in the PKGBUILD.)<br />
<br />
Since pacman manages tar.gz packages, foo.pkg.tar.gz can now easily be installed/removed.<br />
<br />
=Preparing the Files=<br />
<br />
Now download the source tarball of the software you want to package, extract it, and note all commands needed to compile and install it. You will be repeating the same commands in the ''PKGBUILD'' file. Most software authors stick to the 3-step build cycle:<br />
./configure<br />
make<br />
make install<br />
When you run ''makepkg'', it will look for a ''PKGBUILD'' file in the present working directory. If a ''PKGBUILD'' file is found it will download the software's source code and compile it according to the instructions specified in the ''PKGBUILD'' file. The instructions must be fully interpretable by [[Wikipedia:Bash|Bash]]. After successful compilation, the resulting binaries and metadata of the package, i.e. package version and dependencies, are packed in a ''pkgname.pkg.tar.gz'' package file that can be cleanly installed with ''pacman -U [package file]''.<br />
To start out with a new package, you should first create an empty working directory, preferably named ''~/abs/'''pkgname'''''. Once you make the directory and change into it, create a ''PKGBUILD'' file to work with either by copying the prototype from ''/usr/share/pacman/PKGBUILD.proto'' or by copying a ''PKGBUILD'' from another package. The latter is quite useful if you want to modify compilation options of a package instead of creating an entirely new one.<br />
<br />
=Defining PKGBUILD Variables=<br />
The PKGBUILD file contains metadata about a package. It is a plain text file. The following is a prototype PKGBUILD. It can be found in /usr/share/pacman along with other templates.<br />
<br />
<pre><br />
# This is an example PKGBUILD file. Use this as a start to creating your own,<br />
# and remove these comments. For more information, see 'man PKGBUILD'.<br />
# Note: Please fill out the license field for your package. If it is unknown,<br />
# then please put 'unknown'.<br />
<br />
# Contributor: Your Name <youremail@domain.com><br />
pkgname=NAME<br />
pkgver=VERSION<br />
pkgrel=1<br />
pkgdesc=""<br />
arch=()<br />
url=""<br />
license=('GPL')<br />
groups=()<br />
depends=()<br />
makedepends=()<br />
provides=()<br />
conflicts=()<br />
replaces=()<br />
backup=()<br />
install=<br />
source=($pkgname-$pkgver.tar.gz)<br />
noextract=()<br />
md5sums=() #generate with 'makepkg -g'<br />
<br />
build() {<br />
cd "$srcdir/$pkgname-$pkgver"<br />
<br />
./configure --prefix=/usr<br />
make || return 1<br />
make DESTDIR="$pkgdir/" install<br />
}<br />
</pre><br />
<br />
The following are variables that can be filled out in the ''PKGBUILD'' file:<br />
* '''''pkgname'''''<br />
** The name of the package. It should consist of '''alphanumeric characters only''' and all letters should be '''lowercase'''. For the sake of consistency, ''pkgname'' should match the name of the source tarball of the software you are packaging. For instance, if the software is in ''foobar-2.5.tar.gz'', the ''pkgname'' value should be ''foobar''. The present working directory the ''PKGBUILD'' file is in should also match the ''pkgname''.<br />
<br />
* '''''pkgver'''''<br />
** The version of the package. The value should be the same as the version released by the author of the package. It can contain letters, numbers and periods but '''CANNOT''' contain a hyphen. If the author of the package uses a hyphen in their version numbering scheme, replace it with an underscore. For instance, if the version is ''0.99-10'', it should be changed to ''0.99_10''. <br />
<br />
* '''''pkgrel'''''<br />
** The release number of the package specific to Arch Linux. This value allows users to differentiate between consecutive builds of the same version of a package. When a new package version is first released, the '''release number starts at 1'''. As fixes and optimizations are made to the ''PKGBUILD'' file, the package will be '''re-released''' and the '''release number''' will increment by 1. When a new version of the package comes out, the release number resets to 1.<br />
<br />
* '''''pkgdesc'''''<br />
** The description of the package. The description should be about 80 character or less and should not include the package name in a self-referencing way. For instance, "Nedit is a text editor for X11" should be written as "A text editor for X11."<br />
<br />
* '''''arch'''''<br />
** An array of architectures that the ''PKGBUILD'' file is known to build and work on. Currently, it should contain '''i686''' and/or '''x86_64''', arch=('i686' 'x86_64'). The value '''any''' can also be used for independent packages, but the official repositories of Arch does not support this value. You can access this value with the variable <code>$CARCH</code> during the build.<br />
<br />
* '''''url'''''<br />
** The URL of the official site of the software being packaged.<br />
* '''''license'''''<br />
** The license under which the software is distributed. A ''licenses'' package has been created in ''[core]'' that stores common licenses in ''/usr/share/licenses/common'', i.e. ''/usr/share/licenses/common/GPL''. If a package is licensed under one of these licenses, the value should be set to the directory name, e.g. ''license=('GPL')''. If the appropriate license is not included in the official ''licenses'' package, several things must be done:<br />
**# The license file(s) should be included in: ''/usr/share/licenses/'''pkgname'''/'', e.g. ''/usr/share/licenses/foobar/LICENSE''.<br />
**# If the source tarball does '''NOT''' contain the license details and the license is only displayed elsewhere, e.g. a website, then you need to copy the license to a file and include it.<br />
**# Add '''custom''' to the ''licenses'' array. Optionally, you can replace '''custom''' with '''custom:name of license'''. Once a license is used in two or more packages in an official repository (including ''[community]''), it becomes a part of the ''licenses'' package.<br />
** The [[Wikipedia:BSD_License|BSD]], [[Wikipedia:MIT_License|MIT]], [[Wikipedia:ZLIB_license|zlib/png]] and [[Wikipedia:Python_License|Python]] licenses are special cases and could not be included in the ''licenses'' package. For the sake of the ''license'' array, it is treated as a common license (''license=('BSD')'', ''license=('MIT')'', ''license=('ZLIB')'' and ''license=('Python')'') but technically each one is a custom license because each one has its own copyright line. Any packages licensed under these four should have its own unique license stored in ''/usr/share/licenses/'''pkgname'''''. Some packages may not be covered by a single license. In these cases, multiple entries may be made in the license array, e.g. ''license=('GPL' 'custom:name of license')''.<br />
** Additionally, the (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:<br />
*** (L)GPL - (L)GPLv2 or any later version<br />
*** (L)GPL2 - (L)GPL2 only<br />
*** (L)GPL3 - (L)GPL3 or any later version<br />
<br />
* '''''groups'''''<br />
** The group the package belongs in. For instance, when you install the ''kdebase'' package, it installs all packages that belongs in the ''kde'' group.<br />
<br />
* '''''depends'''''<br />
** An array of package names that must be installed before this software can be run. If a software requires a minimum version of a dependency, the '''>=''' operator should be used to point this out, e.g. ''depends=('foobar>=1.8.0')''. You do not need to list packages that your software depends on if other packages your software depends on already have those packages listed in their dependency. For instance, ''gtk2'' depends on ''glib2'' and ''glibc''. However, ''glibc'' does not need to be listed as a dependency for ''gtk2'' because it is a dependency for ''glib2''.<br />
<br />
* '''''makedepends'''''<br />
** An array of package names that must be installed to build the software but unnecessary for using the software after installation. You can specify the minimum version dependency of the packages in the same format as the ''depends'' array.<br />
<br />
{{Warning | The "base" group is assumed already installed in all Arch setups . The group "base-devel" is assumed already installed when building with makepkg . Members of "base" or "base-devel" '''should not''' be included in (make)depends arrays.}}<br />
<br />
* '''''optdepends'''''<br />
** An array of package names that are not needed for the software to function but provides additional features. A short description of what each package provides should also be noted. An ''optdepends'' may look like this:<br />
optdepends=('cups: printing support'<br />
'sane: scanners support'<br />
'libgphoto2: digital cameras support'<br />
'alsa-lib: sound support'<br />
'giflib: GIF images support'<br />
'libjpeg: JPEG images support'<br />
'libpng: PNG images support')<br />
<br />
* '''''provides'''''<br />
** An array of package names that this package provies the features of (or a virtual package such as ''cron'' or ''sh''). If you use this variable, you should add the version (''pkgver'' and perhaps the ''pkgrel'') that this package will provide if dependencies may be affected by it. For instance, if you are providing a modified ''qt'' package named ''qt-foobar'' version 3.3.8 which provides ''qt'' then the ''provides'' array should look like ''provides=('qt=3.3.8')''. Putting ''provides=('qt')'' will cause to fail those dependencies that require a specific version of ''qt''. Do not add pkgname to your provides array, this is done automatically.<br />
{{ Note | This functionality is slightly broken in pacman 3.1.0 and will be fixed in 3.1.1. This documentation refers to the 3.1.1 syntax which will soon be in use.}}<br />
<br />
* '''''conflicts'''''<br />
** An array of package names that may cause problems with this package if installed. You can also specify the version properties of the conflicting packages in the same format as the ''depends'' array.<br />
* '''''replaces'''''<br />
** An array of obsolete package name that are replaced by this package, e.g. ''replaces=('ethereal')'' for the ''wireshark'' package. After syncing with ''pacman -Sy'', it will immediately replace an installed package upon encountering another package with the matching ''replaces'' in the repositories. If you are providing an alternate version of an already existing package, use the ''conflicts'' variable which is only evaluated when actually installing the conflicting package.<br />
<br />
* '''''backup'''''<br />
** An array of files to be backed up as ''file.pacsave'' when the package is removed. This is commonly used for packages placing configuration files in ''/etc''. The file paths in this array should be relative paths (e.g. etc/pacman.conf) not absolute paths (e.g. /etc/pacman.conf).<br />
<br />
* '''''options'''''<br />
** This array allows you to override some of the default behavior of ''makepkg''. To set an option, include the option name in the array. To reverse the default behavior, place an '''!''' at the front of the option. The following options may be placed in the array:<br />
*** '''''strip''''' - Strips symbols from binaries and libraries.<br />
*** '''''docs''''' - Save ''/doc'' directories.<br />
*** '''''libtool''''' - Leave ''libtool'' (.la) files in packages.<br />
*** '''''emptydirs''''' - Leave empty directories in packages.<br />
*** '''''zipman''''' - Compress ''man'' and ''info'' pages with ''gzip''.<br />
*** '''''ccache''''' - Allow the use of ''ccache'' during build. More useful in its negative form ''!ccache'' with select packages that have problems building with ''ccache''.<br />
*** '''''distcc''''' - Allow the use of ''distcc'' during build. More useful in its negative form ''!distcc'' with select packages that have problems building with ''distcc''.<br />
*** '''''makeflags''''' - Allow the use of user-specific ''makeflags'' during build. More useful in its negative form ''!makeflags'' with select packages that have problems building with custom ''makeflags''.<br />
*** '''''force''''' - Force the package to be upgraded by a ''pacman'' system upgrade operation, even if the version number would normally not trigger such an upgrade. This is useful when the version numbering scheme of a package changes (or is alphanumeric).<br />
<br />
* '''''install'''''<br />
** The name of the ''.install'' script to be included in the package. ''pacman'' has the ability to store and execute a package-specific script when it installs, removes or upgrades a package. The script contains the following functions which run at different times:<br />
*** '''''pre_install''''' - The script is run right before files are extracted. One argument is passed: new package version.<br />
*** '''''post_install''''' - The script is run right after files are extracted. One argument is passed: new package version.<br />
*** '''''pre_upgrade''''' - The script is run right before files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
*** '''''post_upgrade''''' - The script is run after files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
*** '''''pre_remove''''' - The script is run right before files are removed. One argument is passed: old package version.<br />
*** '''''post_remove''''' - The script is run right after files are removed. One argument is passed: old package version.<br />
** {{ Note | A prototype ''.install'' is provided at ''/usr/share/pacman/proto.install''. }}<br />
<br />
* '''''source'''''<br />
** An array of files which are needed to build the package. It must contain the location of the software source, which in most cases is a full HTTP or FTP URL. The previously set variables ''pkgname'' and ''pkgver'' can be used effectively here:<br />
*** <pre>source=(http://example.com/$pkgname-$pkgver.tar.gz)</pre><br />
** If you need to supply which are not downloadable on the fly, e.g. self-made patches, you simply put those into the same directory where your ''PKGBUILD'' file is in and add the filename to this array. Any paths you add here are resolved relative to the directory where the ''PKGBUILD'' lies. Before the actual build process is started, all of the files referenced in this array will be downloaded or checked for existence, and ''makepkg'' will not proceed if any are missing.<br />
<br />
* '''''noextract'''''<br />
** An array of files listed under the ''source'' array which should not be extracted from their archive format by ''makepkg''. This most commonly applies to certain zip files which cannot be handled by ''bsdtar'' because ''libarchive'' processes all files as streams rather than random access as ''unzip'' does. In these situations ''unzip'' should be added in the ''makedepends'' array and the first line of the ''build()'' function should contain:<br />
<pre><br />
cd $srcdir/$pkgname-$pkgver<br />
unzip [source].zip<br />
</pre><br />
<br />
* '''''md5sums'''''<br />
** An array of md5 checksums of the files listed in the ''source'' array. Once all files in the ''source'' array are available, an md5 hash of each file will be automatically generated and compared with the values of this array in the same order they appear in the ''source'' array. While the order of the source files itself does not matter, it is important that it matches the order of this array since ''makepkg'' cannot guess which md5sum belongs to what source file. You can generate this array quickly and easily using the command ''makepkg -g'' in the directory that contains the ''PKGBUILD'' file.<br />
<br />
It is common practice to preserve the order of the ''PKGBUILD'' variables as shown above. However, this is not mandatory, as the only requirement in this context is correct [[Wikipedia:Bash|Bash]] syntax.<br />
<br />
=The build() function=<br />
<br />
Now you need to implement the ''build()'' function in the ''PKGBUILD'' file. This function uses common shell commands in the [http://en.wikipedia.org/wiki/Bash Bash] syntax to automatically compile software and create a ''pkg/'' directory to install the software to. This allows ''makepkg'' to pack it up without having to pick all the necessary files from your actual filesystem.<br />
The first step in the ''build()'' function is to change into the directory created by uncompressing the source tarball. In most common cases the first command will look like this:<br />
cd $srcdir/$pkgname-$pkgver<br />
<br />
Now, you need to list the same commands you used when you manually compiled the software. The ''build()'' function in essence automates everything you did by hand and compiles the software in the fakeroot build environment. If the software you are packaging uses a configure script, it is good practice to use ''--prefix=/usr'' when building packages for ''pacman''. A lot of software install their files relative to the ''/usr/local'' directory, which should only be done if you are manually building from source. All Arch Linux packages should use the ''/usr'' directory. As seen in the ''/usr/share/pacman/PKGBUILD.proto'' file, the next two lines should look like this:<br />
./configure --prefix=/usr<br />
make || return 1<br />
<br />
The final step in the ''build()'' funciton is to put the compiled files in a directory where ''makepkg'' can retrieve to create a package. This by default is the ''pkg/'' directory - a simple fakeroot environment. It imitates the root of your filesystem to the software's installation procedure. If you have to manually install files under the root of your filesystem, you should instead install it in the ''pkg/'' directory under the same directory structure, e.g. if you want to install a file to ''/usr/bin'', it should instead be placed under ''$pkgdir/usr/bin''. Very few software require the user to copy dozens of files manually, and you usually will not have to worry about this. Instead, for most software you will have to call ''make install''. The final line should look like the following in order to correctly install the software in the ''pkg/'' directory:<br />
make DESTDIR=$pkgdir install || return 1<br />
<br />
'''Note''': It is sometimes the case where <code>DESTDIR</code> is not used in the <code>Makefile</code>; you may need to use <code>prefix</code> instead. If the package is built with autoconf/automake, use <code>DESTDIR</code>; this is what is [http://sources.redhat.com/automake/automake.html#Install documented] in the manuals. If <code>DESTDIR</code> does not work, try building with <code>make prefix="$pkgdir/usr/" install</code>. If that does not work, you'll have to look further into the install commands that are executed by "<code>make <...> install</code>".<br />
<br />
In some odd cases, the software expects to be run from a single directory. In such cases it is wise to simply copy these to ''$pkgdir/opt''.<br />
More often than not the installation process of the software will create any subdirectories below the ''pkg/'' directory. If it does not, however, ''makepkg'' will generate a lot of errors and you will need to manually create subdirectories by adding the appropriate ''mkdir -p'' commands in the ''build()'' function before the installation procedure is run.<br />
Also, ''makepkg'' defines three variables that you should use as part of the build and install process:<br />
*'''''startdir''''' - This contains the absolute path to the directory where the ''PKGBUILD'' file is located, which is the present working directory. This variable is almost always used in combination with ''/src'' or ''/pkg'' postfixes, but the use of ''srcdir'' and ''pkgdir'' variables is preferred.<br />
*'''''srcdir''''' - This points to the directory where ''makepkg'' extracts or copies all source files. It is currently an alias for ''$startdir/src''.<br />
*'''''pkgdir''''' - This points to the directory where ''makepkg'' bundles the installed package, which becomes the root directory of your built package. It is currently an alias for ''$startdir/pkg''.<br />
<br />
'''Note:''' makepkg, and thus the build() function, is intended to be non-interactive. Interactive utilities or scripts called in the build() function may break makepkg, particularly if it is invoked with build-logging enabled (-l). (see [http://bugs.archlinux.org/task/13214 Arch Linux Bug #13214].)<br />
<br />
=Additional Guidelines=<br />
<br />
Here are some additional guidelines that you should adhere to:<br />
*All elements in an array variable '''must be separated by spaces'''.<br />
*If possible, remove empty lines from the ''PKGBUILD'' including fields that have empty values.<br />
*Wherever possible, use ''|| return 1'' for critical build functions: make || return 1 make DESTDIR=$pkgdir install || return 1 <br />
*'''Do not introduce new variables''' into your ''PKGBUILD'' file unless the package cannot be built without doing so, as these could possibly conflict with variables used in ''makepkg'' itself. If a new variable is absolutely required, '''prefix the variable name with an underscore''': _customvariable= <br />
*'''Avoid''' using ''/usr/libexec/'' for anything. Use ''/usr/lib/pkgname'' instead.<br />
*The ''packager'' field from the package meta file can be customized by the package builder by modifying the appropriate option in the ''/etc/makepkg.conf'' file, or alternatively by exporting the ''PACKAGER'' environment variable before building packages with ''makepkg'': # export PACKAGER="Your Name &lt;email@domain.com&gt;" <br />
* '''Configuration files''' should be placed in the ''/etc'' directory. If there is more than one configuration file, it is customary to use a subdirectory in order to keep the ''/etc'' area as clean as possible. Use ''/etc/'''pkgname''''' or a suitable alternative, e.g., [http://httpd.apache.org/ Apache] uses ''/etc/httpd/''. <br />
*Package files should follow these '''general directory guidelines''': <br />
**''/etc/'' - System essential configuration files<br />
**''/usr/bin'' - Application binaries<br />
**''/usr/sbin'' - System binaries<br />
**''/usr/lib'' - Libraries<br />
**''/usr/include'' - Header files<br />
**''/usr/lib/pkgname'' - Modules, plugins, etc.<br />
**''/usr/share/man'' - Manpages<br />
**''/usr/share/pkgname'' - Application data<br />
**''/usr/share/licenses/pkgname'' - Package license, if not included under common<br />
**''/etc/pkgname'' - Configuration files<br />
**''/opt'' - Large self-contained packages such as Java, etc.<br />
<br />
*Packages should not contain the following directories: <br />
**''/dev''<br />
**''/home''<br />
**''/media''<br />
**''/mnt''<br />
**''/proc''<br />
**''/root''<br />
**''/selinux''<br />
**''/sys''<br />
**''/tmp''<br />
**''/var/tmp''<br />
<br />
=Testing the PKGBUILD=<br />
<br />
As you are writing the ''build()'' function, you will want to test your changes frequently to ensure there are no bugs. You can do this using the ''makepkg'' command in the directory containing the ''PKGBUILD'' file. With a properly formatted ''PKGBUILD'', this will create a package, but with a broken or unfinished one it will throw an error.<br />
If ''makepkg'' finishes successfully, it will place a file named ''pkgname-pkgver.pkg.tar.gz'' in your working directory. This is package that can be installed with the ''pacman -U'' command. However, just because a package file was built does not imply that it is fully functional. It might conceivably contain only the directory and no files whatsoever if, for example, a prefix was specified improperly. You can use ''pacman'''s query functions to display a list of files contained in the package and the dependencies it requires with ''pacman -Qlp [package file]'' and ''pacman -Qip [package file]'' respectively.<br />
If the package looks sane, then you are done! However, if you plan on release the ''PKGBUILD'' file, it is imperative that you check and double check the contents of the ''depends'' array. <br />
<br />
=ldd and namcap=<br />
<br />
Dependencies are the most common packaging error. There are two excellent tools you can use to check dependencies. The first one is ''ldd'', which will show you the shared library dependencies of dynamic executables:<br />
$ ldd gcc<br />
linux-gate.so.1 => (0xb7f33000)<br />
libc.so.6 => /lib/libc.so.6 (0xb7de0000)<br />
/lib/ld-linux.so.2 (0xb7f34000)<br />
<br />
The other tool is ''namcap'' which not only checks for dependencies but the overall sanity of your package. It can be used on both the ''PKGBUILD'' file and the ''pkg.tar.gz'' package. It will report any bad permissions, missing dependencies, unnecessary dependencies and other common mistakes. You can install ''namcap'' via ''pacman'':<br />
$ pacman -S namcap<br />
<br />
To use ''namcap'', simply supply a ''PKGBUILD'' file or a ''pkg.tar.gz'' package as the argument:<br />
$ namcap PKGBUILD<br />
or $ namcap pkgname.tar.gz<br />
<br />
Although ''namcap'' can help detect dependencies, it is not always correct. Verify dependencies by looking at the documentation of the software.<br />
<br />
==Testing the package==<br />
Also make sure that the package binaries actually ''run'' flawlessly! It's really annoying to release a package that contains all necessary files, but dumps core because of some obscure configuration option that doesn't quite work well with the rest of the system. If you're only going to compile packages for your own system, though, you don't need to worry too much about this quality assurance step, as you're the only person suffering from mistakes after all.<br />
<br />
=Submitting Packages to the AUR=<br />
<br />
Follow these steps to submit a package into the AUR:<br />
#Register a new account if you do not already have one.<br />
#Check all of the official repositories (''[core]'', ''[extra]'', and ''[community]'') and see if the package already exists. If it is inside any of those repositories, '''DO NOT''' submit the package. If the package is broken, file a bug report.<br />
#Check the ''[unsupported]'' repository for the package. If it is currently maintained, changes can be submitted in a comment for the maintaner's attention. If it is unmaintained, the package can be adopted and updated.<br />
#To upload the package to the AUR, the directory containing the ''PKGBUILD'' file and any other required files must be compressed as a tarball. The archive name should contain the name of the package, e.g. ''foo.tar.gz.''. You can easily build a tarball by using ''makepkg --source'' in the directory. This makes a tarball named ''pkgname-pkver-pkrel.src.tar.gz'', which you can then upload to the AUR. The tarball '''cannot''' contain the binary tarball created by ''makepkg'' or the source tarball of the software. Packages that contain binaries or that are very poorly written will be deleted without warning.<br />
#Click the '''Submit''' link by the menu in the AUR. Choose the appropriate category for your package and upload.<br />
<br />
=Summary=<br />
#Download the source tarball of the software you want to package.<br />
#Try compiling the package and installing it into an arbitrary directory.<br />
#Copy over the prototype ''/usr/share/pacman/PKGBUILD.proto'' and rename it to ''PKGBUILD'' in a temporary working directory - preferably ''~/abs/''.<br />
#Edit the ''PKGBUILD'' according to the needs of your package.<br />
#Run ''makepkg'' and see whether the resulting package is built correctly.<br />
#If not, repeat the last two steps.<br />
<br />
==Warnings==<br />
* Before you can automate the package building process, you should have done it manually at least once unless you know ''exactly'' what you're doing ''in advance'', in which case you would not be reading this in the first place. Unfortunately, although a good bunch of program authors stick to the 3-step build cycle of "./configure; make; make install", this is not always the case, and things can get real ugly if you have to apply patches to make everything work at all. Rule of thumb: If you can't get the program to compile from the source tarball, and make it install itself to a defined, temporary subdirectory, you don't even need to try packaging it. There isn't any magic pixie dust in <code>makepkg</code> that makes source problems go away.<br />
* In a few cases, the packages are not even available as source and you have to use something like <code>sh installer.run</code> to get it to work. You will have to do quite a bit of research (read READMEs, INSTALL instructions, man pages, perhaps ebuilds from gentoo or other package installers, possibly even the MAKEFILEs or source code) to get it working. In some really bad cases, you have to edit the source files to get it to work at all. However, <code>makepkg</code> needs to be completely autonomous, with no user input. Therefore if you need to edit the Makefiles, you may have to bundle a custom patch with the <code>PKGBUILD</code> and install it from inside the <code>build()</code> function, or you might have to issue some <code>sed</code> commands from inside the <code>build()</code> function.<br />
<br />
=See also=<br />
* [[ABS]] The Arch Build System<br />
* [[Arch CVS & SVN PKGBUILD guidelines]]<br />
* [[ArchLinux User-community Repository (AUR)]]<br />
* [[Kernel Compilation with ABS]]<br />
* [[Makepkg]]<br />
* [[Safe Cflags]]<br />
* [[PKGBUILD Tricks]]</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Creating_packages&diff=85162Creating packages2009-11-25T23:02:52Z<p>Bhobbit: Merged info from ABS PKGBUILD Explained</p>
<hr />
<div>[[Category:About Arch (English)]]<br />
[[Category:Package development (English)]]<br />
[[Category:Guidelines (English)]]<br />
=Setting Up=<br />
<br />
First, verify that you have the necessary tools installed. You need the following packages:<br />
*'''base-devel''' (a package group): Contains ''make'' and additional tools for compiling from the source.<br />
*'''fakeroot''' (part of 'base-devel'): Allows a normal user the necessary root permissions to create packages in the build environment without being able to alter the wider system. If the build process attempts to alter files outside of the build environment, errors are produced and the build fails. This is very useful for checking the quality, safety and integrity of the packages for distribution.<br />
*'''abs''': [[ABS|Arch Build System]]. The abs package will install all of the PKGBUILDs and local source files needed to rebuild the binary packages in the official Arch Linux repositories. You do not need abs to use makepkg and you should only install abs if you intend to rebuild man packages in the ABS tree. If you only need a few PKGBUILDs, you can retrieve the latest versions from the web interface directly or via other available tools such as [http://xyne.archlinux.ca/info/pbget pbget]<br />
<br />
If you do not have them, install them using ''pacman'':<br />
# pacman -S abs base-devel fakeroot<br />
<br />
One of the key tools for building packages is ''makepkg''. It does the following:<br />
#Checks if package dependencies are installed.<br />
#Downloads the source file(s) from the specified server(s).<br />
#Unpacks the source file(s).<br />
#Compiles the software and installs it under a fakeroot environment.<br />
#Strips symbols from binaries and libraries.<br />
#Generates the package meta file which is included with each package.<br />
#Compress the fakeroot environment into a package file.<br />
#Stores the package file in the configured destination directory, which is the present working directory by default.<br />
<br />
''abs'' is optional to use, but it gives you the option to build official packages directly from source instead of downloading the pre-built, binary copy. It also helps you keep all of your ''PKGBUILD'' files, both official and unofficial in a centralized location. A ''PKGBUILD'' file contains metadata about a package, and is the essential component for building packages. You can specify which repositories to include in your ABS tree in the ''/etc/abs.conf'' file. To obtain the ABS tree which contains all of the ''PKGBUILD'' files, just run the ''abs'' command as root:<br />
# abs<br />
Create an ABS build directory under the /home of your non-root user, if you have not done so already: <br />
$ mkdir ~/abs<br />
<br />
= Package file =<br />
<br />
ABS automatically downloads the source code for the particular software you are compiling. It then unpacks, compiles the sources and squeezes everything into an installable package.<br />
Typically, the resulting package file is a file called ''foo''.pkg.tar.gz. <br />
<br />
In fact, it is no more than a gzipped tar archive or 'tarball' which contains:<br />
<br />
* The files to install<br />
<br />
*.PKGINFO: contains all the metadata needed by pacman to deal with packages, dependencies, etc.<br />
<br />
*.FILELIST: lists all the files of the archive. It's used in order to uninstall the software or to check for file conflicts. (Obsolete now; used for pacman-2.x)<br />
<br />
*.INSTALL: a file used to execute commands after the install/upgrade/remove stage. (This file is present only if specified in the PKGBUILD.)<br />
<br />
Since pacman manages tar.gz packages, foo.pkg.tar.gz can now easily be installed/removed.<br />
<br />
=Preparing the Files=<br />
<br />
Now download the source tarball of the software you want to package, extract it, and note all commands needed to compile and install it. You will be repeating the same commands in the ''PKGBUILD'' file. Most software authors stick to the 3-step build cycle:<br />
./configure<br />
make<br />
make install<br />
When you run ''makepkg'', it will look for a ''PKGBUILD'' file in the present working directory. If a ''PKGBUILD'' file is found it will download the software's source code and compile it according to the instructions specified in the ''PKGBUILD'' file. The instructions must be fully interpretable by [[Wikipedia:Bash|Bash]]. After successful compilation, the resulting binaries and metadata of the package, i.e. package version and dependencies, are packed in a ''pkgname.pkg.tar.gz'' package file that can be cleanly installed with ''pacman -U [package file]''.<br />
To start out with a new package, you should first create an empty working directory, preferably named ''~/abs/'''pkgname'''''. Once you make the directory and change into it, create a ''PKGBUILD'' file to work with either by copying the prototype from ''/usr/share/pacman/PKGBUILD.proto'' or by copying a ''PKGBUILD'' from another package. The latter is quite useful if you want to modify compilation options of a package instead of creating an entirely new one.<br />
<br />
=Defining PKGBUILD Variables=<br />
The PKGBUILD file contains metadata about a package. It is a plain text file. The following is a prototype PKGBUILD. It can be found in /usr/share/pacman along with other templates.<br />
<br />
<pre><br />
# This is an example PKGBUILD file. Use this as a start to creating your own,<br />
# and remove these comments. For more information, see 'man PKGBUILD'.<br />
# Note: Please fill out the license field for your package. If it is unknown,<br />
# then please put 'unknown'.<br />
<br />
# Contributor: Your Name <youremail@domain.com><br />
pkgname=NAME<br />
pkgver=VERSION<br />
pkgrel=1<br />
pkgdesc=""<br />
arch=()<br />
url=""<br />
license=('GPL')<br />
groups=()<br />
depends=()<br />
makedepends=()<br />
provides=()<br />
conflicts=()<br />
replaces=()<br />
backup=()<br />
install=<br />
source=($pkgname-$pkgver.tar.gz)<br />
noextract=()<br />
md5sums=() #generate with 'makepkg -g'<br />
<br />
build() {<br />
cd "$srcdir/$pkgname-$pkgver"<br />
<br />
./configure --prefix=/usr<br />
make || return 1<br />
make DESTDIR="$pkgdir/" install<br />
}<br />
</pre><br />
<br />
The following are variables that can be filled out in the ''PKGBUILD'' file:<br />
* '''''pkgname'''''<br />
** The name of the package. It should consist of '''alphanumeric characters only''' and all letters should be '''lowercase'''. For the sake of consistency, ''pkgname'' should match the name of the source tarball of the software you are packaging. For instance, if the software is in ''foobar-2.5.tar.gz'', the ''pkgname'' value should be ''foobar''. The present working directory the ''PKGBUILD'' file is in should also match the ''pkgname''.<br />
* '''''pkgver'''''<br />
** The version of the package. The value should be the same as the version released by the author of the package. It can contain letters, numbers and periods but '''CANNOT''' contain a hyphen. If the author of the package uses a hyphen in their version numbering scheme, replace it with an underscore. For instance, if the version is ''0.99-10'', it should be changed to ''0.99_10''.<br />
* '''''pkgrel'''''<br />
** The release number of the package specific to Arch Linux. This value allows users to differentiate between consecutive builds of the same version of a package. When a new package version is first released, the '''release number starts at 1'''. As fixes and optimizations are made to the ''PKGBUILD'' file, the package will be '''re-released''' and the '''release number''' will increment by 1. When a new version of the package comes out, the release number resets to 1.<br />
* '''''pkgdesc'''''<br />
** The description of the package. The description should be about 80 character or less and should not include the package name in a self-referencing way. For instance, "Nedit is a text editor for X11" should be written as "A text editor for X11."<br />
* '''''arch'''''<br />
** An array of architectures that the ''PKGBUILD'' file is known to build and work on. Currently, it should contain '''i686''' and/or '''x86_64''', arch=('i686' 'x86_64'). The value '''any''' can also be used for independent packages, but the official repositories of Arch does not support this value.<br />
* '''''url'''''<br />
** The URL of the official site of the software being packaged.<br />
* '''''license'''''<br />
** The license under which the software is distributed. A ''licenses'' package has been created in ''[core]'' that stores common licenses in ''/usr/share/licenses/common'', i.e. ''/usr/share/licenses/common/GPL''. If a package is licensed under one of these licenses, the value should be set to the directory name, e.g. ''license=('GPL')''. If the appropriate license is not included in the official ''licenses'' package, several things must be done:<br />
**# The license file(s) should be included in: ''/usr/share/licenses/'''pkgname'''/'', e.g. ''/usr/share/licenses/foobar/LICENSE''.<br />
**# If the source tarball does '''NOT''' contain the license details and the license is only displayed elsewhere, e.g. a website, then you need to copy the license to a file and include it.<br />
**# Add '''custom''' to the ''licenses'' array. Optionally, you can replace '''custom''' with '''custom:name of license'''. Once a license is used in two or more packages in an official repository (including ''[community]''), it becomes a part of the ''licenses'' package.<br />
** The [[Wikipedia:BSD_License|BSD]], [[Wikipedia:MIT_License|MIT]], [[Wikipedia:ZLIB_license|zlib/png]] and [[Wikipedia:Python_License|Python]] licenses are special cases and could not be included in the ''licenses'' package. For the sake of the ''license'' array, it is treated as a common license (''license=('BSD')'', ''license=('MIT')'', ''license=('ZLIB')'' and ''license=('Python')'') but technically each one is a custom license because each one has its own copyright line. Any packages licensed under these four should have its own unique license stored in ''/usr/share/licenses/'''pkgname'''''. Some packages may not be covered by a single license. In these cases, multiple entries may be made in the license array, e.g. ''license=('GPL' 'custom:name of license')''.<br />
** Additionally, the (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:<br />
*** (L)GPL - (L)GPLv2 or any later version<br />
*** (L)GPL2 - (L)GPL2 only<br />
*** (L)GPL3 - (L)GPL3 or any later version<br />
<br />
* '''''groups'''''<br />
** The group the package belongs in. For instance, when you install the ''kdebase'' package, it installs all packages that belongs in the ''kde'' group.<br />
* '''''depends'''''<br />
** An array of package names that must be installed before this software can be run. If a software requires a minimum version of a dependency, the '''>=''' operator should be used to point this out, e.g. ''depends=('foobar>=1.8.0')''. You do not need to list packages that your software depends on if other packages your software depends on already have those packages listed in their dependency. For instance, ''gtk2'' depends on ''glib2'' and ''glibc''. However, ''glibc'' does not need to be listed as a dependency for ''gtk2'' because it is a dependency for ''glib2''.<br />
* '''''makedepends'''''<br />
** An array of package names that must be installed to build the software but unnecessary for using the software after installation. You can specify the minimum version dependency of the packages in the same format as the ''depends'' array.<br />
<br />
{{Warning | Remember this before complaining about missing (make)dependencies. The "base" group is assumed already installed in all Arch setups . The group "base-devel" is assumed already installed when building with makepkg .}}<br />
* '''''optdepends'''''<br />
** An array of package names that are not needed for the software to function but provides additional features. A short description of what each package provides should also be noted. An ''optdepends'' may look like this:<br />
optdepends=('cups: printing support'<br />
'sane: scanners support'<br />
'libgphoto2: digital cameras support'<br />
'alsa-lib: sound support'<br />
'giflib: GIF images support'<br />
'libjpeg: JPEG images support'<br />
'libpng: PNG images support')<br />
<br />
* '''''provides'''''<br />
** An array of package names that this package provies the features of (or a virtual package such as ''cron'' or ''sh''). If you use this variable, you should add the version (''pkgver'' and perhaps the ''pkgrel'') that this package will provide if dependencies may be affected by it. For instance, if you are providing a modified ''qt'' package named ''qt-foobar'' version 3.3.8 which provides ''qt'' then the ''provides'' array should look like ''provides=('qt=3.3.8')''. Putting ''provides=('qt')'' will cause to fail those dependencies that require a specific version of ''qt''. Do not add pkgname to your provides array, this is done automatically.<br />
<br />
* '''''conflicts'''''<br />
** An array of package names that may cause problems with this package if installed. You can also specify the version properties of the conflicting packages in the same format as the ''depends'' array.<br />
* '''''replaces'''''<br />
** An array of obsolete package name that are replaced by this package, e.g. ''replaces=('ethereal')'' for the ''wireshark'' package. After syncing with ''pacman -Sy'', it will immediately replace an installed package upon encountering another package with the matching ''replaces'' in the repositories. If you are providing an alternate version of an already existing package, use the ''conflicts'' variable which is only evaluated when actually installing the conflicting package.<br />
<br />
* '''''backup'''''<br />
** An array of files to be backed up as ''file.pacsave'' when the package is removed. This is commonly used for packages placing configuration files in ''/etc''. The file paths in this array should be relative paths (e.g. etc/pacman.conf) not absolute paths (e.g. /etc/pacman.conf).<br />
<br />
* '''''options'''''<br />
** This array allows you to override some of the default behavior of ''makepkg''. To set an option, include the option name in the array. To reverse the default behavior, place an '''!''' at the front of the option. The following options may be placed in the array:<br />
*** '''''strip''''' - Strips symbols from binaries and libraries.<br />
*** '''''docs''''' - Save ''/doc'' directories.<br />
*** '''''libtool''''' - Leave ''libtool'' (.la) files in packages.<br />
*** '''''emptydirs''''' - Leave empty directories in packages.<br />
*** '''''zipman''''' - Compress ''man'' and ''info'' pages with ''gzip''.<br />
*** '''''ccache''''' - Allow the use of ''ccache'' during build. More useful in its negative form ''!ccache'' with select packages that have problems building with ''ccache''.<br />
*** '''''distcc''''' - Allow the use of ''distcc'' during build. More useful in its negative form ''!distcc'' with select packages that have problems building with ''distcc''.<br />
*** '''''makeflags''''' - Allow the use of user-specific ''makeflags'' during build. More useful in its negative form ''!makeflags'' with select packages that have problems building with custom ''makeflags''.<br />
*** '''''force''''' - Force the package to be upgraded by a ''pacman'' system upgrade operation, even if the version number would normally not trigger such an upgrade. This is useful when the version numbering scheme of a package changes (or is alphanumeric).<br />
<br />
* '''''install'''''<br />
** The name of the ''.install'' script to be included in the package. ''pacman'' has the ability to store and execute a package-specific script when it installs, removes or upgrades a package. The script contains the following functions which run at different times:<br />
*** '''''pre_install''''' - The script is run right before files are extracted. One argument is passed: new package version.<br />
*** '''''post_install''''' - The script is run right after files are extracted. One argument is passed: new package version.<br />
*** '''''pre_upgrade''''' - The script is run right before files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
*** '''''post_upgrade''''' - The script is run after files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
*** '''''pre_remove''''' - The script is run right before files are removed. One argument is passed: old package version.<br />
*** '''''post_remove''''' - The script is run right after files are removed. One argument is passed: old package version.<br />
** {{ Note | A prototype ''.install'' is provided at ''/usr/share/pacman/proto.install''. }}<br />
<br />
* '''''source'''''<br />
** An array of files which are needed to build the package. It must contain the location of the software source, which in most cases is a full HTTP or FTP URL. The previously set variables ''pkgname'' and ''pkgver'' can be used effectively here:<br />
*** <pre>source=(http://example.com/$pkgname-$pkgver.tar.gz)</pre><br />
** If you need to supply which are not downloadable on the fly, e.g. self-made patches, you simply put those into the same directory where your ''PKGBUILD'' file is in and add the filename to this array. Any paths you add here are resolved relative to the directory where the ''PKGBUILD'' lies. Before the actual build process is started, all of the files referenced in this array will be downloaded or checked for existence, and ''makepkg'' will not proceed if any are missing.<br />
<br />
* '''''noextract'''''<br />
** An array of files listed under the ''source'' array which should not be extracted from their archive format by ''makepkg''. This most commonly applies to certain zip files which cannot be handled by ''bsdtar'' because ''libarchive'' processes all files as streams rather than random access as ''unzip'' does. In these situations ''unzip'' should be added in the ''makedepends'' array and the first line of the ''build()'' function should contain:<br />
<pre><br />
cd $srcdir/$pkgname-$pkgver<br />
unzip [source].zip<br />
</pre><br />
<br />
* '''''md5sums'''''<br />
** An array of md5 checksums of the files listed in the ''source'' array. Once all files in the ''source'' array are available, an md5 hash of each file will be automatically generated and compared with the values of this array in the same order they appear in the ''source'' array. While the order of the source files itself does not matter, it is important that it matches the order of this array since ''makepkg'' cannot guess which md5sum belongs to what source file. You can generate this array quickly and easily using the command ''makepkg -g'' in the directory that contains the ''PKGBUILD'' file.<br />
<br />
It is common practice to preserve the order of the ''PKGBUILD'' variables as shown above. However, this is not mandatory, as the only requirement in this context is correct [[Wikipedia:Bash|Bash]] syntax.<br />
<br />
=The build() function=<br />
<br />
Now you need to implement the ''build()'' function in the ''PKGBUILD'' file. This function uses common shell commands in the [http://en.wikipedia.org/wiki/Bash Bash] syntax to automatically compile software and create a ''pkg/'' directory to install the software to. This allows ''makepkg'' to pack it up without having to pick all the necessary files from your actual filesystem.<br />
The first step in the ''build()'' function is to change into the directory created by uncompressing the source tarball. In most common cases the first command will look like this:<br />
cd $srcdir/$pkgname-$pkgver<br />
<br />
Now, you need to list the same commands you used when you manually compiled the software. The ''build()'' function in essence automates everything you did by hand and compiles the software in the fakeroot build environment. If the software you are packaging uses a configure script, it is good practice to use ''--prefix=/usr'' when building packages for ''pacman''. A lot of software install their files relative to the ''/usr/local'' directory, which should only be done if you are manually building from source. All Arch Linux packages should use the ''/usr'' directory. As seen in the ''/usr/share/pacman/PKGBUILD.proto'' file, the next two lines should look like this:<br />
./configure --prefix=/usr<br />
make || return 1<br />
<br />
The final step in the ''build()'' funciton is to put the compiled files in a directory where ''makepkg'' can retrieve to create a package. This by default is the ''pkg/'' directory - a simple fakeroot environment. It imitates the root of your filesystem to the software's installation procedure. If you have to manually install files under the root of your filesystem, you should instead install it in the ''pkg/'' directory under the same directory structure, e.g. if you want to install a file to ''/usr/bin'', it should instead be placed under ''$pkgdir/usr/bin''. Very few software require the user to copy dozens of files manually, and you usually will not have to worry about this. Instead, for most software you will have to call ''make install''. The final line should look like the following in order to correctly install the software in the ''pkg/'' directory:<br />
make DESTDIR=$pkgdir install || return 1<br />
<br />
'''Note''': It is sometimes the case where <code>DESTDIR</code> is not used in the <code>Makefile</code>; you may need to use <code>prefix</code> instead. If the package is built with autoconf/automake, use <code>DESTDIR</code>; this is what is [http://sources.redhat.com/automake/automake.html#Install documented] in the manuals. If <code>DESTDIR</code> does not work, try building with <code>make prefix="$pkgdir/usr/" install</code>. If that does not work, you'll have to look further into the install commands that are executed by "<code>make <...> install</code>".<br />
<br />
In some odd cases, the software expects to be run from a single directory. In such cases it is wise to simply copy these to ''$pkgdir/opt''.<br />
More often than not the installation process of the software will create any subdirectories below the ''pkg/'' directory. If it does not, however, ''makepkg'' will generate a lot of errors and you will need to manually create subdirectories by adding the appropriate ''mkdir -p'' commands in the ''build()'' function before the installation procedure is run.<br />
Also, ''makepkg'' defines three variables that you should use as part of the build and install process:<br />
*'''''startdir''''' - This contains the absolute path to the directory where the ''PKGBUILD'' file is located, which is the present working directory. This variable is almost always used in combination with ''/src'' or ''/pkg'' postfixes, but the use of ''srcdir'' and ''pkgdir'' variables is preferred.<br />
*'''''srcdir''''' - This points to the directory where ''makepkg'' extracts or copies all source files. It is currently an alias for ''$startdir/src''.<br />
*'''''pkgdir''''' - This points to the directory where ''makepkg'' bundles the installed package, which becomes the root directory of your built package. It is currently an alias for ''$startdir/pkg''.<br />
<br />
=Additional Guidelines=<br />
<br />
Here are some additional guidelines that you should adhere to:<br />
*All elements in an array variable '''must be separated by spaces'''.<br />
*If possible, remove empty lines from the ''PKGBUILD'' including fields that have empty values.<br />
*Wherever possible, use ''|| return 1'' for critical build functions: make || return 1 make DESTDIR=$pkgdir install || return 1 <br />
*'''Do not introduce new variables''' into your ''PKGBUILD'' file unless the package cannot be built without doing so, as these could possibly conflict with variables used in ''makepkg'' itself. If a new variable is absolutely required, '''prefix the variable name with an underscore''': _customvariable= <br />
*'''Avoid''' using ''/usr/libexec/'' for anything. Use ''/usr/lib/pkgname'' instead.<br />
*The ''packager'' field from the package meta file can be customized by the package builder by modifying the appropriate option in the ''/etc/makepkg.conf'' file, or alternatively by exporting the ''PACKAGER'' environment variable before building packages with ''makepkg'': # export PACKAGER="Your Name &lt;email@domain.com&gt;" <br />
* '''Configuration files''' should be placed in the ''/etc'' directory. If there is more than one configuration file, it is customary to use a subdirectory in order to keep the ''/etc'' area as clean as possible. Use ''/etc/'''pkgname''''' or a suitable alternative, e.g., [http://httpd.apache.org/ Apache] uses ''/etc/httpd/''. <br />
*Package files should follow these '''general directory guidelines''': <br />
**''/etc/'' - System essential configuration files<br />
**''/usr/bin'' - Application binaries<br />
**''/usr/sbin'' - System binaries<br />
**''/usr/lib'' - Libraries<br />
**''/usr/include'' - Header files<br />
**''/usr/lib/pkgname'' - Modules, plugins, etc.<br />
**''/usr/share/man'' - Manpages<br />
**''/usr/share/pkgname'' - Application data<br />
**''/usr/share/licenses/pkgname'' - Package license, if not included under common<br />
**''/etc/pkgname'' - Configuration files<br />
**''/opt'' - Large self-contained packages such as Java, etc.<br />
<br />
*Packages should not contain the following directories: <br />
**''/dev''<br />
**''/home''<br />
**''/media''<br />
**''/mnt''<br />
**''/proc''<br />
**''/root''<br />
**''/selinux''<br />
**''/sys''<br />
**''/tmp''<br />
**''/var/tmp''<br />
<br />
=Testing the Package=<br />
<br />
As you are writing the ''build()'' function, you will want to test your changes frequently to ensure there are no bugs. You can do this using the ''makepkg'' command in the directory containing the ''PKGBUILD'' file. With a properly formatted ''PKGBUILD'', this will create a package, but with a broken or unfinished one it will throw an error.<br />
If ''makepkg'' finishes successfully, it will place a file named ''pkgname-pkgver.pkg.tar.gz'' in your working directory. This is package that can be installed with the ''pacman -U'' command. However, just because a package file was built does not imply that it is fully functional. It might conceivably contain only the directory and no files whatsoever if, for example, a prefix was specified improperly. You can use ''pacman'''s query functions to display a list of files contained in the package and the dependencies it requires with ''pacman -Qlp [package file]'' and ''pacman -Qip [package file]'' respectively.<br />
If the package looks sane, then you are done! However, if you plan on release the ''PKGBUILD'' file, it is imperative that you check and double check the contents of the ''depends'' array. <br />
<br />
=ldd and namcap=<br />
<br />
Dependencies are the most common packaging error. There are two excellent tools you can use to check dependencies. The first one is ''ldd'', which will show you the shared library dependencies of dynamic executables:<br />
$ ldd gcc<br />
linux-gate.so.1 => (0xb7f33000)<br />
libc.so.6 => /lib/libc.so.6 (0xb7de0000)<br />
/lib/ld-linux.so.2 (0xb7f34000)<br />
<br />
The other tool is ''namcap'' which not only checks for dependencies but the overall sanity of your package. It can be used on both the ''PKGBUILD'' file and the ''pkg.tar.gz'' package. It will report any bad permissions, missing dependencies, unnecessary dependencies and other common mistakes. You can install ''namcap'' via ''pacman'':<br />
$ pacman -S namcap<br />
<br />
To use ''namcap'', simply supply a ''PKGBUILD'' file or a ''pkg.tar.gz'' package as the argument:<br />
$ namcap PKGBUILD<br />
or $ namcap pkgname.tar.gz<br />
<br />
Although ''namcap'' can help detect dependencies, it is not always correct. Verify dependencies by looking at the documentation of the software.<br />
<br />
=Submitting Packages to the AUR=<br />
<br />
Follow these steps to submit a package into the AUR:<br />
#Register a new account if you do not already have one.<br />
#Check all of the official repositories (''[core]'', ''[extra]'', and ''[community]'') and see if the package already exists. If it is inside any of those repositories, '''DO NOT''' submit the package. If the package is broken, file a bug report.<br />
#Check the ''[unsupported]'' repository for the package. If it is currently maintained, changes can be submitted in a comment for the maintaner's attention. If it is unmaintained, the package can be adopted and updated.<br />
#To upload the package to the AUR, the directory containing the ''PKGBUILD'' file and any other required files must be compressed as a tarball. The archive name should contain the name of the package, e.g. ''foo.tar.gz.''. You can easily build a tarball by using ''makepkg --source'' in the directory. This makes a tarball named ''pkgname-pkver-pkrel.src.tar.gz'', which you can then upload to the AUR. The tarball '''cannot''' contain the binary tarball created by ''makepkg'' or the source tarball of the software. Packages that contain binaries or that are very poorly written will be deleted without warning.<br />
#Click the '''Submit''' link by the menu in the AUR. Choose the appropriate category for your package and upload.<br />
<br />
=Summary=<br />
#Download the source tarball of the software you want to package.<br />
#Try compiling the package and installing it into an arbitrary directory.<br />
#Copy over the prototype ''/usr/share/pacman/PKGBUILD.proto'' and rename it to ''PKGBUILD'' in a temporary working directory - preferably ''~/abs/''.<br />
#Edit the ''PKGBUILD'' according to the needs of your package.<br />
#Run ''makepkg'' and see whether the resulting package is built correctly.<br />
#If not, repeat the last two steps.<br />
<br />
=See also=<br />
* [[ABS]] The Arch Build System<br />
* [[Arch CVS & SVN PKGBUILD guidelines]]<br />
* [[ArchLinux User-community Repository (AUR)]]<br />
* [[Kernel Compilation with ABS]]<br />
* [[Makepkg]]<br />
* [[Safe Cflags]]<br />
* [[PKGBUILD Tricks]]</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Talk:Creating_packages&diff=85054Talk:Creating packages2009-11-25T04:30:32Z<p>Bhobbit: </p>
<hr />
<div>Guys, if I'm going to see even more of this useless PKGBUILD variable reordering stuff, I'll go completely insane, submit my own standard of those to upstream (oh, that's right here! :) and put every wiki article on my watchlist containing the word "pkgname"... ''-.-''<br />
:--[[User:Byte|byte]]<br />
<br />
I think the title of this article is somewhat misleading: it discusses building packages from the abs tree, while using abs is not necessary to either build, install or remove packages. This fact mentioned in the article itself, but it doesn't make the title less confusing for those who are just starting to get familiarized with building packages in Arch.<br />
--[[User:Bhobbit|Bhobbit]] 23:30, 24 November 2009 (EST)</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Network_Time_Protocol&diff=71391Network Time Protocol2009-06-29T18:01:02Z<p>Bhobbit: grammar</p>
<hr />
<div>[[Category:Networking (English)]]<br />
[[Category:Daemons and system services (English)]]<br />
[[Category:HOWTOs (English)]]<br />
{{i18n_links_start}}<br />
{{i18n_entry|English|:Network Time Protocol}}<br />
{{i18n_entry|简体中文|:Network Time Protocol (简体中文)}}<br />
{{i18n_links_end}}<br />
This article discribes the different possibilities of getting accurate system time and date for your Arch Linux. First openntpd is explained, an easy to use solution. Second, the original ntpd is explained.<br />
<br />
== OpenNTPD ==<br />
<br />
===Using OpenNTPD instead of ntpd===<br />
<br />
OpenNTPD is a FREE, easy to use implementation of the Network Time Protocol. It provides the ability to sync the local clock to remote NTP servers and can act as NTP server itself, redistributing the local clock.<br />
<br />
OpenNTPD is primarily developed by Henning Brauer as part of the OpenBSD Project.<br />
<br />
OpenNTPD is a brand new implementation of the ntp protocol. It is much easier to configure and use than ntpd.<br />
<br />
First, the OpenNTPD package must be installed.<br />
It is available in the Arch Linux community repository.<br />
<br />
# pacman -S openntpd<br />
<br />
Once installed, the /etc/ntpd.conf file must be edited.<br />
This is much easier than with ntpd.<br />
<br />
The default configuration is actually usable if all you want is to sync the local computer.<br />
<pre><br />
# $OpenBSD: ntpd.conf,v 1.7 2004/07/20 17:38:35 henning Exp $<br />
# sample ntpd configuration file, see ntpd.conf(5)<br />
<br />
# Addresses to listen on (ntpd does not listen by default)<br />
#listen on *<br />
#listen on 127.0.0.1<br />
#listen on ::1<br />
<br />
# sync to a single server<br />
#server ntp.example.org<br />
<br />
# use a random selection of 8 public stratum 2 servers<br />
# see http://twiki.ntp.org/bin/view/Servers/NTPPoolServers<br />
servers pool.ntp.org<br />
</pre><br />
<br />
To sync to a particular server, uncomment and edit the "server" directive. You can find server's URL in your area at [http://www.pool.ntp.org/zone/@ www.pool.ntp.org/zone/@].<br />
server ntp.example.org<br />
<br />
The "servers" directive works the same as the "server" directive, however, if the dns name resolves to multiple IP address, ALL of them will be synced to. The default, "pool.ntp.org" is working and should be acceptable in most cases.<br />
pool.ntp.org<br />
<br />
Any number of "server" or "servers" directives may be used.<br />
<br />
If you want the computer you run OpenNTPD on to also be a time server, simply uncomment and edit the "listen" directive.<br />
<br />
For example:<br />
listen on *<br />
will listen on all interfaces, and<br />
listen on 127.0.0.1<br />
will only listen on the loopback interface.<br />
<br />
If you would like to run OpenNTPD at boot, add openntpd the DAEMONS variable in your /etc/rc.conf. If you are using openntpd just to set your local system time, you could add @openntpd instead of openntpd to decrease the boot time; adding the @ makes Arch run the other daemons following @openntpd without waiting for openntpd to finish.<br />
<br />
If you want to see the status of your syncing, look at /var/log/daemon.log<br />
<br />
OpenNTPD skews the clock by small amounts at a time. It can take some time to correct the time. If it is off by more than 180 seconds you can try "<code>ntpd -s -d</code>" in the console. The -s can help with large time corrections. You can also use the "<code>date --set=STRING</code>" to set the time as close to possible to the actual time and then let OpenNTPD fine tune the time.<br />
<br />
=== Trouble Shooting ===<br />
'''Error adjusting time'''<br />
<br />
If you find your time set incorrectly and in log you see<br />
openntpd adjtime failed: Invalid argument<br />
try "<code>ntpd -s -d</code>" in console .<br />
<br />
<br />
'''Increasing time shift'''<br />
<br />
Starting ''openntpd'' in the background could lead to synchronization errors between the actual time and the time stored on your computer. If you recognize an increasing time difference between your desktop clock and the actual time, try to start the ''openntpd'' daemon normal and not in the background.<br />
<br />
== ntp ==<br />
===Installation===<br />
# pacman -S ntp<br />
<br />
===/etc/ntp.conf Configuration===<br />
The very first line of your ntp.conf file should contain a line such as the following:<br />
restrict default noquery notrust nomodify<br />
<br />
This essentially restricts everyone from modifying anything. Following this, you need to let ntpd know what you want to let through into your NTP server. Here is where you would specify any other ip addresses you would like to synchronize on your NTP server. For example:<br />
restrict 1.2.3.4<br />
restrict 192.168.0.0 mask 255.255.255.0 nomodify<br />
<br />
This tells ntpd that 1.2.3.4 and all ip addresses from the 192.168.0.0 range will be allowed to synchronize on this server, but they will not be allowed to modify anything. All other IP addresses in the world will still obey the default restrictions (the first line in the ntp.conf).<br />
<br />
Now, is where the stratum 2 servers that our server will synchronize with come into play. The lines in ntp.conf will be used to tell ntpd what servers we would like to use for synchronizing (these are just examples; use ntp servers that are closest to your location). Please see http://ntp.isc.org/bin/view/Servers/NTPPoolServers for a list a closer servers.<br />
server ntp1.cs.wisc.edu<br />
server ntp3.cs.wisc.edu<br />
server ntp3.sf-bay.org<br />
<br />
Unless you have a good reason not to, it is advisable to use the pool.ntp.org servers: http://www.pool.ntp.org/.<br />
Alternatively, a list of ntp servers is available at http://www.eecis.udel.edu/~mills/ntp/clock2a.html. Please pay attention to the Access Policies. <br />
<br />
If we left it alone right now, we would never connect to a server because the response from any of the three servers listed above would never be allowed back into our server due to the fact that our default restrict statement would be in use (since we did not add the servers to our lesser restrictions (like we did with 127.0.0.1 and the subnet of 192.168.0.0).<br />
<br />
To correct this, enter the following lines in ntp.conf:<br />
restrict ntp1.cs.wisc.edu noquery nomodify<br />
restrict ntp3.cs.wisc.edu noquery nomodify<br />
restrict ntp3.sf-bay.org noquery nomodify<br />
<br />
This will allow the response from the above servers into our system so our local clock can be synchronized. The noquery restriction will not allow any of the above three servers to query for information from our server. The nomodify restriction will not allow the three servers to modify anything (synchronization will still take place).<br />
<br />
The only thing left to do is add the drift file (which keeps track of yours clocks time deviation). and the log file location:<br />
driftfile /etc/ntp.drift<br />
logfile /var/log/ntp.log<br />
<br />
The complete file will look like this:<br />
<br />
<pre><br />
# default restrictions<br />
restrict default noquery notrust nomodify<br />
<br />
# override the default restrictions here<br />
restrict 10.1.1.0 mask 255.255.255.0 nomodify<br />
<br />
# public NTP servers to sync with (all stratum 2)<br />
server ntp1.cs.wisc.edu<br />
server ntp3.cs.wisc.edu<br />
server ntp3.sf-bay.org<br />
<br />
restrict ntp1.cs.wisc.edu noquery nomodify<br />
restrict ntp3.cs.wisc.edu noquery nomodify<br />
restrict ntp3.sf-bay.org noquery nomodify<br />
<br />
# NTP drift file - used to keep track of your system clocks<br />
# time deviation<br />
driftfile /etc/ntp.drift<br />
<br />
# NTP log file<br />
logfile /var/log/ntp.log<br />
</pre><br />
<br />
Take note that this is for a client and a server ntp.conf configuration. If you just want to synchronize with a stratum server and are not concerned with other PCs synchronizing with your ntp server, then you can do something like the following (note that only 127.0.0.1 is allowed to be synchronized):<br />
<br />
<pre><br />
# default restrictions<br />
restrict default noquery notrust nomodify<br />
<br />
# Permit all access over the loopback interface<br />
restrict 127.0.0.1<br />
<br />
# public NTP servers to sync with (all stratum 2)<br />
server ntp1.cs.wisc.edu<br />
server ntp3.cs.wisc.edu<br />
server ntp3.sf-bay.org<br />
<br />
restrict ntp1.cs.wisc.edu noquery nomodify<br />
restrict ntp3.cs.wisc.edu noquery nomodify<br />
restrict ntp3.sf-bay.org noquery nomodify<br />
<br />
# NTP drift file - used to keep track of your system clocks<br />
# time deviation<br />
driftfile /etc/ntp.drift<br />
<br />
# NTP log file<br />
logfile /var/log/ntp.log<br />
</pre><br />
<br />
... or if you don't care about restrictions at all, something like this (note there are no restrictions, thus no need to reduce restrictions for 127.0.0.1 to allow your local clock to synchronize):<br />
<br />
<pre><br />
# public NTP servers to sync with (all stratum 2)<br />
server ntp1.cs.wisc.edu<br />
server ntp3.cs.wisc.edu<br />
server ntp3.sf-bay.org<br />
<br />
# NTP drift file - used to keep track of your system clocks<br />
# time deviation<br />
driftfile /etc/ntp.drift<br />
<br />
# NTP log file<br />
logfile /var/log/ntp.log<br />
</pre><br />
<br />
===A Note about Security===<br />
You may wonder about all of the restrict lines. The reason for them is security. If you don't want a secure NTP server, don't add any restrict lines to your ntp.conf file. If you want a secure NTP server, start out by adding a default restrict that doesn't allow anything to contact your server, then add more (less restrictive) restrict lines - allowing certain addresses various access privileges.<br />
<br />
===/etc/rc.d/network file modification===<br />
One more thing that you may want to do. In some cases, your /etc/ntp.conf file may be overwritten by dhcp. To avoid this, edit the /etc/conf.d/dhcpcd file and add <code>-N</code> to the line that starts with '<code>dhcpcd -t 10</code>'.<br />
<br />
'''Note:''' This was my experience/solution with setting the time:<br />
<br />
On my system my /etc/conf.d/dhcpcd contains a single line:<br />
DHCPCD_ARGS="-t 30 -h $HOSTNAME"<br />
<br />
I assume it needs to be changed to:<br />
DHCPCD_ARGS="-N -t 30 -h $HOSTNAME"<br />
<br />
Some have suggested adding <code>-R</code> to preserve /etc/resolv.conf as well.<br />
<br />
===/etc/conf.d/ntp-client.conf Configuration===<br />
This is for /etc/rc.d/ntpdate configuration. Edit NTP_CLIENT_SERVER for your ntp server. <br />
<pre><br />
# change this to a server closer to your location<br />
NTP_CLIENT_SERVER="pool.ntp.org"<br />
<br />
# client options<br />
NTP_CLIENT_OPTION="-b -u"<br />
<br />
# timeout for the ntp-client<br />
NTPCLIENT_TIMEOUT=10<br />
<br />
# arguments passed to ntpd when started<br />
NTPD_ARGS="-g"<br />
</pre><br />
<br />
=== /etc/rc.conf file modification ===<br />
Add ntpdate and ntpd in DAEMONS=().<br />
<br />
DAEMONS=(syslog-ng network ntpdate ntpd ...)<br />
<br />
{{Note| ntpdate has to be placed before ntpd.}}<br />
<!--<br />
===To fix Time use /etc/rc.local===<br />
To set the correct time; Set time and start ntpd at boot via /etc/rc.local<br />
<br />
Relevant sections of /etc/rc.conf<br />
HARDWARECLOCK="UTC"<br />
TIMEZONE="US/Mountain"<br />
<br />
''Network/DHCP section:''<br />
lo="lo 127.0.0.1"<br />
eth0="dhcp"<br />
INTERFACES=(lo eth0)<br />
''Daemons subsection:''<br />
DAEMONS=(syslog-ng hotplug !pcmcia network netfs !ntpd crond dbus hal alsa gdm)<br />
<br />
This is my /etc/rc.local<br />
#!/bin/bash<br />
#<br />
# /etc/rc.local: Local multi-user startup script.<br />
#<br />
<br />
# Re-copy ntp.conf (was over written by dhcp)<br />
cp /root/CONFIG.BAK/ntp.conf.bac /etc/ntp.conf<br />
# I advise you keep your desired /etc/ntp.conf<br />
# OUTSIDE of /etc<br />
<br />
# Set time<br />
/usr/bin/ntpdate ntp.nasa.gov #Use any time server you like here<br />
<br />
# Start ntpd<br />
/etc/rc.d/ntpd start<br />
<br />
And here is my /root/CONFIG.BAK/ntp.conf.bac (this is just a copy of the desired /etc/ntp.conf)<br />
# default restrictions<br />
restrict default noquery notrust nomodify<br />
<br />
# override the default restrictions here<br />
restrict 127.0.0.1 nomodify<br />
restrict 192.168.2.0 mask 255.255.255.0 nomodify<br />
<br />
# public NTP servers to sync with (all stratum 2)<br />
server ntp.nasa.gov #Use any time server you like here<br />
<br />
restrict ntp.nasa.gov noquery nomodify<br />
<br />
# NTP drift file - used to keep track of your system clocks<br />
driftfile /etc/ntp.drift<br />
<br />
# NTP log file<br />
logfile /var/log/ntp.log<br />
<br />
Leave /etc/conf.d/dhcpcd at default. Mine is a single line and reads<br />
DHCPCD_ARGS="-t 30 -h $HOSTNAME"<br />
<br />
With this configuration I get the correct time and ntpd running at boot.<br />
There may be a better way, but this worked for me.<br />
I hope it helps. --><br />
<br />
===Updating your system immediately using ntpdate===<br />
It is recommended to add a line like the following to your /etc/rc.local file so when you boot your system, your time will be correct (use an NTP server close to your location).<br />
/usr/bin/ntpdate ntp1.cs.wisc.edu<br />
<br />
Running ''ntpdate'' when you boot up is a good idea because ntpd may take a long time to synchronize your local clock depending on how far off the time is. If your clock is synchronized when ntpd starts, then it's sole purpose is to keep it synchronized. To run ntpd at startup, add ''ntpd'' to the daemons section of the /etc/rc.conf file.<br />
<br />
ntpd will work well if you have a connection to the internet all the time. If you are using dialup, you may just want to stick with using ntpdate via the command line.<br />
<br />
===Querying your NTP server using ntpq===<br />
There is a default restrict statement for the localhost that includes an ignore flag. Without overriding it (adding the line ''restrict'' ''127.0.0.1'') you will not be able to query your NTP server. If that's not a concern to you, then leave out the restrict line for your localhost. You will still be able to synchronize with your stratum 2 servers.<br />
<br />
== External Resources ==<br />
* http://www.ntp.org/<br />
* http://twiki.ntp.org/bin/view/Main/WebHome<br />
* http://www.eecis.udel.edu/~mills/ntp/html/index.html<br />
* http://www.openntpd.org</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Netcfg&diff=70226Netcfg2009-06-09T06:56:49Z<p>Bhobbit: correction: wifi-select now lives in [community]; updated the section accordingly</p>
<hr />
<div>{{i18n_links_start}}<br />
{{i18n_entry|English|Network Profiles}}<br />
{{i18n_entry|简体中文|Netcfg2网络配置}}<br />
{{i18n_entry|Türkçe|Ağ Profilleri}}<br />
{{i18n_links_end}}<br />
<br />
==Quickstart==<br />
===Step 1===<br />
# pacman -Sy core/netcfg<br />
or<br />
# pacman -Sy testing/netcfg<br />
<br />
{{Box Note | Presently the [testing] version is recommended as it contains many fixes and improved documentation, however this document is equally applicable for the [core] version -- iphitus }}<br />
<br />
===Step 2===<br />
Copy an example configuration from /etc/network.d/examples/ to /etc/network.d/mynetwork. You may use another name instead of "mynetwork".<br />
<br />
Depending on your security and connection, use the following examples from /etc/network.d/examples/<br />
* '''WEP hex key''' wireless-wep<br />
* '''WEP string key''' wireless-wep-string-key<br />
* '''WPA passphrase''' wireless-wpa<br />
* '''WPA enterprise''' wireless-wpa-config<br />
* '''Wired connection - dhcp''' ethernet-dhcp<br />
* '''Wired connection - static IP''' ethernet-static<br />
* '''Wired connection - iproute configuration''' ethernet-iproute<br />
<br />
===Step 3===<br />
Modify your configuration file new configuration file, /etc/network.d/mynetwork<br />
<br />
* Set INTERFACE= to your wireless or ethernet interface. This can be checked with ifconfig and iwconfig.<br />
* '''Wireless''' - Make sure you set your ESSID and KEY correctly. Typos in these are common errors.<br />
* '''Wireless - WPA Enterprise''' - You'll need to use an external wpa_supplicant configuration.<br />
<br />
===Step 4===<br />
To connect, simply execute:<br />
# netcfg mynetwork<br />
<br />
If it does not work, have a look at the [[Network Profiles#Troubleshooting|troubleshooting section]] for solutions and how to get help.<br />
<br />
If all goes to plan, you can configure it to [[Network Profiles#Step 4: Connecting on boot|connect automatically or on boot]].<br />
<br />
==Step 1: Install==<br />
Network profiles are handled by the bash scripts available in the netcfg package.<br />
<br />
# pacman -Sy testing/netcfg<br />
<br />
For information relating to the latest development version of netcfg, see [[Network Profiles development]]<br />
<br />
==Step 2: Create the profile(s)==<br />
A profile is a single text file in /etc/network.d which defines variables used by netcfg. The file name will become the name of the profile, and can be anything you wish, it is not a setting involved in the connection.<br />
<br />
The easiest way to create a new profile is to copy one of the example profiles from /etc/network.d/examples and edit it to fit with your network.<br />
<br />
{{Box Note | Example profiles are located in /etc/network.d/examples/. Modifying an example from here is the best way to ensure that you have a configuration suitable for your version of netcfg. }}<br />
<br />
{{Box Note | Your network information (e.g. wireless passkey) will be stored in plain text format, so you may want to change the permissions on the newly created /etc/network.d/*.conf file (e.g. <tt>chmod 0600 /etc/network.d/*.conf</tt> to make it readable by root only), depending upon how security conscious you are. }}<br />
<br />
===Configuration Notes===<br />
====Using a string WEP key====<br />
This is for a STRING WEP key, not a HEX WEP key, not a WPA key.<br />
KEY="s:Somepasskey"<br />
<br />
====Ralink legacy drivers rt2500, rt2400 that use iwpriv====<br />
There is no plans to add WPA support to these drivers. rt2x00 is supported, however, and will replace these.<br />
<br />
If you must use them, create a shell script that runs the needed iwpriv commands and put its path in PRE_UP=""<br />
<br />
====Passing arguments to iwconfig before connecting====<br />
Simply:<br />
<br />
IWCONFIG="<arguments>"<br />
<br />
Where <arguments> can be any valid iwconfig argument. The script then runs "iwconfig $INTERFACE $IWCONFIG"<br />
<br />
For example, setting bssid/ap mac:<br />
IWCONFIG="ap 12:34:56:78:90:12"<br />
<br />
This supercedes the IWOPTS and WEP_OPTS options which were incompletely implemented.<br />
<br />
==Step 3: Connect==<br />
To connect to a profile just execute the following command ''as root'':<br />
# netcfg <profile-name><br />
To disconnect from a profile:<br />
# netcfg down <profile-name><br />
<br />
Where <profile-name> is the name of the file created in /etc/network.d. For example /etc/network.d/homewireless would simply have a profile name of homewireless<br />
<br />
==Step 4: Connecting on boot==<br />
===net-profiles===<br />
<code>net-profiles</code> allows you to start some profiles on boot.<br />
<br />
In order to do that you need to list the /etc/network.d/ profiles you want netcfg to try at boot in the <code>NETWORKS=()</code> line in /etc/rc.conf. <br />
<br />
NETWORKS=(home mywireless)<br />
<br />
You also need to add <code>net-profiles</code> to the DAEMONS array, eg: DAEMONS=(... '''net-profiles''' ...).<br />
<br />
====Display a menu at boot====<br />
<code>net-profiles</code> can also display a menu so you can pick which profile you want to set up. For that you just need to set NETWORKS= to menu (ie <code>NETWORKS=menu</code>).<br />
<br />
You can also access that menu at any time by running <code>netcfg-menu</code> in a terminal.<br />
<br />
The dialog package is needed.<br />
<br />
===Automatic detection===<br />
====net-auto====<br />
<code>net-auto</code> is the second boot-time script of the netcfg package. Its function is to determine automatically which profile should be started.<br />
<br />
<code>net-auto</code> reads the AUTO_NETWORKS=() line in /etc/rc.conf. For example:<br />
AUTO_NETWORKS=(auto-wireless wlan0)<br />
<br />
Like <code>net-profiles</code> it needs to be added to the DAEMONS=() line, eg: DAEMONS=(... '''net-auto''' ...).<br />
<br />
To run after boot:<br />
# /usr/bin/netcfg-auto-wireless $interface<br />
<br />
==Troubleshooting==<br />
===Wireless connections===<br />
For wireless connections, make sure the required drivers and firmwares are installed as explained in [[Wireless Setup]].<br />
===netcfg error messages===<br />
====Network unavailable====<br />
This is typically one of:<br />
* Out of range<br />
* Driver issue (See Driver Quirks above)<br />
* Trying to connect to a hidden network<br />
<br />
If you know your network is hidden, set <br />
SCAN=no <br />
<br />
====Wireless Association failed====<br />
This is typically one of:<br />
* Out of range/reception<br />
* Incorrect configuration<br />
* Invalid key<br />
* Driver problem (See Driver Quirks above)<br />
<br />
If it is a range problem, increasing TIMEOUT= can help.<br />
<br />
====Unable to get IP address with DHCP====<br />
This is typically one of:<br />
* Out of range/reception<br />
<br />
Try increasing DHCP_TIMEOUT<br />
<br />
====Not a valid connection, check spelling or look at examples====<br />
You must set CONNECTION= to one of the connection types in /usr/lib/network/connections/. Alternatively use one of the provided configuration examples in /etc/network.d/examples.<br />
<br />
===Driver Quirks (netcfg 2.1 and later)===<br />
{{Box Note | You most likely do NOT need these. Ensure your configuration is correct before considering these. They are for a small range of drivers with unusual issues, many of them older versions. These are workarounds, not solutions. }}<br />
<br />
Some drivers behave oddly and need workarounds to connect. These have to be enabled manually. They're best determined by reading the forums, seeing what others have used, and, if that fails, trial and error. They '''can''' be combined.<br />
<br />
* prescan - Run "iwlist $INTERFACE scan" before attempting to connect (Some broadcom)<br />
* preessid - Run "iwconfig $INTERFACE essid $ESSID" before attempting to connect. (Some ipw3945 and Intel PRO/Wireless 4965AGN)<br />
* wpaessid - Same as previous, run before starting wpa_supplicant<br />
* predown - Take interface down before association and then restore it after. (madwifi)<br />
* postsleep - Sleep 1 second before checking if the association was successful<br />
* postscan - Run "iwlist scan" after associating <br />
<br />
For example<br />
QUIRKS=(prescan preessid)<br />
<br />
If you are having problems with DNS and DHCP, try adding to your profile:<br />
DHCLIENT=no<br />
This will tell netcfg to use dhcpcd instead of dhclient<br />
<br />
If you get "Wireless Network Not Found" or "Association Failed" and have tried the above, try:<br />
SCAN=no<br />
<br />
===It still doesn't work, what do I do ?===<br />
If the FAQs below didn't solve your problem the next best place to go is the forums, or the mailing list. <br />
<br />
To be able to determine what's wrong, we need information so when you post, make sure that you provide the following output:<br />
* '''''ALL OUTPUT FROM netcfg''''' <br />
* '''''ALL OUTPUT FROM netcfg''''' <br />
* '''''ALL OUTPUT FROM netcfg''''' - this is absolutely cruicial to be able determine what went wrong. The message might be short or nonexistant, but it can mean a great deal. <br />
* '''''Your /etc/network.d network profiles''''' - Also cruicial as many problems are simple config issues. Feel free to censor your wireless key.<br />
* '''''netcfg version'''''<br />
* lsmod<br />
* iwconfig<br />
<br />
==GUI==<br />
<br />
A Qt-based netcfg frontend called ArchAssistant exists. It proposes to manage & connect/disconnect profiles from a systray icon. Automatic wireless detection is also available. This tool is particularly useful for laptop users.<br />
<br />
Links:<br />
[http://aur.archlinux.org/packages.php?ID=15655 archassistant on AUR] | [http://www.kde-apps.org/content/show.php/ArchAssistant?content=76760 archassistant on kde-apps.org] | archassistant package on archlinux.fr [http://repo.archlinux.fr/i686/ i686] and [http://repo.archlinux.fr/x86_64/ x86_64]<br />
<br />
==Supplementary tools==<br />
<br />
There is a console tool for selecting wireless networks "in real-time" (in NetworkManager manner) called <code>wifi-select</code>. The tool is convinient for use in wifi-cafe or another places you are visiting for the first (and maybe the last) time. Then you don't need to create the file-profile for a new network, just type <code>sudo wifi-select wlan0</code> and choose the network you need. <br />
<br />
The tool is currently packaged and available in [community] repository. To install, do <code>pacman -S wifi-select</code>.<br />
<br />
It works as follows:<br />
* parses <code>iwlist scan</code> results and presents list of networks along with its security settings (wpa/wep/none) using <code>dialog</code><br />
* if user selects network with existing profile -- just use this profile to connect with <code>netcfg</code><br />
* if user selects a new network (for example network from wifi-cafe he currently visited), <code>wifi-select</code> automatically generates new profile with corresponding <code>$SECURITY</code> and asks for the key (if needed). It uses DHCP as <code>$IP</code> by default<br />
* then, if connection succeeds, profile is saved for later usage<br />
* if connection fails, user is asked if he/she wants to keep generated profile for further usage (for example to change <code>$IP</code> to static or adjust some additional options)<br />
<br />
Links: <br />
[http://bbs.archlinux.org/viewtopic.php?id=63973 Forum thread] related to development of <code>wifi-select</code> | [http://aur.archlinux.org/packages.php?ID=23471 wifi-select on AUR] | [http://hg.horna.org.ua/wifi-select/ wifi-select mercurial repository]<br />
<br />
==FAQ==<br />
===Why doesnt netcfg do ''x''?===<br />
netcfg doesn't need to. It connects to networks.<br />
<br />
But netcfg is super modular and re-usable. Have a look at /usr/lib/networks/ -- heaps of reusable functions for your own scripts. <br />
<br />
===Why doesn't netcfg behave in this way? It makes more sense===<br />
netcfg doesn't enforce any rules. It's task is to connect to networks. It doesn't impose any heuristics, like 'disconnect from wireless if ethernet is connected'.<br />
<br />
If you want behaviour like that, it'd be really easy to write a separate tool over netcfg. See the question above.<br />
<br />
===Do I still need ''x'' when I'm using netcfg?===<br />
* /etc/hosts: Yes, you still need this, this is important. Don't remove your hostname from this otherwise you'll have some odd problems. <br />
* HOSTNAME= in /etc/rc.conf: It's strongly recommended you keep this, otherwise no hostname will be set if a profile fails<br />
* DAEMONS=(network) and INTERFACES=() in /etc/rc.conf: If you've setup all your networks with netcfg instead, yes, you can remove this. You can also safely remove lo, it's been moved into rc.sysinit.<br />
* lo: This is now in rc.sysinit, you don't need to configure it anywhere.</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Talk:Network_configuration/Wireless&diff=70144Talk:Network configuration/Wireless2009-06-07T05:03:57Z<p>Bhobbit: </p>
<hr />
<div>It would be good to place a further example for encrypting.<br />
<br />
# /etc/conf.d/wireless<br />
wlan_wlan0="wlan0 essid MyEssid"<br />
#wlan_wlan0="wlan0 essid MyEssid key 625341627"<br />
#wlan_wlan0="wlan0 essid MyEssid key s:masterpassword"<br />
<br />
If you have eth0 as wireless card, you replace wlan0 with eth0<br />
<br />
wlan_et0="eth0 essid MyEssid key s:masterpassword""<br />
<br />
<br />
<br />
----<br />
<br />
I added the section in ndiswrapper about no internet -- this also could be adapted for other sections, or just generalized at the beginning. --[[User:Majikstreet|Majikstreet]] 13:30, 15 September 2006 (PDT)<br />
<br />
----<br />
<br />
I made some changes to the rt2500 driver section, since the newer driver rt2500pci works with wpa supplicant. Somebody could probably clean that section up, and write it better, but I don't really think I know enough to be qualified.<br />
<br />
----<br />
<br />
i added a link to the autowifi page under the 3rd party tools. Black Mage<br />
<br />
----<br />
<br />
Does anybody else besides me think that it would be helpful to mention modprobe -l to get a list of loaded modules/drivers and that ath9k is already included in the kernel at the beginning of ''First steps'' or ''Drivers and Firmware'' section? In my case (I have a Thinkpad x61) I didn't have to install any additional drivers, so I could proceed immediately to Manual setup and everything worked perfectly. --[[User:Bhobbit|Bhobbit]] 01:03, 7 June 2009 (EDT)</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Apache_OpenOffice&diff=69853Apache OpenOffice2009-06-02T20:09:24Z<p>Bhobbit: go-oo -> go-openoffice</p>
<hr />
<div>[[Category:Office (English)]]<br />
[[Category:HOWTOs (English)]]<br />
<br />
{{i18n_links_start}}<br />
{{i18n_entry|English|OpenOffice}}<br />
{{i18n_entry|Italiano|OpenOffice_(Italiano)}}<br />
{{i18n_entry|Ελληνικά|OpenOffice (Ελληνικά)}}<br />
{{i18n_entry|简体中文|OpenOffice.org_(简体中文)}}<br />
{{i18n_entry|Português|OpenOffice_(Português)}}<br />
{{i18n_entry|Türkçe|OpenOffice_(Türkçe)}}<br />
{{i18n_links_end}}<br />
==Introduction==<br />
[http://www.openoffice.org/ OpenOffice.org] is a leading open-source office software suite for word processing, spreadsheets, presentations, graphics, databases and more. <br />
<br />
Arch offers 3 trees of binary packages for OpenOffice with different package names:<br />
<br />
'''openoffice-base'''<br />
<br />
This will always be the last released stable version of OpenOffice. <br><br />
Current version: 3.0.1 <br><br />
start it with "soffice" or from Desktop menu <br><br />
<br />
'''openoffice-base-beta'''<br />
<br />
This package will be only present when a new release is not far away. It will be the alpha, beta, and release candidates packages for the next stable release. <br><br />
Current version: 3.1.0_ooo310_m01 (way to =3.1.0rc1) (versions branched from DEV300_m40 that will lead to next stable 3.1.x release) <br><br />
start it with "soffice-beta" or from Desktop menu <br><br />
It's safe to install it together with the stable and devel version.<br><br />
Please test it carefully and report upstream bugs to OpenOffice and packaging bugs in our flyspray <br><br />
see http://wiki.services.openoffice.org/wiki/OOoRelease31 for roadmap<br />
<br />
'''openoffice-base-devel'''<br />
<br />
This packages will be updated from time to time and is a playground for the packager and for testing latest features. Please test and file upstream issues at http://www.openoffice.org/issues/query.cgi<br><br />
Current version: 3.1_dev300_m41 / snapshot DEV300_m41 (snapshots past branching the 3.1 stable tree that will lead to 3.2 release and beyond) <br><br />
start it with "soffice-dev" or from Desktop menu <br><br />
It's safe to install it together with the stable and beta version<br />
{{Note|If you play with more than one openoffice-base version it's highly recommended to always backup your<br />
configuration directory ~/.openoffice{2,3} !}}<br />
<br />
'''go-openoffice'''<br />
<br />
In addition, there is a package for go-oo in the extra repository, which includes enhancements and features found in versions of openoffice.org available in Ubuntu, OpenSuSE and other distributions. For users of Arch switching from other distributions go-openoffice may be more familiar to them.<br />
<br />
==Installation==<br />
* First, install a Java Runtime Environment (optional, highly recommended):<br />
# pacman -S openjdk6 or<br />
# pacman -S jre<br />
* Also, make sure that fonts are installed (otherwise you will see only rectangles):<br />
# pacman -S artwiz-fonts ttf-ms-fonts<br />
* Download the base for stable and/or beta and/or devel and/or go-oo:<br />
# pacman -S openoffice-base openoffice-base-beta openoffice-base-devel go-openoffice<br />
<br />
<br />
===Extension management and spell checking for OpenOffice 3.x===<br />
* see [http://extensions.services.openoffice.org/getmore?cid=920794 OpenOffice Extension site]<br />
* Old openoffice-spell packages are obsolete. <br />
* Spell checking is done via new [http://extensions.services.openoffice.org/dictionary extensions]. There are three ways to install such a extension:<br />
* 1) Use the Extension manager from OOo menu for download and installation - installs only for the user into his ~/.openoffice.org/3/user/uno_packages/cache<br />
* 2) Download the extension and install it using "unopkg add extension" for the user or<br />
* 3) Download the extension and install it using "unopkg add --shared extension" for every user on the system (requires root permission)<br />
* 4) The Arch package is now shipped with some dictionaries and these get deployed automatically. Check Extension manager if your language is already there.<br />
<br />
If spellcheck does not work for you immediately after install, check the directory<br />
/opt/openoffice/share/extension/install<br />
Inside there should be several files called <br />
/opt/openoffice/share/extension/install/dict-<LANG>.oxt<br />
Use the Extension Manager to add your language dictionary; this often enables spellcheck.<br />
<br />
====French dictionary====<br />
As of openoffice 3.0.0-2 the french dictionary is buggy due to a character encoding problem. To solve this problem, first execute the following commands (you'll need '''zip''' and '''unzip''' packages):<br />
$ cp /opt/openoffice/share/extension/install/dict-fr.oxt dict-fr.oxt<br />
$ unzip dict-fr.oxt -d dict-fr<br />
$ cd dict-fr<br />
$ iconv -f ISO-8859-15 -t UTF-8 dictionaries.xcu > dictionaries.xcu.utf<br />
$ mv dictionaries.xcu.utf dictionaries.xcu<br />
$ zip ../dict-fr.oxt *<br />
$ cd ../<br />
$ rm -r dict-fr<br />
then go in the openoffice extension manager (Tools menu) and install the dictionary from the new dict-fr.oxt file.<br />
<br />
===Set OOo environment variable===<br />
OpenOffice2 introduced the ability to use several toolkits for drawing and integrates into different desktop environments in a clean way. To choose by hand, you need to set the OOO_FORCE_DESKTOP environment variable.<br />
<br />
To run OpenOffice.org in GTK2 mode, you can issue (using bash):<br />
# OOO_FORCE_DESKTOP=gnome soffice<br />
To run OpenOffice.org in QT/KDE3 mode, you can issue (using bash):<br />
# OOO_FORCE_DESKTOP=kde soffice<br />
<br />
{{Box Note | As KDE look will be removed in Openoffice3 it is highly recommended to use the GTK mode for all users. }}<br />
<br />
====Configure globally====<br />
To configure the look for anytime OpenOffice gets started, you can export the variable in one of the startup scripts, either system wide or for a specific user. <br />
<br />
Put<br />
export OOO_FORCE_DESKTOP=gnome<br />
in ~/.bashrc, ~/.config/openbox/autostart.sh, or similar to configure for one user. <br />
<br />
For all users, create the file "/etc/profile.d/openoffice.sh", put the export in there, and make the file executable.<br />
# chmod +x /etc/profile.d/openoffice.sh<br />
You could also put the export in /etc/profile directly, or in rc.local, but this is less clean.<br />
<br />
This export is obsolete for all OOo versions >= 3.0.0-2. Since that version the official package ships its own /etc/profile.d/openoffice.sh!<br />
<br />
====Environment variable scripts====<br />
If for whatever reason you don't want to configure the look globaly, as a non-gnome/kde user you may run into problems when trying to add the environment variable to the command in a *box menu, as such menus don't seem to like environment variables.<br />
<br />
This script will run openoffice using the GTK look while still accepting command line options like -writer.<br />
#!/bin/sh<br />
<br />
#### openoffice-gtk - A script to start openoffice with the GNOME/GTK environment<br />
<br />
OOO_FORCE_DESKTOP=gnome /opt/openoffice/program/soffice "$@"<br />
<br />
Just use this script as a command (e.g, /usr/bin/openoffice-gtk) for your menu or whatever other sort of launcher you use.<br />
<br />
{{Box Note | If you open a file in a filemanager, for example Thunar, the default look will be used, as the file association will not use your personal script. }}<br />
<br />
=== KDE4 look & feel for OpenOffice ===<br />
OOO_FORCE_DESKTOP=gnome never did the trick for me. A good workaround is to set (as root):<br />
export SAL_GTK_USE_PIXMAPPAINT=1<br />
into /etc/profile. In KDE4 systemsettings, make sure "use my KDE style in GTK applications" is selected in Appearance > GTK styles and fonts (you must install gtk-qt-engine first).<br />
<br />
=== Adding media support to OpenOffice.org 2 ===<br />
<br />
If you want to be able to use sound and video in OpenOffice.org Impress presentations, you need to install the [[Java Media Framework]] and [[Java_Media_Framework#Adding_media_support_to_OpenOffice.org|configure OpenOffice.org to use it]]<br />
<br />
==Running OpenOffice==<br />
<br />
If you want to run a specific module of OpenOffice.org (instead of the soffice default), for example the word processor (Write), spreadsheet application (Calc) or presentation program (Impress), check for the following script front-ends:<br />
<br />
Writer<br />
/opt/openoffice/program/swriter<br />
<br />
Calc<br />
/opt/openoffice/program/scalc<br />
<br />
Impress<br />
/opt/openoffice/program/simpress<br />
<br />
Math (Formula Editor)<br />
/opt/openoffice/program/smath<br />
<br />
Base (Database frontend)<br />
/opt/openoffice/program/sbase<br />
<br />
Printer Administration (Recommended to run as root)<br />
/opt/openoffice/program/spadmin<br />
<br />
==Known Problems==<br />
* extension handling in versions >=3.0<br />
* qt look'n feel since kde4 release<br />
* Rendering problems with some dark GTK themes and gtk-qt-engine. For a dirty fix, see [http://aur.archlinux.org/packages.php?ID=22383 openoffice-dark-gtk-fix] on the AUR. This also sets OOO_FORCE_DESKTOP=gnome.</div>Bhobbithttps://wiki.archlinux.org/index.php?title=Xorg&diff=69832Xorg2009-06-02T04:03:10Z<p>Bhobbit: /* hwd */</p>
<hr />
<div>[[Category:X Server (English)]]<br />
[[Category:HOWTOs (English)]]<br />
<br />
{{i18n_links_start}}<br />
{{i18n_entry|Dansk|Xorg (Dansk)}}<br />
{{i18n_entry|English|Xorg}}<br />
{{i18n_entry|Ελληνικά|Xorg (Ελληνικά)}}<br />
{{i18n_entry|Español|Configurando Xorg (Español)}}<br />
{{i18n_entry|Polski|Xorg_(Polski)}}<br />
{{i18n_entry|Русский|Xorg (Русский)}}<br />
{{i18n_entry|Česky|Xorg (Česky)}}<br />
{{i18n_entry|Italiano|Xorg (Italiano)}}<br />
{{i18n_entry|简体中文|Xorg (简体中文)}}<br />
{{i18n_entry|Türkçe|Xorg (Türkçe)}}<br />
{{i18n_links_end}}<br />
<br />
== Introduction ==<br />
<br />
'''Xorg''' is the public, open-source implementation of the X11 X Window System. (See the [http://en.wikipedia.org/wiki/X.Org_Server X.org Wikipedia Article] or [http://wiki.x.org/wiki/ X.org] for details.) Basically, if you want a GUI atop Arch, you will want xorg.<br />
<br />
==Installing Xorg==<br />
<br />
Before beginning, make sure you do the following:<br />
#Make sure that [[pacman]] is configured and refreshed.<br />
#If you are running another X server you can close it now. (Ctrl+Alt+Backspace)<br />
#Make a note about third-party drivers (e.g., nVidia or ATI drivers). <br />
<br />
First let us install the complete 'xorg' group:<br />
# pacman -S xorg<br />
<br />
The default 'vesa' driver is merely a fallback (not accelerated and doesn't support many resolutions), so you will need a proper video driver too. You can type this command to list all the video drivers available:<br />
# pacman -Ss xf86-video<br />
<br />
(However, if you have an nVidia card, you may install the package "nvidia" instead, if you don't mind proprietary drivers)<br />
<br />
Look for the appropriate driver for your card and install it with {{Codeline|pacman -S}}. To check your card, if hwd is installed, run:<br />
$ hwd -s<br />
or run:<br />
$ lspci | grep "VGA"<br />
<br />
If Xorg installed OK, it's time to make {{Filename|xorg.conf}}.<br />
<br />
==Configuring xorg==<br />
<br />
Before you can run xorg, you need to configure it so that it knows about your graphics card, monitor, mouse and keyboard. There are several methods of automating the process:<br />
<br />
===Without xorg.conf===<br />
<br />
The latest Xorg does a good job at detecting all your hardware with the help of [[HAL]]. So using an {{Filename|xorg.conf}} is optional now. Even if you need one, it is better to start with no xorg.conf and then add sections you need.<br />
<br />
Since xorg depends on hal, install hal if you haven't done it yet:<br />
# pacman -S hal<br />
<br />
Add hal to DAEMONS array of {{Filename|/etc/[[rc.conf]]}}:<br />
<br />
Start hal:<br />
# /etc/rc.d/hal start<br />
<br />
Then try starting X:<br />
$ startx<br />
<br />
If the X started and you want to have a base {{Filename|xorg.conf}} file, you can now [[#From the Xorg.0.log file|create it from Xorg.0.log file]]<br />
<br />
If it is not detecting proprietary drivers like nvidia, add a minimalistic {{Filename|xorg.conf}} like the following:<br />
Section "ServerLayout"<br />
Identifier "Layout0"<br />
Screen 0 "Screen0" 0 0<br />
EndSection<br />
<br />
Section "Files"<br />
FontPath "/usr/share/fonts/local/"<br />
EndSection<br />
<br />
Section "Device"<br />
Identifier "Device0"<br />
Driver "nvidia"<br />
VendorName "NVIDIA Corporation"<br />
BoardName "GeForce Go 7300"<br />
EndSection<br />
<br />
Section "Screen"<br />
Identifier "Screen0"<br />
Device "Device0"<br />
EndSection<br />
<br />
====Setting non-us keyboard without xorg.conf====<br />
<br />
# cp /usr/share/hal/fdi/policy/10osvendor/10-keymap.fdi /etc/hal/fdi/policy/<br />
Then open {{filename|/etc/hal/fdi/policy/10-keymap.fdi}} and edit "us" in <code>input.xkb.layout</code> to what you want and, if necessary, edit <code>input.xkb.variant</code> too.<br />
<br />
The command<br />
# setxkbmap pl <br />
(with your keyboard layout instead of pl) executed in X should switch to your keyboard.<br />
To make it permanent you can e.g. add this command to {{filename|~/.xinitrc}} file (before starting the window manager).<br />
<br />
===hwd===<br />
<br />
{{Warning|hwd is [http://www.archlinux.org/pipermail/arch-general/2008-December/002833.html no longer supported] and has been moved to [[AUR]]. Please use <tt>X -configure</tt>.}}<br />
<br />
{{Note | hwd has been updated (ver. 5.5) to work with xorg-server-1.5.x and 1.6.x. Currently, it disables HAL-based input device hotplugging and instead generates a traditional {{Filename|xorg.conf}} including input devices.}}<br />
<br />
Perhaps the easiest way of getting Xorg up and running quickly is to use <tt>hwd</tt>, a tool written by users in the Arch Linux community. It's basically a hardware-detection tool that has multiple uses, one of which is setting up an X server. Fortunately, hwd is much more streamlined than <tt>xorgconf</tt> and doesn't require any input at all.<br />
<br />
First, install the <tt>hwd</tt> package:<br />
# pacman -S hwd<br />
<br />
Now simply run the following command as root to generate a default {{Filename|xorg.conf}} file:<br />
# hwd -xa<br />
<br />
This will overwrite any existing {{Filename|/etc/X11/xorg.conf}} file with a practical set of defaults, based on what <tt>hwd</tt> detected for your hardware.<br />
<br />
Alternatively, you can generate a sample Xorg config ({{Filename|/etc/X11/xorg.conf.hwd}}) without overwriting your existing settings. To do so, run <tt>hwd</tt> with the {{Codeline|-x}} flag instead:<br />
# hwd -x<br />
<br />
Sample result:<br />
/etc/X11/xorg.conf.ati<br />
/etc/X11/xorg.conf.vesa<br />
<br />
Your sample file(s) ready, rename 'xorg.conf'.<br />
If unsure first try 'vesa' (default).<br />
<br />
To use the sample config(s), you must manually rename it. Sample:<br />
# mv /etc/X11/xorg.conf.vesa /etc/X11/xorg.conf<br />
<br />
AD: In my experience hwd creates XF86Config-4 file and if there is not {{Filename|xorg.conf}} present Xorg uses it automatically.<br />
<br />
===Xorg -configure===<br />
You can also use<br />
# Xorg -configure<br />
or<br />
# X -configure<br />
The command automatically generate a default xorg.conf.new file in the current directory. You can check it by:<br />
# X -config ./xorg.conf.new<br />
and copy it as {{Filename|/etc/X11/xorg.conf}}.<br />
<br />
===nvidia-xconfig===<br />
nVidia users can also use<br />
# nvidia-xconfig<br />
when they have official nvidia drivers [[NVIDIA|installed]].<br />
<br />
Comment the line:<br />
Load "type1"<br />
<br />
in the {{Codeline|Module}} section since recent versions of xorg-server do not include the type1 font module (completely replaced by freetype).<br />
<br />
===From the Xorg.0.log file===<br />
If you managed to start x without any xorg.conf file, you can find the default xorg configuration in {{Filename|/var/log/Xorg.0.log}}. Just copy the text between lines like<br />
(==) --- Start of built-in configuration ---<br />
and<br />
(==) --- End of built-in configuration ---<br />
to your new xorg.conf file.<br />
<br />
==Editing xorg.conf==<br />
<br />
You may wish to edit the config after it's been generated. To open in your favourite text-editor, such as Vim (you need root privileges):<br />
<br />
# vim /etc/X11/xorg.conf<br />
<br />
or use Xorg (xorg-server version < 1.6) Configuration toolkit:<br />
<br />
# xorgcfg -textmode<br />
<br />
===Monitor Settings===<br />
<br />
Depending on your hardware, Xorg may fail to detect your monitor capabilities correctly, or you may simply wish to use a lower resolution than your monitor is capable of. You might want to look up the following values in your monitor's manual before setting them.<br />
The following settings are specified in the Monitor section:<br />
<br />
====Horizontal Sync====<br />
<br />
HorizSync 28-64<br />
<br />
====Refresh Rate====<br />
<br />
VertRefresh 60<br />
<br />
The following are specified in the Screen section:<br />
<br />
====Color Depth====<br />
<br />
Depth 24<br />
<br />
====Resolution====<br />
<br />
Modes "1280x1024" "1024x768" "800x600"<br />
<br />
====Multi-monitor setups====<br />
<br />
The easiest way to achieve a working multi-monitor setup is using xrandr after X starts. First, run (from any account):<br />
<br />
xrandr -q<br />
<br />
This will list all your available video outputs, with some information about them. Assume your output names are VGA-0, DVI-0 and S-video. Then, to merge screens connected to DVI-0 and VGA-0 outputs, you just need to run:<br />
<br />
xrandr --output DVI-0 --right-of VGA-0<br />
<br />
If this command works for you, just add it to your [[xinitrc]] file.<br />
<br />
=== Keyboard Settings ===<br />
<br />
Xorg may fail to detect your keyboard correctly. This might give problems with your keyboard layout or keyboard model not being set correctly.<br />
<br />
To see a full list of keyboard models, layouts, variants and options, open:<br />
<br />
/usr/share/X11/xkb/rules/xorg.lst<br />
<br />
==== Input hotplugging with xorg-server 1.5 ====<br />
<br />
Normally xorg-server 1.5 tries to configure your keyboard using the new xf86-input-evdev driver (which in turn uses dbus and HAL) instead of using your configuration settings in xorg.conf. This may result in an undesired auto-configured keyboard layout. The fastest workaround is to disable the hotplugging mechanism by adding the following section to your xorg.conf:<br />
<br />
Section "ServerFlags"<br />
Option "AutoAddDevices" "False"<br />
EndSection<br />
<br />
{{Box Note|This will disable Xorg hotplugging for '''all''' input devices and revert to the same behavior as xorg-server 1.4.}}<br />
<br />
For more information see [[Xorg input hotplugging]].<br />
<br />
==== Keyboard Layout ====<br />
<br />
{{Box Note|If you are using the xorg-server 1.5 series, please see the keyboard layout section in [[Xorg input hotplugging]].}}<br />
<br />
To change the keyboard layout, use the XkbLayout option in the keyboard InputDevice section. For example, if you have a keyboard with English layout:<br />
<br />
Option "XkbLayout" "gb"<br />
<br />
To be able to easily switch keyboard layouts, for example between a US and a Swedish layout use this instead:<br />
<br />
Option "XkbLayout" "us, se"<br />
Option "XkbOptions" "grp:caps_toggle"<br />
<br />
This makes your Caps Lock key switch between the different layouts. This is mainly useful if you don't run a Desktop Environment which takes care of keyboard layouts for you.<br />
<br />
==== Keyboard Model ====<br />
<br />
To change the keyboard model, use the XkbModel option in the keyboard <br />
InputDevice section. For example, if you have a Microsoft Wireless Multimedia Keyboard:<br />
<br />
Option "XkbModel" "microsoftmult"<br />
<br />
==== Problem with your Apple Keyboard? ====<br />
More information can be found [[Apple Keyboard|here]].<br />
<br />
===Display Size/DPI===<br />
<br />
In order to get correct sizing for fonts, the display size must be set for your desired DPI.<br />
<br />
First thing you may try is Xorg autodetection of display size and DPI settings with [http://en.wikipedia.org/wiki/Display_Data_Channel DDC].<br />
<br />
In {{Filename|/etc/X11/xorg.conf}}:<br />
...<br />
Section "Module"<br />
# support for Data Display Channel. Allows to query the monitor capabilities via the video card<br />
Load "ddc"<br />
# serial bus over which you speak the ddc protocol to get info from the monitor<br />
Load "i2c"<br />
...<br />
Section Screen<br />
...<br />
DefaultColorDepth 24<br />
SubSection "Display"<br />
Depth 24<br />
Modes "1280x1024" "1152x864" "1024x768" "800x600" "640x480"<br />
EndSubSection<br />
...<br />
And do not write any {{Codeline|Modeline}} or {{Codeline|DisplaySize}} settings. Sometimes it works fine, otherwise you need to set up it manualy.<br />
<br />
One way to set it up is to pass an argument directly to the X (Xorg) binary. In {{Filename|/etc/X11/xinit/xserverrc}} add the {{Codeline|"-dpi 96"}} part as follows:<br />
exec /usr/bin/X -nolisten tcp '''-dpi 96'''<br />
<br />
Alternatively, going back to the {{Filename|/etc/X11/xorg.conf}} file, in the section {{Codeline|Monitor}} put in your display size in mm:<br />
<br />
Section "Monitor"<br />
...<br />
DisplaySize 336 252 # 96 DPI @ 1280x960<br />
...<br />
EndSection<br />
<br />
<br />
The formula for calculating the {{Codeline|DisplaySize}} values is Width (in inches) x 25.4 / DPI and Height (in inches) x 25.4 / DPI. If you're running Xorg with a resolution of 1024x768 and want a DPI of 96, use 1024 x 25.4 / 96 and 768 x 25.4 / 96. Round numbers down. (xorg expects width/height specifications to be given in milimeters. There are 25.4 milimeters per inch, thus the need to multiply by 25.4)<br />
<br />
# calc: (x|y)pixels * 25.4 / dpi<br />
# DisplaySize 168 126 # 96 DPI @ 640x480<br />
# DisplaySize 210 157 # 96 DPI @ 800x600<br />
# DisplaySize 269 201 # 96 DPI @ 1024x768<br />
# DisplaySize 302 227 # 96 DPI @ 1152x864<br />
# DisplaySize 336 252 # 96 DPI @ 1280x960<br />
# DisplaySize 336 210 # 96 DPI @ 1280x800 (non 4:3 aspect)<br />
# DisplaySize 339 271 # 96 DPI @ 1280x1024 (non 4:3 aspect)<br />
# DisplaySize 370 277 # 96 DPI @ 1400x1050<br />
# DisplaySize 380 238 # 96 DPI @ 1440x900 (non 4:3 aspect)<br />
# DisplaySize 420 315 # 96 DPI @ 1600x1200<br />
# DisplaySize 444 277 # 96 DPI @ 1680x1050 (non 4:3 aspect)<br />
# DisplaySize 506 315 # 96 DPI @ 1920x1200 (non 4:3 aspect)<br />
<br />
<br />
In case X ignores your {{Codeline|DisplaySize}} setting ([https://bugs.freedesktop.org/show_bug.cgi?id=9758 known bug]) add the following line in the {{Codeline|Device}} section.<br />
Option "NoDDC" "true"<br />
<br />
For nVidia drivers you may have to disable automatic detection of DPI to set it manually. There is also an easier way to set DPI on these cards. Either or both of the following lines can be set in the device section for your nVidia card.<br />
<br />
Option "UseEdidDpi" "false"<br />
Option "DPI" "96 x 96"<br />
<br />
If X still ignores your DPI settings, and you have an RandR compliant video driver, you can use<br />
xrandr --dpi 96<br />
to manually set the DPI. You can add that command to your {{Filename|.xinitrc}} to have the DPI settings applied when you start X manually, and if you are using a display manager, like KDM, you can add it to your display manager's X statup file. For KDM, that would be somewhere like {{Filename|/usr/share/config/kdm/Xstartup}}.<br />
<br />
Results can be checked by issuing the following command, which should return 96x96 dots per inch if you set DPI @ 96:<br />
$ xdpyinfo | grep -B1 dot<br />
<br />
===Proprietary Drivers===<br />
<br />
If you wish to use third-party graphics drivers, do check that the X server runs OK first. Xorg should run smoothly without official drivers, which are typically needed only for advanced features such as 3D-accelerated rendering for games, dual-screen setups, and TV-out. Refer to the [[NVIDIA]] and [[ATI]] wikis for help with driver installation.<br />
<br />
===Fonts===<br />
<br />
There some tips for setting up fonts in [[Xorg Font Configuration]].<br />
<br />
=== Sample Xorg.conf Files ===<br />
Anyone who has an Xorg.conf file written up that works, go ahead and post a link to it here for others to look at! Please don't inline the entire conf file; upload it somewhere else and link. Thanks!<br />
* raskolnikov (via unichrome and synaptics drivers): http://athanatos.free.fr/Arch/xorg.conf<br />
* Mr.Elendig (nvidia with composite and "stuff") http://arch.har-ikkje.net/configs/etc/X11/xorg.conf<br />
<br />
==Running Xorg==<br />
<br />
This is done simply by typing:<br />
$ startx<br />
or<br />
$ xinit<br />
<br />
The default X environment is rather bare, and you will typically seek to install window managers or desktop environments to supplement X. <br />
<br />
To test the config file you have created:<br />
$ X -config ''<your config file>''<br />
<br />
If a problem occurs, then view the log at {{Filename|/var/log/Xorg.0.log}}. Be on the lookout for any lines beginning with {{Codeline|(EE)}} which represent errors, and also {{Codeline|(WW)}} which are warnings that could indicate other issues.<br />
<br />
'''Please Note:''' Using startx or xinit requires a {{Filename|[[xinitrc|~/.xinitrc ]]}} file, so that X knows what to run when it starts. Your best option is to copy {{Filename|/etc/skel/.xinitrc}} to your home directory and edit it. Comment out the {{Codeline|exec}} lines you don't want, and add or uncomment one for the WM you want to use. If you are using GNOME it is best to start GNOME through gdm to avoid HAL permission problems.<br />
<br />
In addition, you can also install twm and xterm (via pacman), which will be used as a fallback if {{Filename|~/.xinitrc}} does not exist (as stated in {{Filename|/etc/X11/xinit/xinitrc}}).<br />
<br />
==X startup (/usr/bin/startx) tweaking==<br />
For X's option reference see:<br />
$ man Xserver<br />
<br />
<br />
The following options have to be appended to the variable {{Codeline|"defaultserverargs"}} in the {{Filename|/usr/bin/startx}} file:<br />
* Prevent X from listening on tcp:<br />
-nolisten tcp<br />
{{Note | This seems to be the default option now in {{Filename|/etc/X11/xinit/xserverrc}}.}}<br />
<br />
<br />
* Getting rid of the gray weave pattern while X is starting and let X set a black root window:<br />
-br<br />
{{Note | There seems to be no need for that in recent releases of Xorg.}}<br />
<br />
<br />
* Enable deferred glyph loading for 16 bit fonts:<br />
-deferglyphs 16<br />
<br />
Note: If you start X with kdm, the startx script does not seem to be executed. X options must be appended to the variable {{Codeline|"ServerArgsLocal"}} or {{Codeline|"ServerCmd"}} in the {{Filename|/usr/share/config/kdm/kdmrc}} file. By default kdm options are:<br />
ServerArgsLocal=-nolisten tcp<br />
ServerCmd=/usr/bin/X<br />
<br />
== Changes with modular Xorg ==<br />
<br />
=== Most Common Packages ===<br />
<br />
Make sure you install drivers for mouse, keyboard and videocard. For mouse and keyboard, '''xf86-input-keyboard''' and '''xf86-input-mouse''' should get installed. Other '''xf86-input-*''' packages are available for different input devices.<br />
<br />
For the videocard, find out which driver is required and install the right '''xf86-video-*''' package. ATI and Nvidia users may wish to install the non-free drivers for their hardware instead ([[NVIDIA]], [[ATI]]).<br />
<br />
To install all drivers in one run, the '''xorg-input-drivers''' and '''xorg-video-drivers''' are available.<br />
<br />
=== OpenGL 3D Acceleration ===<br />
<br />
X.Org 7.0 on Arch Linux uses a modular design for mesa, the OpenGL rendering system. Several implementations are available:<br />
* libgl-dri: Open-source DRI OpenGL implementation. Falls back to software rendering when no DRI driver is installed<br />
* some other driver providing libGL (ati, nvidia)<br />
<br />
When pacman installs an application that needs mesa, it will install one of these packages. To be sure about the right library for your setup, install the library you want prior to installing Xorg. Installing the right package afterwards is also possible, though this gives some dependency errors sometimes, which can be ignored with the -d switch.<br />
<br />
=== Glxgears and Glxinfo ===<br />
<br />
These apps are included in the mesa package.<br />
<br />
=== Changed paths (and configuration) ===<br />
<br />
'''See this entry for additional upgrade info:''' http://www.archlinux.org/blog/2006/01/02/how-to-upgrade-xorg/<br />
<br />
Modular X.Org 7 installs everything in <tt>/usr</tt>, where the older versions installed in <tt>/usr/X11R6</tt>. Several configuration files need updates:<br />
* {{Filename|/etc/X11/xorg.conf}}<br />
** Fontpaths live in /usr/share/fonts now<br />
** RGB database is in /usr/share/X11/rgb<br />
** Module path is /usr/lib/xorg/modules<br />
<br />
Also note that some X configuration tools might stop working. The easiest way to configure X.org is by installing the correct driver packages and running {{Codeline|Xorg -configure}}, which results in a {{Filename|xorg.conf.new}} which only needs modification in the resolutions, mouse configuration and keyboard layouts.<br />
<br />
Some packages have hard-coded references to <tt>/usr/X11R6</tt>. These packages need fixing. In the meantime, look what packages install files in <tt>/usr/X11R6</tt>, uninstall those, make a symlink from <tt>/usr</tt> to <tt>/usr/X11R6</tt> and reinstall the affected packages. Another option is to move the contents of <tt>/usr/X11R6</tt> to <tt>/usr</tt> and make the symlink.<br />
<br />
Or you can just add a second module path via:<br />
ModulePath "/usr/X11R6/lib/modules"<br />
This works e.g. for Nvidia 76.76.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Xorg "can't see" the resolutions your monitor supports ===<br />
I found myself in a situation where if I used one of my monitors (a gnr ts902), Xorg would only present me with the options 640x480 and 320x480 which of course was less than I desired. After a lot of research I found through read-edid (in [[AUR]]) that part of my EDID was corrupt and so I could only read my HorizSync with read-edid. This fortunately was enough and after adding the right HorizSync line to the xorg.conf's Monitor section (I didn't have to add VertRefresh) I restarted X to see the right resolution :)<br />
<br />
note: I'm not sure if<br />
<br />
Option "ModeValidation" "NoEdidModes"<br />
Option "UseEdid" "false"<br />
<br />
in Device section of xorg.conf are needed as well; too lazy now to test without them :)<br />
<br />
=== Keyboard Problems ===<br />
<br />
Auto-generated xorg.conf files may cause you problems. If you cannot get to tty1 by holding CTRL-ALT and pressing F1 or cannot get the £ sign for gb people, check to see if the following entries are in your /etc/X11/xorg.conf:<br />
<br />
Option "XkbLayout" "uk" #"uk" is not a real layout, look in /usr/share/X11/xkb/symbols/ for a list of real ones.<br />
#Try "gb" if you want a UK keyboard layout<br />
Option "XkbRules" "xfree86" #this should be "xorg"<br />
Option "XkbVariant" "nodeadkeys" #This line is also known to cause the problems described, try commenting it out.<br />
<br />
To switch between layouts with Alt+Shift:<br />
Option "XkbOptions" "grp:alt_shift_toggle,grp_led:scroll"<br />
<br />
===A Quick Fix for the Bitstream-Vera Conflict===<br />
If you see a message that ttf-bitstream-vera conflicts with xorg:<br />
#Exit the pacman session by answering no.<br />
#Run <code>pacman -Rd xorg</code><br />
#Run <code>pacman -Syu</code><br />
#Run <code>pacman -S xorg</code><br />
#Update your paths in /etc/X11/xorg.conf<br />
<br />
===A Quick Fix for file conflicts in /usr/include===<br />
If you see messages about file conflicts in /usr/include/X11 and /usr/include/GL:<br />
#Run <code>rm /usr/include/{GL,X11}</code><br />
#Run <code>pacman -Su</code><br />
The symlinked directories removed by this operation are replaced by real directories in the new xorg package, causing these file conflicts to appear.<br />
<br />
=== libgl-dri conflicts ===<br />
<br />
(Note below, that nvidia-legacy has been replaced by nvidia-71xx or nvidia-96xx. See [[NVIDIA | here]] for further details of which driver to use.)<br />
<br />
If you get a message similar to:<br />
:: libgl-dri conflicts with nvidia-legacy. Remove nvidia-legacy? [Y/n]<br />
this is due to the multiple OpenGL implementations explained in the OpenGL section above - pacman is attempting to install libgl-dri to satisfy this dependency, but also trying to upgrade your existing video driver, and they conflict. To solve, try:<br />
<br />
* Updating your video driver before a full system update: <br />
# pacman -S nvidia-legacy<br />
# pacman -Syu<br />
<br />
Or, if that doesn't work,<br />
* Remove your existing video driver, do the update, then reinstall your driver:<br />
# pacman -Rd nvidia-legacy<br />
# pacman -Syu<br />
# pacman -S nvidia-legacy<br />
:: nvidia-legacy conflicts with libgl-dri. Remove libgl-dri? [Y/n] '''Y'''<br />
<br />
=== Mouse wheel not working ===<br />
The "Auto" protocol doesn't seem to work properly in Xorg 7 any more. In the InputDevice section for your mouse, change:<br />
Option "Protocol" "auto"<br />
to<br />
Option "Protocol" "IMPS/2"<br />
or<br />
Option "Protocol" "ExplorerPS/2"<br />
<br />
=== Extra mouse buttons not working ===<br />
USB Mice users should read [[Get_All_Mouse_Buttons_Working]].<br />
<br />
Intellimouse (ExplorerPS/2) users might find their scroll and side buttons aren't behaving as they used to. Previously xorg.conf needed:<br />
Option "Buttons" "7"<br />
Option "ZAxisMapping" "6 7"<br />
and users also had to run xmodmap to get the side buttons working with a command like:<br />
xmodmap -e "pointer = 1 2 3 6 7 4 5"<br />
Now xmodmap is no longer required. Instead, make xorg.conf look like this:<br />
Option "Buttons" "5"<br />
Option "ZAxisMapping" "4 5"<br />
Option "ButtonMapping" "1 2 3 6 7"<br />
and the side buttons on a 7-button Intellimouse will work like they used to, without needing to run xmodmap.<br />
<br />
===Keyboard problems===<br />
Some keyboard layouts have changed. I wondered why:<br />
* I wasn't able to Ctrl+Alt+Fx to switch to console<br />
* I wasn't able to use layouts<br />
The problem was that the ''sk_qwerty'' layout doesn't exist anymore. I had to replace<br />
Option "XkbLayout" "us,sk_qwerty"<br />
with<br />
Option "XkbLayout" "us,sk"<br />
Option "XkbVariant" ",qwerty"<br />
<br />
Another thing to look for if your keyboard isn't properly functioning is the XkbRules option:<br><br />
You'll need to change<br />
Option "XkbRules" "xfree86"<br />
to<br />
Option "XkbRules" "xorg"<br />
<br />
==== AltGR (Compose Key) not working properly ====<br />
<br />
If, after the update, you can't use the AltGr key as expected any more, try adding this to your keyboard section:<br />
Option "XkbOptions" "compose:ralt"<br />
<br />
This is not the correct way to activate the AltGr Key on a German keyboard (for example, to use the '|' and '@' keys on German keyboards).<br />
Just choose a valid keyboard variant for it to work again, for example (the example is for a German keyboard):<br />
Option "XkbLayout" "de"<br />
Option "XkbVariant" "nodeadkeys"<br />
<br />
The solutions above don't work on an Italian keyboard. To activate the AltGr key on an Italian keyboard make sure you have the following lines set up properly:<br />
Driver "kbd"<br />
Option "XkbRules" "xorg"<br />
Option "XkbVariant" ""<br />
<br />
This might still not be enough for a swedish keyboard. Try the above, but with lv3 instead of compose. (Thank you wyvern!)<br />
That is:<br />
Option "XkbLayout" "se"<br />
Option "XkbVariant" "nodeadkeys"<br />
Option "XkbOptions" "lv3:ralt_switch"<br />
<br />
==== Can't set qwerty layouts using the setxkbmap command ====<br />
<br />
After the update, there aren't qwerty layouts as for example sk_qwerty. If you want to switch your present keyboard layout to any qwerty keyboard layout use this command:<br />
$ setxkbmap NAME_OF_THE_LAYOUT qwerty<br />
e.g.: for sk_qwerty use:<br />
$ setxkbmap sk qwerty<br />
<br />
After the update, trying the above command I had this message "Error loading new keyboard description".<br />
I find out that the xserver doesn't have the rights to write, execute, read in the directory /var/tmp<br />
So give the permissions to that directory. Restart the xserver and you will have your deadkeys back!<br />
Don't believe? Try out the code e.g.: it layout<br />
$ setxkbmap -layout it<br />
<br />
==== Setup French Canadian (old ca_enhanced) layout ====<br />
<br />
<br />
'''With disabled hotplugging'''<br />
<br />
Since the new Xorg changed the way it deals with keyboards, the following method will only work if you disable "hotplugging" : http://wiki.archlinux.org/index.php/Xorg_input_hotplugging<br />
<br />
With Xorg7, "ca_enhanced" is no more. You have to do a little trick to get the same layout that you are used to:<br />
Switch the old:<br />
Option "XkbLayout" "ca_enhanced"<br />
To:<br />
Option "XkbLayout" "ca"<br />
Option "XkbVariant" "fr"<br />
<br />
It will be similar with other layout, I presume. You can refer to Gentoo HowTo there: http://www.gentoo.org/proj/en/desktop/x/x11/modular-x-howto.xml<br />
<br />
<br />
'''Workaround'''<br />
<br />
I use a workaround so that I don't have to manually change the HAL fdi policies, as this is the new way of dealing with keymaps with the new Xorg. I use "setxkbmap" : http://wiki.archlinux.org/index.php/Xorg_input_hotplugging#Using_setxkbmap<br />
<br />
Change the X keyboard layout to french canadian with this command:<br />
<br />
#setxkbmap ca -variant fr<br />
<br />
<br />
To make it change automatically, you can try this: <br />
<br />
Created the file <br />
<br />
~.config/autostart/keymap.desktop<br />
<br />
and added this to it:<br />
<br />
[Desktop Entry]<br />
Encoding=UTF-8<br />
Version=0.9.4<br />
Type=Application<br />
Name=Keymap French Canadian<br />
Comment=<br />
Exec=setxkbmap ca -variant fr<br />
StartupNotify=false<br />
Terminal=false<br />
Hidden=false<br />
<br />
It works at least for XFCE4 and LXDE.<br />
<br />
=== Missing libraries ===<br />
* '''Help! I get an error message running my favourite app saying "libXsomething" doesn't exist!'''<br><br />
In most cases, all you need to do is take the name of the library (eg libXau.so.1), convert it all to lowercase, remove the extension, and pacman for it:<br />
# pacman -S libxau<br />
<br />
This will install the library you're missing, and all will be well again!<br />
<br />
=== Some packages fail to build and complain about missing X11 includes ===<br />
<br />
Just reinstall the packages xproto and libx11, even if they are already installed.<br />
<br />
=== Unable to load font '(null)' ===<br />
* '''Some programs don't work and say unable to load font `(null)'.'''<br><br />
These packages would like some extra fonts. Some programs only work with bitmap fonts.<br />
Two major packages with bitmap fonts are available, xorg-fonts-75dpi and xorg-fonts-100dpi. You don't need both; one should be enough. To find out which one would be better in your case, try this:<br />
<br />
$ xdpyinfo | grep resolution<br />
<br />
and grab what is closer to you (75 or 100 instead of XX)<br />
<br />
# pacman -S xorg-fonts-XXdpi<br />
<br />
<br />
<br />
=== After updating to xorg-server 1.5, KDE4 Konsole crashes and/or systray icons disappear on right click ===<br />
Replace<br />
Option "BackingStore" "True"<br />
by<br />
Option "BackingStore" "False"<br />
in /etc/X11/xorg.conf.<br />
<br />
=== Updating from testing version to extra (missing files) ===<br />
<br />
If you've updated from Xorg 7 in testing to Xorg 7 in extra and are finding that many files seem to be missing (including startx, /usr/share/X11/rgb.txt, and others), you may have lost many files due to the xorg-clients package splitting from a single package into many smaller sub packages. <br><br />
<br />
You need to reinstall all the packages that are dependencies of xorg-clients:<br />
# pacman -S xorg-apps xorg-font-utils xorg-res-utils xorg-server-utils \<br />
xorg-twm xorg-utils xorg-xauth xorg-xdm xorg-xfs xorg-xfwp \<br />
xorg-xinit xorg-xkb-utils xorg-xsm<br />
<br />
This should fix the problem.<br />
<br />
=== Problem with MIME types in various desktop environments ===<br />
<br />
If you noticed icons missing and can't click-open files in desktop environments, add the following lines to /etc/profile or your preferred init script and reboot.<br />
XDG_DATA_DIRS=$XDG_DATA_DIRS:/usr/share<br />
export XDG_DATA_DIRS<br />
<br />
=== DRI stops working with Matrox cards ===<br />
<br />
If you use a Matrox card and DRI stops working after upgrading to xorg7, try adding the line<br />
Option "OldDmaInit" "On"<br />
to the Device section that references the video card in xorg.conf.<br />
<br />
=== Cannot start any clients under Xephyr ===<br />
<br />
The client connections are rejected by the X server's security mechanism, you can find a complete explanation and solution in [http://wiki.debian.org/XStrikeForce/FAQ#howtoxnest].<br />
<br />
=== Cannot start X clients as root using "su" ===<br />
<br />
If you're getting "Client is not authorized to connect to server", try adding the line <br />
<br />
session optional pam_xauth.so<br />
<br />
to the file /etc/pam.d/su. <br />
pam_xauth will properly set environment variables and handle xauth keys.<br />
<br />
=== Cannot run in frambuffer mode===<br />
<br />
If the X fail to start with the following log messages:<br />
(WW) Falling back to old probe method for fbdev<br />
(II) Loading sub module "fbdevhw"<br />
(II) LoadModule: "fbdevhw"<br />
(II) Loading /usr/lib/xorg/modules/linux//libfbdevhw.so<br />
(II) Module fbdevhw: vendor="X.Org Foundation"<br />
compiled for 1.6.1, module version = 0.0.2<br />
ABI class: X.Org Video Driver, version 5.0<br />
(II) FBDEV(1): using default device<br />
<br />
Fatal server error:<br />
Cannot run in framebuffer mode. Please specify busIDs for all framebuffer devices<br />
<br />
then simply uninstalling <code>xf86-video-fbdev</code> will help.<br />
<br />
=== Ctrl-Alt-Backspace doesn't exit X ===<br />
==== Modification to /etc/X11/xorg.conf ====<br />
New xorg disables zapping with {{Keypress|Ctrl}}+{{Keypress|Alt}}+{{Keypress|Backspace}} by default. You can enable it by adding the following lines to {{Filename|/etc/X11/xorg.conf}}<br />
<br />
Section "ServerFlags"<br />
Option "DontZap" "false"<br />
EndSection<br />
<br />
and<br />
<br />
Option "XkbOptions" "terminate:ctrl_alt_bksp" <br />
<br />
to InputDevice section for keyboard<br />
<br />
==== If you use input hotplugging ====<br />
<br />
If you are using hal to manage your keyboard, you must add the following to {{Filename|/usr/share/hal/fdi/policy/10osvendor/10-keymap.fdi}} to enable this behavior.<br />
<br />
<merge key="input.xkb.options" type="string">terminate:ctrl_alt_bksp</merge><br />
<br />
Restart hal after making the modification.<br />
<br />
Another way is to add the following line to {{Filename|~/.xinitrc}} <br />
setxkbmap -option terminate:ctrl_alt_bksp<br />
<br />
== Links ==<br />
See also:<br />
<br />
* [[Enabling a DM]]<br />
* [[Start X at boot]]<br />
* [[Xorg Font Configuration]]<br />
* Proprietary Video Drivers<br />
** [[ATI]]<br />
** [[NVIDIA]]<br />
* [[Desktop Environment]]<br />
** [[KDE]]<br />
** [[GNOME]]<br />
** [[Xfce]]<br />
** [[Enlightenment]]<br />
** [[Fluxbox]]<br />
** [[Openbox]]<br />
** [[LXDE]]<br />
* [[Get All Mouse Buttons Working]]<br />
* [[Compiz Fusion]]<br />
<br />
== External Links ==<br />
<br />
* [http://en.wikipedia.org/wiki/X.Org_Server X.org Wikipedia Article]<br />
* [http://wiki.x.org/wiki/ X.org]</div>Bhobbit