1
1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2
2
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" >
3
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
5
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
6
<meta name="generator" content="AsciiDoc 7.0.0"/>
5
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
<meta name="generator" content="AsciiDoc 7.1.2" />
7
7
<style type="text/css">
9
9
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
267
277
<p>Don't take this file as a law. We may or may not be right in these issues.</p>
268
278
<p>Motto: I didn't expect someone to look at the source, so it's unreadable.
269
279
—Mikulas</p>
270
<h3>Language files</h3>
282
<h2>Language files</h2>
283
<div class="sectionbody">
271
284
<p>Each UI output should use language files in order to be able to translate the
272
285
messages to a desired language. Those language files reside in the po/ subdir. If
273
286
you want to update a .po file, please read the gettext manual available at
274
287
<http://www.gnu.org/manual/gettext>. In order to actually use your updates on
275
288
your own system, you have to have the gettext tools installed.</p>
276
<h3>ELinks philosophy</h3>
290
<h2>ELinks philosophy</h2>
291
<div class="sectionbody">
277
292
<p>ELinks is based on the philosophy of asynchronism. That means, you pass a
278
293
callback to each function, and when the requested task finishes sometime in the
279
294
unclear future, the callback will be called in order to notify you that you can
281
296
<p>When you use multiple elinks instances at once, normally only one of them is a
282
<span class="emphasis">master</span>, and the rest of them are just kinda dumb terminals. So if you want
283
to test some new feature, you have to start elinks with the <span class="emphasis">-no-connect</span>
297
<em>master</em>, and the rest of them are just kinda dumb terminals. So if you want
298
to test some new feature, you have to start elinks with the <em>-no-connect</em>
284
299
parameter, otherwise it will just connect to an already running elinks and you
285
300
won't see your great new feature that you just added with such much pain.</p>
286
301
<p>There are two basic structures in ELinks. Connection and session - their names
432
453
<p>The code to allow binding Lua code to a keypress is slightly different then the
433
454
hooks, but not much. Instead of branching off to some C code when a key is
434
455
pressed, we branch off to some Lua code.</p>
435
<h3>Coding style</h3>
436
<p>Mikulas once said that <span class="emphasis">it was hard to code, so it should be hard to read</span> -
457
<h2>Coding style</h2>
458
<div class="sectionbody">
459
<p>Mikulas once said that <em>it was hard to code, so it should be hard to read</em> -
437
460
and he drove by this when he was writing links. However, we do NOT drive by
438
461
this rule anymore ;-). We strongly welcome cleanup patches and you have 99%
439
462
chance that they will be applied, if they are correct.</p>
440
<p>Variable names should be descriptive. Well, in worst case we'll accept <span class="emphasis">i</span> for
463
<p>Variable names should be descriptive. Well, in worst case we'll accept <em>i</em> for
441
464
index, but if possible don't do even this :). You should try to declare them
442
465
on the lowest level possible, so their declaration and initialization will be
443
466
near their usage and you will also prevent reuse of one variable for two
445
468
reasonable, initialize variables during their declaration and don't group too
446
469
many variables in one line. ALWAYS make a blank line after the declaration
448
<p>Be sure to prefix all local functions with <span class="emphasis">static</span>.</p>
471
<p>Be sure to prefix all local functions with <em>static</em>.</p>
449
472
<p>Indent shift width is 8 characters—that means one tab character.</p>
450
<p><span class="emphasis">{</span> should be on the same line as conditions near for, if, while, switch etc.,
473
<p><em>{</em> should be on the same line as conditions near for, if, while, switch etc.,
451
474
but on separate lines near function headers in function definitions.</p>
452
475
<p>Please _USE_ one tab instead of 8 spaces! It makes things easier.</p>
453
<p>Always place spaces around <span class="emphasis">=</span>, after <span class="emphasis">,</span> and - if reasonable - around other
476
<p>Always place spaces around <em>=</em>, after <em>,</em> and - if reasonable - around other
454
477
operators as well. You shouldn't make assignments in conditionals:</p>
455
478
<div class="listingblock">
456
479
<div class="title">Example: Use:</div>
457
480
<div class="content">
458
<pre><span class="monospaced">foo = mem_alloc(1234);
459
if (!foo) panic("out of memory");</span></pre>
481
<pre><tt>foo = mem_alloc(1234);
482
if (!foo) panic("out of memory");</tt></pre>
461
484
<div class="listingblock">
462
485
<div class="title">Example: Instead of:</div>
463
486
<div class="content">
464
<pre><span class="monospaced">if (!(foo = mem_alloc(1234))) panic("out of memory");</span></pre>
487
<pre><tt>if (!(foo = mem_alloc(1234))) panic("out of memory");</tt></pre>
466
489
<p>Note that thou shalt ALWAYS test for success on everything - we are supposed
467
490
to die with honor if we are to die!</p>
471
494
weird and ancient systems and we are already used to C89 anyway. The most
472
495
remarkable implication of no C99 are no C++ (//) comments and declarations
473
496
at the start of block only.</p>
475
<p>Use blank lines frequently to separate chunks of code. And use magic <span class="monospaced">/*</span> and
476
<span class="monospaced">*/</span> to give others an idea about what it does and about possible pitfalls.
499
<div class="sectionbody">
500
<p>Use blank lines frequently to separate chunks of code. And use magic <tt>/*</tt> and
501
<tt>*/</tt> to give others an idea about what it does and about possible pitfalls.
477
502
(Do not use //, as that is not a feature of ANSI C a.k.a. C89.)</p>
478
503
<p>Keep in mind that if there's an object and verb in the comment (and it is, in
479
504
most cases), it is a sentence, so it has to start with a capital letter and end
500
* blabla? */</span></pre>
525
* blabla? */</tt></pre>
502
527
<p>The best one usually depends on the actual context.</p>
503
528
<p>If you describe a structure, make either:</p>
504
529
<div class="listingblock">
505
530
<div class="content">
506
<pre><span class="monospaced">char *name; /* name of the tag */
531
<pre><tt>char *name; /* name of the tag */
507
532
void (*func)(unsigned char *); /* function hopefully handling the
508
533
* content of the tag */
509
int linebreak; /* needed for break of a line? */</span></pre>
534
int linebreak; /* needed for break of a line? */</tt></pre>
512
537
<div class="listingblock">
513
538
<div class="content">
514
<pre><span class="monospaced">/* Name of the tag */
539
<pre><tt>/* Name of the tag */
516
541
/* Function hopefully handling the content of the tag */
517
542
void (*func)(unsigned char *);
519
544
/* Do we need to break a line? */
520
int linebreak;</span></pre>
545
int linebreak;</tt></pre>
522
547
<p>Same if you comment the code. If the comment is</p>
523
548
<div class="literalblock">
524
549
<div class="content">
525
<pre><span class="monospaced">/* then do it now! */</span></pre>
550
<pre><tt>/* then do it now! */</tt></pre>
527
552
<p>place it on the same line as the command, if it's</p>
528
553
<div class="literalblock">
529
554
<div class="content">
530
<pre><span class="monospaced">/* We have to parse this crap now, as it is going to be freed in free_crap() */</span></pre>
555
<pre><tt>/* We have to parse this crap now, as it is going to be freed in free_crap() */</tt></pre>
532
557
<p>place it on the preceding line.</p>
533
<h3>More about style</h3>
559
<h2>More about style</h2>
560
<div class="sectionbody">
534
561
<p>Note: We use short variables names and stupid examples here, do not take that
535
562
as a guideline for _REAL_ coding. Always use descriptive variables
536
563
names and do not write stupid code ;).</p>
537
<h4>General style is:</h4>
564
<h3>General style is:</h3>
538
565
<div class="listingblock">
539
566
<div class="content">
540
<pre><span class="monospaced">[blank line]
567
<pre><tt>[blank line]
541
568
/* This is a comment about that function */
543
570
func(int a, int b)
602
629
<div class="listingblock">
603
630
<div class="title">Example: Use:</div>
604
631
<div class="content">
605
<pre><span class="monospaced">c = a;
606
if (c == b) {...</span></pre>
633
if (c == b) {...</tt></pre>
608
635
<div class="listingblock">
609
636
<div class="title">Example: Instead of:</div>
610
637
<div class="content">
611
<pre><span class="monospaced">if ((c = a) == b) {...</span></pre>
638
<pre><tt>if ((c = a) == b) {...</tt></pre>
613
640
<p>Never use spaces within ().</p>
614
641
<div class="listingblock">
615
642
<div class="title">Example: Use:</div>
616
643
<div class="content">
617
<pre><span class="monospaced">if (a) ...</span></pre>
644
<pre><tt>if (a) ...</tt></pre>
619
646
<div class="listingblock">
620
647
<div class="title">Example: Instead of:</div>
621
648
<div class="content">
622
<pre><span class="monospaced">if ( a ) ...</span></pre>
649
<pre><tt>if ( a ) ...</tt></pre>
625
652
<div class="listingblock">
626
653
<div class="title">Example: Use:</div>
627
654
<div class="content">
628
<pre><span class="monospaced">foreach (a, b)
655
<pre><tt>foreach (a, b)
634
661
<div class="listingblock">
635
662
<div class="title">Example: Instead of:</div>
636
663
<div class="content">
637
<pre><span class="monospaced">foreach(a, b) if (a == c) ... else ...</span></pre>
664
<pre><tt>foreach(a, b) if (a == c) ... else ...</tt></pre>
639
666
<p>If you have a chain of if () { .. } else if () { .. } else { .. } with longer
640
667
statements, you can insert a blank line before each else line.</p>
641
<p>Label names should start on the first column and with have a blank line before
668
<p>Label names should start on the first column and a blank line should be
669
inserted before it.</p>
643
670
<div class="listingblock">
644
671
<div class="title">Example: Use:</div>
645
672
<div class="content">
646
<pre><span class="monospaced"> some_code(aaa);
673
<pre><tt> some_code(aaa);
649
some_other_code(bbb);</span></pre>
676
some_other_code(bbb);</tt></pre>
651
678
<div class="listingblock">
652
679
<div class="title">Example: Instead of:</div>
653
680
<div class="content">
654
<pre><span class="monospaced"> some_code(aaa);
681
<pre><tt> some_code(aaa);
656
some_other_code(bbb);</span></pre>
683
some_other_code(bbb);</tt></pre>
658
685
<p>Wrap conditions on spaces before operators like && or ||.</p>
659
686
<div class="listingblock">
660
687
<div class="title">Example: Use:</div>
661
688
<div class="content">
662
<pre><span class="monospaced">if (some_very_long_thing1 == some_very_long_thing2
689
<pre><tt>if (some_very_long_thing1 == some_very_long_thing2
663
690
&& (test1 == test2
664
691
|| some_very_long_thing3 == some_very_long_thing4)) {
668
695
<p>Please remove useless spaces or tabs at the end of lines. Vim has a syntax
669
696
file called "Whitespace (add)" …</p>
674
701
<div class="listingblock">
675
702
<div class="title">Example: Use:</div>
676
703
<div class="content">
677
<pre><span class="monospaced">int
683
710
<div class="listingblock">
684
711
<div class="title">Example: Instead of:</div>
685
712
<div class="content">
686
<pre><span class="monospaced">int
692
719
<p>Please write if (), while (), switch (), for (), …. instead of if(),
693
720
while(), switch(), for()… Same thing apply for all iterators and tests
694
721
(e.g. foreach, foreachback).</p>
695
722
<p>Please write sizeof(something) instead of sizeof something.</p>
696
723
<p>Use assert() and assertm() where applicable. It will prevent hidden bugs.</p>
724
<p>Names of enum constants should be in upper case.</p>
725
<p>Please call the charset "utf8" or "UTF8" in identifiers, "UTF-8"
726
elsewhere, and "utf_8" only for compatibility.</p>
697
727
<p>If you see code in ELinks that doesn't follow these rules, fix it or tell us
699
729
<p>All the .c files MUST start by a short one-line description:</p>
700
730
<div class="literalblock">
701
731
<div class="content">
702
<pre><span class="monospaced">/* <short one-line description> */</span></pre>
732
<pre><tt>/* <short one-line description> */</tt></pre>
704
<p>All the .h files MUST start by a CVS Id tag and then anti-reinclusion ifdef.
734
<p>All the .h files MUST start by an anti-reinclusion ifdef.
706
736
<div class="literalblock">
707
737
<div class="content">
708
<pre><span class="monospaced">EL_<path_relative_to_src:s/[\/.]/_/>.</span></pre>
738
<pre><tt>EL_<path_relative_to_src:s/[\/.]/_/>.</tt></pre>
710
740
<p>There are obviously exceptions to these rules, but don't make a rule from your
711
741
exception and be prepared to defend your exception at anytime ;).</p>
712
<h3>Coding practices</h3>
713
<h4>Use bitfields to store boolean values</h4>
743
<h2>Coding practices</h2>
744
<div class="sectionbody">
745
<h3>Use bitfields to store boolean values</h3>
714
746
<p>If speed is not critical and especially if you are messing with some struct
715
747
where size might matter, feel encouraged to use bitfields to store boolean (or
716
748
tristate or tetrastate ;) values (e.g. unsigned int foo:1 for one-bit field).
717
749
HOWEVER please ALWAYS specify signedness of all such fields. It is very easy
718
750
to reach the top bit in these cases, and with int foo:1, foo would be either 0
719
751
or -1, which is probably not what you want.</p>
720
<h4>Wrap hard initializations of structures with macros</h4>
752
<h3>Wrap hard initializations of structures with macros</h3>
721
753
<p>This should be done if the structure's initializers are going to be spread
722
754
widely (so that we can grep for them easily), there are massive typecasts
723
755
needed in most of the initializers, you feel that order of the fields in
743
struct example t = NULL_EXAMPLE;</span></pre>
775
struct example t = NULL_EXAMPLE;</tt></pre>
745
<h4>Please try to keep order of fields</h4>
777
<h3>Please try to keep order of fields</h3>
746
778
<p>Please try to keep order of fields from max. to min. of size of each type of
747
779
fields, especially in structures:</p>
748
780
<div class="listingblock">
749
781
<div class="title">Example: Use:</div>
750
782
<div class="content">
751
<pre><span class="monospaced">long a;
755
787
<div class="listingblock">
756
788
<div class="title">Example: Instead of:</div>
757
789
<div class="content">
758
<pre><span class="monospaced">char c;
762
794
<p>It will help to reduce memory padding on some architectures. Note that this
763
795
applies only if this will not affect logical division of the structure. The
764
796
logical composition always takes precedence over this optimization, modulo
765
797
some very rare critical structures.</p>
766
<h4>Please do not use sizeof(struct item_struct_name)</h4>
798
<h3>Please do not use sizeof(struct item_struct_name)</h3>
767
799
<p>Instead use sizeof(*item) when possible.</p>
768
800
<div class="listingblock">
769
801
<div class="content">
770
<pre><span class="monospaced">struct example {
802
<pre><tt>struct example {
775
struct example *item;</span></pre>
807
struct example *item;</tt></pre>
777
809
<div class="listingblock">
778
810
<div class="title">Example: Use:</div>
779
811
<div class="content">
780
<pre><span class="monospaced">item = mem_alloc(sizeof(*item));
812
<pre><tt>item = mem_alloc(sizeof(*item));
781
813
memset(item, 0, sizeof(*item));
782
814
item->integers = mem_calloc(10, sizeof(*item->integers));
783
item->pointers = mem_calloc(10, sizeof(*item->pointers));</span></pre>
815
item->pointers = mem_calloc(10, sizeof(*item->pointers));</tt></pre>
785
817
<div class="listingblock">
786
818
<div class="title">Example: Instead of:</div>
787
819
<div class="content">
788
<pre><span class="monospaced">item = mem_alloc(sizeof(struct example));
820
<pre><tt>item = mem_alloc(sizeof(struct example));
789
821
memset(item, 0, sizeof(struct example));
790
822
item->integers = mem_calloc(10, sizeof(int));
791
item->pointers = mem_calloc(10, sizeof(void *));</span></pre>
823
item->pointers = mem_calloc(10, sizeof(void *));</tt></pre>
793
825
<p>The preferred form eases future changes in types, and maintain size vs type
795
<h4>Please postfix defined types with _T</h4>
827
<h3>Please postfix defined types with _T</h3>
796
828
<div class="listingblock">
797
829
<div class="content">
798
<pre><span class="monospaced">typedef int (some_func_T)(void *);
799
typedef long long our_long_T;</span></pre>
830
<pre><tt>typedef int (some_func_T)(void *);
831
typedef long long our_long_T;</tt></pre>
801
<h4>Please use mode_t and S_I???? macros instead of numeric modes</h4>
833
<h3>Please use mode_t and S_I???? macros instead of numeric modes</h3>
802
834
<div class="listingblock">
803
835
<div class="title">Example: Use:</div>
804
836
<div class="content">
805
<pre><span class="monospaced">mode_t mode = S_IRWXU | S_IRGRP | S_IROTH;</span></pre>
837
<pre><tt>mode_t mode = S_IRWXU | S_IRGRP | S_IROTH;</tt></pre>
807
839
<div class="listingblock">
808
840
<div class="title">Example: Instead of:</div>
809
841
<div class="content">
810
<pre><span class="monospaced">int mode = 0744;</span></pre>
842
<pre><tt>int mode = 0744;</tt></pre>
812
844
<p>Note that S_IREAD, S_IWRITE and S_IEXEC are obsolete, you should use S_IRUSR,
813
845
S_IWUSR, S_IXUSR instead.</p>
848
<div class="sectionbody">
815
849
<p>Please send unified patches only.</p>
816
850
<div class="listingblock">
817
851
<div class="title">Example: The recommended way is:</div>
818
852
<div class="content">
819
<pre><span class="monospaced">cp -a elinks/ elinks+mysuperfeature/
853
<pre><tt>cp -a elinks/ elinks+mysuperfeature/
820
854
cd elinks+mysuperfeature/
822
856
*clickety clickey*
848
882
important thing is to separate big changes to smaller ones and smaller ones,
849
883
breaking it to the "thinnest" possible level where the change is still
850
884
sufficiently self-contained.</p>
851
<h3>Advantages of <span class="monospaced">—enable-debug</span> configure option</h3>
886
<h2>Advantages of <tt>—enable-debug</tt> configure option</h2>
887
<div class="sectionbody">
852
888
<p>Since ELinks 0.4pre11, a memory debugger can be enabled using the
853
<span class="monospaced">—enable-debug</span> configure script option. It may help to find memleaks and more
889
<tt>—enable-debug</tt> configure script option. It may help to find memleaks and more
854
890
which is why everybody concerned with ELinks develepment should use it:</p>
855
<p>In 0.5 versions <span class="monospaced">—enable-debug</span> add some fancy things:
856
- many data integrity checking (see <span class="monospaced">lists.h</span>)
891
<p>In 0.5 versions <tt>—enable-debug</tt> add some fancy things:
892
- many data integrity checking (see <tt>lists.h</tt>)
857
893
- hotkey debugging: especially cool for translators, it highlights redundant
894
hotkeys in a menu. (See also po/perl/README.)
859
895
- more errors messages
860
896
- low bug tolerance: it will core dump on some errors instead of just writing
861
897
an error description.
862
898
- internal backtrace feature (always enabled if possible)
863
899
- and more…</p>
864
900
<p>Before sending a patch, always try to compile and test it with
865
<span class="monospaced">—enable-debug</span>, then in normal mode, then in <span class="monospaced">—fast-mem</span> mode. If it fails
901
<tt>—enable-debug</tt>, then in normal mode, then in <tt>—fast-mem</tt> mode. If it fails
866
902
to compile or execute in one of these modes, then rework it.</p>
867
903
<p>Happy hacking!</p>
869
905
<div id="footer">
870
906
<div id="footer-text">
871
Last updated 25-Jan-2006 04:49:54 CEST
907
Last updated 14-Apr-2007 12:33:17 EEST
added
removed
doc/html/hacking.html
