docs: Updated documentation
Updated the documents with the following general changes: * Replaced Gitorious with GitLab * Moved translate stuff out of README * Changed plain text to markdown (looks better on website)
This commit is contained in:
Craig Small
parent
00313ef370
commit
7993b4d85d
@ -1,82 +0,0 @@
|
|||||||
BUG REPORTS
|
|
||||||
|
|
||||||
Please read this file before sending in a bug report or patch.
|
|
||||||
|
|
||||||
Also, PLEASE read the documentation first. 90% of the mail I get
|
|
||||||
complaining about procps-ng is due to the sender not having read the
|
|
||||||
documentation!
|
|
||||||
|
|
||||||
|
|
||||||
Where to send
|
|
||||||
=============
|
|
||||||
Send comments, bug reports, patches, etc., to procps@freelists.org
|
|
||||||
|
|
||||||
|
|
||||||
What to send
|
|
||||||
============
|
|
||||||
It is much more useful to me if a program really crashes to recompile it
|
|
||||||
with make "CFLAGS=-ggdb -O", run it with "gdb prog" and "run" and send
|
|
||||||
me a stack trace ('bt' command). That said, any bug report is still
|
|
||||||
better than none.
|
|
||||||
|
|
||||||
strace and ltrace output are very helpful:
|
|
||||||
|
|
||||||
strace -o output-file ps --blah
|
|
||||||
bzip2 output-file
|
|
||||||
|
|
||||||
I also like "ps --info" output, even if there isn't a ps problem.
|
|
||||||
|
|
||||||
Patches
|
|
||||||
=======
|
|
||||||
|
|
||||||
Get latest version of the source from upstream git.
|
|
||||||
|
|
||||||
git clone git://gitorious.org/procps/procps.git
|
|
||||||
|
|
||||||
and use 'git format-patch' format. It is fine to attach patches as
|
|
||||||
compressed tar balls. When you are about to send very large number
|
|
||||||
of patches consider setting up your personal clone, and send a pull
|
|
||||||
request.
|
|
||||||
|
|
||||||
git request-pull commit-id \
|
|
||||||
git://gitorious.org/~yourlogin/procps/your-clone.git
|
|
||||||
|
|
||||||
Gitorious merge requests
|
|
||||||
========================
|
|
||||||
Prefer sending pull request to mail list. More people will notice a
|
|
||||||
change being proposed, making potential discussion to capture wider
|
|
||||||
point of view. Using gitorious merge reguest in combination mail
|
|
||||||
list announcement is fine.
|
|
||||||
|
|
||||||
Kernel-Dependent Patches
|
|
||||||
========================
|
|
||||||
If you send me patches which are specific to *running* with a particular
|
|
||||||
kernel version of /proc, please condition them with the runtime determined
|
|
||||||
variable 'linux_version_code' from libproc/version.c. It is the same
|
|
||||||
number as the macro LINUX_VERSION_CODE for which the kernel /proc fs
|
|
||||||
code was compiled.
|
|
||||||
|
|
||||||
A macro is provide in libproc/version.h to construct the code from its
|
|
||||||
components, e.g.
|
|
||||||
if (linux_version_code < LINUX_VERSION(2,5,41))
|
|
||||||
/* blah blah blah */
|
|
||||||
A startup call to set_linux_version may also be necessary.
|
|
||||||
|
|
||||||
Of course, if a bug is due to a change in kernel file formats, it would
|
|
||||||
be best to first try to generalize the parsing, since the code is then
|
|
||||||
more resilient against future change.
|
|
||||||
|
|
||||||
Code Structure
|
|
||||||
==============
|
|
||||||
|
|
||||||
A goal is to encapsulate *all* parsing dependent on /proc
|
|
||||||
file formats into the libproc library. If the API is general enough
|
|
||||||
it can hopefully stabilize and then /proc changes might only require
|
|
||||||
updating libproc.so. Beyond that having the set of utilities be simple
|
|
||||||
command lines parsers and output formatters and encapsulating all kernel
|
|
||||||
divergence in libproc is the way to go.
|
|
||||||
|
|
||||||
Hence if you are submitting a new program or are fixing an old one, keep
|
|
||||||
in mind that adding files to libproc which encapsulate such things is
|
|
||||||
more desirable than patching the actual driver program. (well, except
|
|
||||||
to move it toward the API of the library).
|
|
||||||
92
Documentation/bugs.md
Normal file
92
Documentation/bugs.md
Normal file
@ -0,0 +1,92 @@
|
|||||||
|
BUG REPORTS
|
||||||
|
===========
|
||||||
|
|
||||||
|
The following is information for reporting bugs. Please read
|
||||||
|
the file as well as the documentation for the relevant program
|
||||||
|
before posting. This document is more useful for advanced users
|
||||||
|
and the people that package for the distributions.
|
||||||
|
|
||||||
|
Also if you are an end-user of the programs and not the packager
|
||||||
|
and are using a distribution, check their bug tracker first,
|
||||||
|
you may find its a known bug already.
|
||||||
|
|
||||||
|
|
||||||
|
Where to send
|
||||||
|
-------------
|
||||||
|
You can raise issues on the GitLab issues tracker which is
|
||||||
|
located at https://gitlab.com/procps-ng/procps/issues You
|
||||||
|
will need a GitLab login to do so.
|
||||||
|
|
||||||
|
Alternatively send comments, bug reports, patches, etc.
|
||||||
|
to the email list procps@freelists.org
|
||||||
|
|
||||||
|
What to send
|
||||||
|
------------
|
||||||
|
It is much more useful to us if a program really crashes to recompile it
|
||||||
|
with make `CFLAGS=-ggdb -O`, run it with `gdb prog` and `run` and send
|
||||||
|
me a stack trace (`bt` command). That said, any bug report is still
|
||||||
|
better than none.
|
||||||
|
|
||||||
|
strace and ltrace output are very helpful:
|
||||||
|
|
||||||
|
> strace -o output-file ps --blah
|
||||||
|
> bzip2 output-file
|
||||||
|
|
||||||
|
The output of `ps --info` is often quite useful, even if the problem
|
||||||
|
is not with ps itself. A lot of the utilities use the same library.
|
||||||
|
|
||||||
|
Merge Requests
|
||||||
|
--------------
|
||||||
|
Merge requests are fine to use and give a central place for
|
||||||
|
everyone involved to have a look. Merge requests are found
|
||||||
|
on GitLab at https://gitlab.com/procps-ng/procps/merge_requests
|
||||||
|
It is best to follow up your merge request with an email to
|
||||||
|
the list saying what you have done.
|
||||||
|
|
||||||
|
Patches
|
||||||
|
-------
|
||||||
|
While merge requests are preferred, patches are also welcome.
|
||||||
|
Get latest version of the source from upstream git.
|
||||||
|
|
||||||
|
> git clone git@gitlab.com:procps-ng/procps.git
|
||||||
|
|
||||||
|
and use `git format-patch` format. It is fine to attach patches as
|
||||||
|
compressed tar balls. When you are about to send very large number
|
||||||
|
of patches consider setting up your personal clone, and send a pull
|
||||||
|
request.
|
||||||
|
|
||||||
|
> git request-pull commit-id \
|
||||||
|
> git://gitorious.org/~yourlogin/procps/your-clone.git
|
||||||
|
|
||||||
|
|
||||||
|
Kernel-Dependent Patches
|
||||||
|
------------------------
|
||||||
|
If you send patches which are specific to *running* with a particular
|
||||||
|
kernel version of /proc, please condition them with the runtime determined
|
||||||
|
variable `linux_version_code` from libproc/version.c. It is the same
|
||||||
|
number as the macro `LINUX_VERSION_CODE` for which the kernel /proc fs
|
||||||
|
code was compiled.
|
||||||
|
|
||||||
|
A macro is provide in libproc/version.h to construct the code from its
|
||||||
|
components, e.g.
|
||||||
|
> if (linux_version_code < LINUX_VERSION(2,5,41))
|
||||||
|
> /* blah blah blah */
|
||||||
|
A startup call to `set_linux_version` may also be necessary.
|
||||||
|
|
||||||
|
Of course, if a bug is due to a change in kernel file formats, it would
|
||||||
|
be best to first try to generalize the parsing, since the code is then
|
||||||
|
more resilient against future change.
|
||||||
|
|
||||||
|
Code Structure
|
||||||
|
--------------
|
||||||
|
A goal is to encapsulate *all* parsing dependent on /proc
|
||||||
|
file formats into the libproc library. If the API is general enough
|
||||||
|
it can hopefully stabilize and then /proc changes might only require
|
||||||
|
updating libproc.so. Beyond that having the set of utilities be simple
|
||||||
|
command lines parsers and output formatters and encapsulating all kernel
|
||||||
|
divergence in libproc is the way to go.
|
||||||
|
|
||||||
|
Hence if you are submitting a new program or are fixing an old one, keep
|
||||||
|
in mind that adding files to libproc which encapsulate such things is
|
||||||
|
more desirable than patching the actual driver program. (well, except
|
||||||
|
to move it toward the API of the library).
|
||||||
21
Documentation/translations.md
Normal file
21
Documentation/translations.md
Normal file
@ -0,0 +1,21 @@
|
|||||||
|
Translations
|
||||||
|
============
|
||||||
|
|
||||||
|
There is a three-step process for translating man pages. Most
|
||||||
|
of the work happens in the man-po directory.
|
||||||
|
|
||||||
|
> make -C man-po translate-templates
|
||||||
|
Creates the translation templates (the .pot files) for translators
|
||||||
|
to use as a base. These, along with the tar file, should be sent
|
||||||
|
to the tp-coorindator before release.
|
||||||
|
|
||||||
|
> make get-trans
|
||||||
|
rsyncs the latest translated (.po) files for both the programs and
|
||||||
|
man pages.
|
||||||
|
|
||||||
|
> make -C man-po translate-mans
|
||||||
|
This is also called in the dist-hook and is where the translation
|
||||||
|
magic happens. Take the original man page, the relevant .po file
|
||||||
|
and produce a translated man page in that language.
|
||||||
|
All of the man pages generated are found in
|
||||||
|
man-po/(LANG)/man(SECTION)/
|
||||||
24
INSTALL.md
Normal file
24
INSTALL.md
Normal file
@ -0,0 +1,24 @@
|
|||||||
|
Installation Instructions for procps
|
||||||
|
====================================
|
||||||
|
Depending on what format you are using to get these files, you
|
||||||
|
might need to run the `autogen.sh` program to create the
|
||||||
|
configure script. If you have a configure script already then
|
||||||
|
you might not need it.
|
||||||
|
|
||||||
|
A typical installation would go something like
|
||||||
|
> ./autogen.sh
|
||||||
|
> ./configure
|
||||||
|
> make
|
||||||
|
> make install
|
||||||
|
|
||||||
|
The configure script has a lot of options, so please have a read
|
||||||
|
of `configure --help` to see what they are and what they are used
|
||||||
|
for.
|
||||||
|
|
||||||
|
Testing
|
||||||
|
-------
|
||||||
|
procps has a series of test scripts (and more are welcome if they
|
||||||
|
are repeatable). You will need to install DejaGNU to run it and
|
||||||
|
it is simply:
|
||||||
|
|
||||||
|
> make check
|
||||||
67
README
67
README
@ -1,67 +0,0 @@
|
|||||||
COMPATIBILITY
|
|
||||||
|
|
||||||
This code is intended for use with Linux 2.6.xx, 3.x and
|
|
||||||
hopefully all future kernels.
|
|
||||||
|
|
||||||
INSTALLATION
|
|
||||||
|
|
||||||
If you are using git version of the project you need extra step.
|
|
||||||
|
|
||||||
./autogen.sh
|
|
||||||
|
|
||||||
After that, and everyone using .tar.xz version of procps-ng, can
|
|
||||||
do normal build. Read './configure --help' to select options for
|
|
||||||
your needs.
|
|
||||||
|
|
||||||
./configure
|
|
||||||
make
|
|
||||||
make install
|
|
||||||
|
|
||||||
If you have DejaGNU installed you can run optional test suite.
|
|
||||||
|
|
||||||
make check
|
|
||||||
|
|
||||||
HOW TO CONTRIBUTE
|
|
||||||
|
|
||||||
See Documentation/BUGS file.
|
|
||||||
|
|
||||||
PACKAGING
|
|
||||||
|
|
||||||
If you are a downstream maintainer (packager) for a Linux
|
|
||||||
distribution, please avoid causing troubles. This section
|
|
||||||
applies to you.
|
|
||||||
|
|
||||||
Avoid maintaining distribution specific patches. Send your
|
|
||||||
patches to upstream, where they are at least reviewed, if not
|
|
||||||
included.
|
|
||||||
|
|
||||||
Please forward bug reports. If your bug database is public and
|
|
||||||
busy enough to bother with, please make this known. Follow
|
|
||||||
Debian's lead in making the bug database easy to comment on via
|
|
||||||
email without need for an account.
|
|
||||||
|
|
||||||
For normal packages, ensure that you do not add debugging flags
|
|
||||||
to the CFLAGS variable.
|
|
||||||
|
|
||||||
TRANSLATING MAN PAGES
|
|
||||||
There is a three-step process for translating man pages. Most
|
|
||||||
of the work happens in the man-po directory.
|
|
||||||
|
|
||||||
make -C man-po translate-templates
|
|
||||||
Creates the translation templates (the .pot files) for translators
|
|
||||||
to use as a base. These, along with the tar file, should be sent
|
|
||||||
to the tp-coorindator before release.
|
|
||||||
|
|
||||||
make get-trans
|
|
||||||
rsyncs the latest translated (.po) files for both the programs and
|
|
||||||
man pages.
|
|
||||||
|
|
||||||
make -C man-po translate-mans
|
|
||||||
This is also called in the dist-hook and is where the translation
|
|
||||||
magic happens. Take the original man page, the relevant .po file
|
|
||||||
and produce a translated man page in that language.
|
|
||||||
All of the man pages generated are found in
|
|
||||||
man-po/(LANG)/man(SECTION)/
|
|
||||||
UPSTREAM & BUG REPORTS
|
|
||||||
|
|
||||||
procps-ng <procps@freelists.org>
|
|
||||||
Loading…
Reference in New Issue
Block a user