Commit 4a14609f by DeX77

* make docs adoc

parent 8297765e
= About Frugalware
[quote, Eric S. Raymond]
_______________________________________________________________________________
Seeing this feast of wonderful code spread in front of me as a working
system was a much more powerful experience than merely knowing, intellectually,
that all the bits were probably out there. It was as though for years I'd been
sorting through piles of disconnected car parts - only to be suddenly
confronted with those same parts assembled into a gleaming red Ferrari,
door open, keys swinging from the lock and engine gently purring with
a promise of power...
________________________________________________________________________________
The aim of creating Frugalware was to help you do your work faster and simpler.
We hope you will like it. In this introduction, we would like to answer a few
questions which were asked in several interview with Miklos, the founder of
the project. You can reach the full list of articles that have been posted about
Frugalware http://frugalware.org/media[here].
== Short
Frugalware is a general purpose Linux distribution, designed for intermediate
users (who are not afraid of text mode).
== Long
'What branches does Frugalware have?'
``We have a -current and a -stable branch. The -current branch is updated
daily, and we provide security support for our -stable branch till the next
release, for approximately 6 months.''
'What is "The Frugalware Philosophy" about?'
``Briefly: simplicity, multimedia, design. We try to make Frugalware as simple
as possible while not forgetting to keep it comfortable for the user. We try to
ship fresh and stable software, as close to the original source as possible,
because in our opinion most software is the best as is, and doesn't need
patching.''
'What is the license of Frugalware?'
``The license of Frugalware itself stands for the license of the buildscripts
used for building Frugalware. That source is available under the GPL license
http://git.frugalware.org[here]. Frugalware's original init scripts were
written by Patrick J. Volkerding, creator of the Slackware Linux distribution.
We release out additions under the GPL, but Patrick J. Volkerding's code is
still under the BSD license. Frugalware also has a few side projects, like our
pacman-g2 package manager, the Frugalware installer an so on. They are available
under the GPL license, too. For more info about the license of the packages
included in Frugalware, refer to the /usr/share/doc/*/COPYING files.''
'What package manager does Frugalware use?'
``We have our own package manager, called pacman-g2. It stands for the second
generation of the pacman-g1 package manager, as it was originally based on Judd
Vinet's great work. The packages are simple .tar.bz2 files, pacman-g2 is
written in C, unlike Slackware's shellscript-based package manager (which may
be rather slow sometimes).''
'How does Frugalware manage updating obsolete packages?'
``We don't have any standalone program for updating packages as pacman-g2
manages this task too. To update your package database, use `pacman-g2 -Sy`,
and to update your packages according the just synchronized package database,
you use `pacman-g2 -Su`. To install package `foo` with the necessary
dependencies directly from one of our ftp servers, you should issue `pacman-g2
-S foo`. For more information, refer to the pacman-g2 man page.''
'Is there any community support available for Frugalware?'
``We have mailing lists, IRC channels and forums that can be used to
communicate with developers or with other users and to get help. You can reach
the list of mailing lists available http://frugalware.org/mailman/listinfo[here].
The IRC channels are on the Freenode network (server: `irc.freenode.net`), the
discussion forums are available http://forums.frugalware.org[here].''
'Is there any commercial support available for Frugalware?'
``No, there isn't for now, and currently it isn't planned, either.''
'For whom is Frugalware recommended to use?'
``Frugalware is designed for intermediate users. Installing Frugalware doesn't
require any magic, of course, but you should read some documentation if you don't
know what a partition, an MBR (Master Boot Record), etc. is.''
'How to become a developer?'
``Get involved! :) Download the FST (Frugalware Source Tree) using the `repoman
upd` command, which is available in the pacman-tools package. Then start to
play with the FrugalBuild scripts, for a skeleton, refer to the `/docs/skel`
directory. Try to improve them, or write a new one for a currently unsupported
program. Then open feature requests in the http://bugs.frugalware.org[Bug
Tracking System] and attach your patches. From this point everything will come
naturally to you :)''
'What do developers do?'
``In short, what they want to, if they play a square game. They may maintain
packages: building them if a newer version is available and update the
FrugalBuild scripts to work correctly against a newer version. They can
contribute a new build script for a previously non-existent package. They write
documentation, fix bugs, provides support, or anything else in connection with
the Frugalware community. If you want to help us, but you don't want to be a
developers, you may help in translating Frugalware to your or other language. And, of
course, we happily accept donations. :) More info link:getting-involved.html[here].''
'Who develops Frugalware?'
``An amazing group of volunteers, who are motived by the users to do so. They
also do it as a hobby, and they are always working on having up to date
knowledge to make Frugalware even better for you.''
'Is Frugalware specialized in a certain purpose?'
``No, it's a general purpose distribution, for desktops, mobile computers and
servers.''
'Do you plan to release a live cd?'
``Well, we have already a live cd, called FwLive. Currently it supports
only i686, but an x86_64 version is also under development. You can find
it in the standard release directories.''
'Does Frugalware support languages other than English?'
``Yes, it supports all languages supported by the packages. If the init
scripts, the setup or the documentation is not available in your language, then
it simply means they haven't yet been translated.''
'What about Asian languages?'
``Frugalware roughly supports Asian languages, but don't expect too much -
using UTF8 is not the default where it is possible.''
'What architectures does Frugalware support?'
``Currently we support x86 (Pentium Pro or higher), x86_64 (k8, aka. amd64)
platforms and arm''
'How are compressed the Frugalware packages ?'
``FPM packages were originally .tar.gz packages, then a bit later we
migrated to libarchive, which allowed bzip2 compression. Life was
good, but then lzma was came, and I added support for libarchive, though
others were not really interested in a migration, so we stick to
.tar.bz2. A few months ago libarchive got support for the xz format
(which is the successor of lzma), so we switched to it. pacman-g2 still
support .tar.gz and .tar.bz2 as well, and the package extension is .fpm
all the time to make it clear that it's a Frugalware package''
= Artwork requirements
== Introduction
This document details the requirements that must be met by all artwork
if it is to be accepted into the official Frugalware gallery.
== The rules
* All artwork must be licensed under the Free Art License 1.3
(link:http://artlibre.org/licence/lal/en/[full details]).
* Where the Frugalware logo appears, only the officially approved logo
may be used. Refer
link:http://frugalware.org/images/logo-new-big.png[here] for the logo.
NOTE: There is a newer SVG version available
http://frugalware.org/~devil505/artwork/[here].
* Artwork must be submitted in either SVG or XCF (The Gimp) format as
this allows for derivative works to be made without affecting the impact
of the original artwork. Examples of derivative works include wallpapers
in various sizes and height/width ratios, and/or KDM/GDM/SLiM themes.
To suit the varying sizes and ratios of monitors, any wallpaper must be
a minimum 1600 pixels wide and provided in both 4:3 and 16:9 ratios.
* All artwork must be submitted together with any associated source
files - i.e. files which are required by the graphics editor used by
the entrant to reproduce and/or edit the artwork.
* Only FLOSS software may be used to create the wallpaper.
* Neither the release's version number, nor code-name are to appear in
artwork, or there should be a version without them for later use when
a given release is no longer supported.
= Frugalware Asciidoc quickstart
Since 0.6 Frugalware, all documentation is written in Asciidoc which
means we have to write README.Frugalware files in Asciidoc syntax.
Here are some basic Asciidoc features and some things you should and
should not do a README.Frugalware.
== Features
You can use \*bold*, \_italic_ and also \`monospaced` fonts.
You can also \``quote'' if you want to do so.
When you want to add something to the
-------------
------------
# root command line
$ user command line
> keyboard input
------------
-------------
that's no problem at all.
Maybe you want bulleted items:
---------------
.Items
* item 1
* item 2
* here is number 3
---------------
And you can also create lists:
-------------------------------------
1. First
+
It's indented, belongs to first.
+
And this paragraph is also indented.
2. Second
+
This is inside the second point.
+
2.1. Foo
+
2.2. Bar
+
a. Baz
3. Third
End of list.
-------------------------------------
Some extras:
-------------------------------
NOTE: You can also place notes.
TIP: It's a tip
WARNING: Warning.
IMPORTANT: This is important
CAUTION: Cave canem!
-------------------------------
== Restrictions
You *must not* underline titles with = or -. You might use ~, and ^ for
subchapters. If you want one line titles place 3 or 4 = before the title and a
space.
== Skeleton for README.Frugalwares
Your titles should look similar to this:
--------------------------------
=== First chapter
--------------
# pacman-g2 -Syu
--------------
=== Second one
`\_F_foobar`
==== This is a subchapter...
...and its contents.
--------------------------------
or
--------------------------------
First chapter
~~~~~~~~~~~~~
--------------
# pacman-g2 -Syu
--------------
Second one
~~~~~~~~~~
`\_F_foobar`
This is a subchapter...
^^^^^^^^^^^^^^^^^^^^^^^
...and its contents.
--------------------------------
== Skeleton for standalone documentation
You might ask then: okay, but how do I start? Here is a really simple example:
--------------------------------
= Title
Author Name <foo@frugalware.org>
== First chapter
--------------
pacman-g2 -Syu
--------------
== Second one
`\_F_foobar`
--------------------------------
And you can generate the HTML using
------------------------------------
asciidoc -a toc -a numbered skel.txt
------------------------------------
The documentation should be placed under the `/docs` dir in the FST. Please add a
link to it in `index.txt` and in `index-user.txt` or `index-devel.txt`
depending on the type of the documentation.
== Buiding it on your own machine
Install the tools necessary to build the documentation (if you haven't already done
so):
----
# pacman-g2 -S make asciidoc po4a
----
Get the necessary source code and translations:
----
$ mkdir ~/git
$ cd ~/git
$ git clone http://frugalware.org/git/pub/frugalware/frugalware-current current
$ git clone http://frugalware.org/git/pub/other/translations
$ cd current/docs
----
Generate additional documentation and update the po files from the translations
repository:
----
$ make packages.txt user.txt po
----
Generate the localized documentation source from the po files:
----
$ po4a -k 0 po4a.cfg
----
Generate HTML from the source:
----
$ cd hu
$ asciidoc -a toc -a numbered -a sectids network.txt
----
Now you can look at the result of your translation in a web browser.
If you have already done this, and you updated the translation, you need to:
----
$ cd ~/git/translations
$ git pull --rebase
$ cd ~/git/current/docs
$ rm -rf po
$ make po
$ po4a -k 0 po4a.cfg
$ cd hu
$ asciidoc -a toc -a numbered -a sectids network.txt
----
and now you should be able to see your updated translation in the updated HTML.
== Adding a new project to Pootle
Well, this happens rarely, and so is not well documented, but here is what
is needed:
* `autogen.sh` should support importing po files from the `translations`
repository and should have a `--pot-only` switch. `gnetconfig` is a good
example.
* The pot file should be updated daily. Add the project's `autogen.sh` to
-current's `/tools/genpkgdbs`.
* Run the above command manually once.
* Add the pot file to `pootle-update` in the `pacman-tools` repository.
* Run `pootle-update` manually once.
* Log in to Pootle with administrator rights and create a new project.
* Add the necessary new languages on the web interface.
* Translate a few strings for one language and commit.
* Pull the translations repository locally and verify that you get the expected
results.
= The Frugalware Bug Reporting HOWTO
== Introduction
The aim of this HOWTO is to explain how to choose a task name and what to
include in a feature request/bugreport to help Frugalware developers speed up
the process of fixing a bug or fulfilling a feature request.
== Where
The URL of our Bug tracking system is:
---------------------------
http://bugs.frugalware.org/
---------------------------
== General
Use the search function before opening a task, as there may be a task for your
bug/feature. In that case just add a comment such as "I can reproduce this, too."
or "I would enjoy this feature, too."
There are a few topics which are often requested/reported but we have a good
reason not fixing/implementing them. You can see a list of such topics in the
http://wiki.frugalware.org/index.php/Bugs_FAQ[wiki].
If you'd like to report an outdated package, first check that it is not already
listed on http://frugalware.org/~vmiklos/stats/chkworld.html[this site]. If the
package is listed, please do *not* report it as we know there is a new version.
We will update it as soon as possible in this case.
Write bugreports in English, please. This is the only language all developers
speak.
== Bug reports
Please include the following things, unless you know what you are doing:
. Description of Problem - never say "does not work", quote the error message
. Steps to reproduce the problem
. Actual Results
. Expected Results
. How often does this happen?
. Additional Information
The default arch is i686 and the default version is -current. If these are not
true, don't forget to change them!
If you report a -current installer bug, then -current is probably not enough,
please specify the snapshot date.
If you found a security bug, then use the [SEC] prefix in the task name.
== Feature Requests
Please don't request more than one package in a feature request. Open a task
for every package. (Of course you don't have to open task for dependencies if
they are also missing from our packages, but please list them if you can.)
If you request a package, please include:
. The name of the application (yes, "more games" is not enough!)
. The URL of the application
. Optionally a short note about why you think this package would be
interesting for others, too
If you have a FrugalBuild for the package already, then upload it as an
attachment after opening the task. In this case, please prefix your task name
with `[FB]`, because this way it will be reviewed sooner.
Alternatively, you can post your FrugalBuild to the `frugalware-devel` mailing
list for review, that can be handy if you want to submit more and more
buildscripts - finally to become a developer if possible. Opening a task for
your FrugalBuild is still fine if you want us to maintain it after the initial
version is accepted.
Please don't link other distribution's buildscripts when you request a package.
That information is useless for us in most cases and if you don't include such
links, you make our life easier.
=== Do not request
Please don't request custom kernels. We try to use as few patches as possible.
See `man kernel.sh` as a reference on building your own kernel using various
patchsets. A
http://wiki.frugalware.org/index.php/How_to_build_a_custom_kernel[tutorial] is
available as well. Really, building such a kernel usually requires a
buildscript of only 5 (five) lines!
== Pacman-g2 problems
If you get a crash from our package manager, then we need a backtrace from gdb.
Here are the instructions to get a backtrace:
- Find the command line that triggers the crash. For example:
pacman-g2 -Sy
- Get the pacman-g2 git repo and compile it with debug symbols enabled:
+
--------------------------------------------------------------
$ git clone http://frugalware.org/git/pub/other/pacman-g2/pacman-g2
$ cd pacman-g2
$ sh autogen.sh
$ ./configure --enable-debug
$ make
--------------------------------------------------------------
- Then run pacman-g2 in gdb and get the trace:
+
----------------------------
$ cd src/pacman-g2
$ sudo libtool gdb ./pacman-g2
> run -Sy
----------------------------
- When pacman-g2 crashes, get the trace by typing 'bt'. Here is an example:
+
----------------------------------------------------------------
Program received signal SIGSEGV, Segmentation fault.
0x0805035e in pacman_sync (targets=0x0) at sync.c:354
354 *p = 1;
(gdb) bt
#0 0x0805035e in pacman_sync (targets=0x0) at sync.c:354
#1 0x08054594 in main (argc=2, argv=0xbfee1844) at pacman.c:609
----------------------------------------------------------------
- Attach the output of 'bt' to your bugreport.
== Fixed in git
Your feature request/bugreport may be closed with a "Fixed in git ..."
message. Git is our source control management software (just like CVS). If
your task is not considered to be critical, then it will be fixed/implemented
only in git, without increasing the package release. This means that it will
be automatically included in the next release.
= Compiz Fusion Bump HOWTO
== Compile order
You must follow this order when doing a version bump
- compiz x11-extra
- libcompizconfig xlib-extra
- compiz-bcop apps-extra
- compiz-plugins-main x11-extra
- compiz-plugins-extra x11-extra
- compiz-emerald x11-extra
- compizconfig-python xlib-extra
- ccsm gnome-extra
- fusion-icon gnome-extra
= How to contribute
If you appreciate our work, please consider contributing. Below are examples
of ways in which you can help the Frugalware project. If you want to help in
a way that's not described here, please tell us of your idea in an email to
the Frugalware users' mailing list, or add an entry to the Frugalware forums.
== Donations of money
Donations of money are welcome and will be used to cover costs such as domain
name registration, hosting costs (hardware, bandwidth etc). If you want to
donate, please use the "Donation" link on the Frugalware home page.
== Translation
Comprehensive, multi-lingual documentation is very important to us because we
want Frugalware to be available to as many people as possible. If you have the
required linguistic knowledge, you could help translate various pieces of work.
These include our own applications, documentation, web site etc.
== Application packaging
In the http://bugs.frugalware.org[Bug Tracking System], are requests for
packages, from Frugalware's users. The process of making packages is well
documented in the http://frugalware.org/docs/stable/index-devel
[Frugalware Developer Documentation], and with some GNU/Linux experience, you
could contribute in that way. Existing package maintainers are always available
to help you, especially if you're new to packaging.
== Developing
Frugalware has several of its own applications, including:
* An ncurses installer;
* A GUI installer (fwife);
* A GUI package management tool (gfpm);
* A command-line package manager (pacman-g2);
* A GUI runlevel manager (gservice).
Help in further developing and enhancing these applications is welcome.
== Donating hardware
By sending us some wanted hardware (see http://frugalware.org/donations[donations]),
you can make testing packages easier, or speed up the package creation
process within a specific architecture.
== Artwork
We usually update our artwork (background images, grub splash, desktop manager
themes, window manager splashes and so on) for each release. If you are skilled
in this area, you're welcome to join the artwork team.
== Support
If you have time and knowledge, monitor the forums, read the mailing list
posts, hang around on IRC and try to answer peoples' questions.
== Find bugs
If you find bugs, you can help by submitting well-written bug reports, see the
Reporting Bugs section for more info.
= Frequently Asked Developer Questions
== What is the recommended way to version bump a package if I don't have git push access?
.. Update the FrugalBuild.
.. Optional: update the patches/docs/etc.
.. Compile the package.
.. Upload the new .fpm to incoming.
.. repoman rec, git format-patch and git send-email the fixes. (Don't forget to set your git identity!)
== makepkg ends up with <packagename>: /usr/info/dir: exists in filesystem
Instead of
`make DESTDIR=$startdir/pkg install`
you should write
`Fmakeinstall`
in your FrugalBuild.
== I can't pacman-g2 -Su <package>, it says local version is newer, but I know it isn't!
This is a bug in the package's version numbering, so please report this in the
Bug Tracker System. Since pacman-g2 checks the version numbers (installed vs.
repo version), the new package's version must be bigger than the old one to
upgrade flawlessly.
== What does 5.55 SBU mean?
It took 5.55 times longer for the maintainer to compile this package than
binutils. So if you want to know how long it will take to compile a package
with 5.55 SBU, you should first compile binutils (makepkg helps you, as it
writes how many seconds elapsed). Then you should multiply it by 5.55 to know
how many seconds it will take to compile the package.
== Why do maintainers cry about my new package's tarball?
Let's have a look at the filelist of eaccelerator's tarball:
------------------------------------------
$ tar -tf eaccelerator-0.9.3-1.tar.bz2
eaccelerator/
eaccelerator/eaccelerator-0.9.3.zip
eaccelerator/FrugalBuild
eaccelerator/README.Frugalware
eaccelerator/eaccelerator-0.9.3-1-i686.fpm
------------------------------------------
You have to name the tarball as <pkgname>-<pkgver>-<pkgrel>.tar.bz2 (or gz),
which should only contain a <pkgname> directory at the root level, and all the
files needed to create the fpm in it. It is the easiest way for the
maintainers to work with your tarball when adding your package to the repo.
== What should and shouldn't I include in depends(), rodepends() and makedepends()?
You should include only what chkdep -p recommends, and avoid trivial
makedepends, including:
* auto*
* make
* gcc
* kernel-headers
* libtool
* glibc
Don't forget: every depends is a makedepends as well!
The rodepends() array should only contain packages really needed for running
the given application.
== What are the various dependancy-control arrays for?
* 'depends' should contain any packages that this one depends on at compile and
run time as well.
* 'makedepends' is for packages that this one needs to compile.
* 'rodepends' is for run time only dependencies;
eg. a wordlist package (with no executables) needs a program
which can handle it as a dictionary.
* 'provides' is an alternate name for the package. Main use is for
more packages which do the same; eg. hunspell-en and hunspell-de both provide
hunspell-dict, and hunspell depends on hunspell-dict instead of any specific
language. (Sometimes those packages are conflicting, like postfix provides
_and_ conflicts with mta, and exim too - this way there can be only one MTA on
the system, without the need to know other MTAs' name.)
Be careful with dependency-cycles: while pacman-g2 can handle them, makepkg can
not.
== How can I have PHP to work with my newly packaged eaccelerator/anything extension?
Since package A should not tamper with package B's config files,you should write
a README.Frugalware, describing how to enable/use the extension, include it in
source() and Fdoc README.Frugalware.
== How can I cross-compile (package) an architecture-independent (non-binary) program?
You should modify carch and chost in '/etc/makepkg.conf' and build the package
again.
== repoman upd can't create /var/fst/ as it already exists
`Su -` to root and
`cd /var/fst && mv * frugalware-current`
== How can I access the central FW repo (mirrors are too slow for me)?
`git clone http://git.frugalware.org/repos/frugalware-current`
If you are a developer and cloning over SSH makes more sense to you:
`git clone git.frugalware.org:/pub/frugalware/frugalware-current`
This creates a new local repo for you, which is a copy of the central repo. To
update it, run
`git pull --rebase`
in it. That's all to have a read-only copy; if you want to git send-email
patches, then you should read the link:getting-involved.html[Git docs] to set
up your name, email, etc.
== What should I write as patch name and long comment at repoman rec?
Patch name should be the same as the fpm (but without .fpm, of course); and long
comment should only contain what you have done to create that patch (eg. "added
i686 to archs()").
== Where should I place my comments about a package?
You mean README.Frugalware. It should be in source() and then at the end of the
build() you should use:
Fdoc README.Frugalware
It is automatically included if you use empty build() or Fbuild.
== I want to work with the latest development version of pacman&co.! How?
------------------------------------------------------------------
$ git clone http://git.frugalware.org/repos/pacman-tools
$ cd pacman-tools
$ make dist
------------------------------------------------------------------
You will have a brand new .tar.gz. Give it to pacman-tools' FrugalBuild,
correct the checksum, create a new pacman-tools package (makepkg -fucH helps)
and install it. That's all (and if you don't understand this, read it again,
and if it's still not clear, then wait for pacman-tools' normal upgrade
since you don't need this really)...
== Naming locale packages
What is the order of a new package's locales? How should I name them?
Have a look at hunspell There is a hunspell package, which depends on
hunspell-dict. There is no package named hunspell-dict, but it is provided by
the locale packages. The most important ones are -en (==en_US), -hu (==hu_HU),
-de (==de_DE), -fr (==fr_FR), -it (==it_IT), -es (==es_ES) and -sk (==sk_SK).
Here are others: -en_US, -de_CH, -es_MX.