Gentoo Archives: gentoo-dev

From: Kalin KOZHUHAROV <kalin@××××××××.net>
To: gentoo-dev@l.g.o
Subject: Re: [gentoo-dev] webapp.eclass documentation
Date: Fri, 20 Jan 2006 15:44:36
Message-Id: 43D103EC.4040609@thinrope.net
In Reply to: [gentoo-dev] webapp.eclass documentation by Renat Lumpau
1 Renat Lumpau wrote:
2 > I just committed our new documentation [1] for webapp.eclass. We hope that it
3 > will help devs and users write and maintain ebuilds for web applications.
4 > Comments and patches are welcome.
5 >
6 > We also have a brand new project page [2], courtesy of wrobel.
7 >
8 > [1] http://www.gentoo.org/proj/en/webapps/webapp-eclass.xml
9 > [2] http://www.gentoo.org/proj/en/webapps/
10
11 A few comments:
12
13 1. I can see this in many places of the Gentoo docs, so it is not specific
14 to this particular doc, but still: the CSS for span.code would better be
15 changed to use another color than the links. I very often catch myself
16 trying to click on it (e.g. I expected "man 5 webapp.eclass" to be a link to
17 the on-line man page; BTW that would not be a bad idea at all if it can be
18 kept in sync).
19 So if this is not supposed to be changed locally, (I see it is coming from
20 http://www.gentoo.org/css/main.css?d=20051010 ) whom shall I contact?
21
22 2. Consider this paragraph:
23
24 webapp.eclass is located in the usual place in the Portage tree. By default,
25 it will be found in /usr/portage/eclass/webapp.eclass. By definition, the
26 source code is the ultimate documentation and should be consulted whenever
27 something does not perform as expected or further clarification is required.
28
29 "By default, it will be found in /usr/portage/eclass/webapp.eclass." is not
30 acurate I think ( found in /usr/portage/eclass/ is better). Even better if
31 you combine the first two sentences:
32 webapp.eclass is located under /usr/portage/eclass in a Gentoo default
33 installation.
34
35 BTW, is there an easy way to get the source XML of this (and other) doc? So
36 I can send patches directly.
37
38 3. The "Beginner, Intermediate, Advanced" section titles might be better if
39 they are a bit longer, say: "A Beginner example ebuild: www-apps/gallery"
40 Is the version required for the sect title? Yes, it is required inside the
41 explanation though.
42
43 4. This warning:
44
45 "Warning: If the package requires specific Perl modules, all dependencies
46 must have ebuilds available. Relying on CPAN is not acceptable."
47
48 Why is that? If I have a webapp that needs ">=dev-perl/foo-3.0.4" which does
49 not have (yet) an ebuild in /usr/portage what to do? Isn't the normal way to
50 fail the emerge because 'cannot find any ebuilds that satisfy
51 ">=dev-perl/foo-3.0.4"! '
52 A helpful hint "Try using `g-cpan -i foo` and reemerge ${PKG}" will be very
53 good solution. Act accordingly for PHP, Ruby and whatever we have.
54
55 5. Just below the above warning, the discussion about databases...
56
57 > A common mistake with specifying dependencies for web applications is to
58 > unconditionally RDEPEND on a database engine such as MySQL or PostgreSQL.
59 > Many, if not all, web applications are able to connect to a remote
60 > database server. Thus, a local database should not be a requirement;
61 Perfect up to here.
62
63 > the right syntax for dealing with this is:
64 >
65 > Code Listing 2.8: Database Dependencies
66 >
67 > mysql? ( >=dev-db/mysql-4 )
68
69 /me might be wrong, but isn't this asking for the availability of a MySQL
70 server installed? Don't tell me webapp.eclass treats the RDEPEND differently!
71 Isn't it more normal to depend on, say dev-perl/DBD-mysql for a Perl webapp?
72 ( change accordingly for PHP, etc.)
73
74 6. The last word :-)
75 - contact the web-apps herd or ask on <a>IRC</a>.
76 + contact the web-apps herd or discuss it on <a>#gentoo-web</a> IRC channel.
77
78 Imagine reading it printed :-|
79
80 7. Having gone over it, why not webappS.eclass ?
81 $ ls /usr/portage/eclass/*s.eclass |wc -l
82 23
83
84 examples: euitls, games, nsplugins, xemacs-packages ...
85
86 Kalin.
87
88 --
89 |[ ~~~~~~~~~~~~~~~~~~~~~~ ]|
90 +-> http://ThinRope.net/ <-+
91 |[ ______________________ ]|
92
93 --
94 gentoo-dev@g.o mailing list

Replies

Subject Author
Re: [gentoo-dev] webapp.eclass documentation "Jan Kundrát" <jkt@g.o>