Mercurial > hg > index.cgi

annotate 00README.txt @ 322:69adaab94ffd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add notes about coding style and submission guidelines. As became clear from recent conversation, matching submitted code to the format of the existing code is not an obvious thing to do. (It should be but apparently it just doesn't occur to people.) Some description of the coding style is now present in the README. Additionally, submission guidelines have also been added to make it clear that patches (diffs) are the preferred means of providing code changes.
author William Astle <lost@l-w.ca>
date Mon, 03 Mar 2014 21:54:12 -0700
parents 03f425c6c39c
children 48b1cc3991d8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
1 This is LWTOOLS, a cross development system targetting the 6809 CPU.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
2
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
3 It consists of an assembler, lwasm, a linker, lwlink, and an archiver,
18
8eddaa2ab6c0 Added note about gnu make being suggested
lost@l-w.ca
parents: 0
diff changeset
4 lwar which should compile on any reasonably modern POSIX environment. If you
8eddaa2ab6c0 Added note about gnu make being suggested
lost@l-w.ca
parents: 0
diff changeset
5 have problems building, make sure you are using GNU make. Other make
8eddaa2ab6c0 Added note about gnu make being suggested
lost@l-w.ca
parents: 0
diff changeset
6 programs may work but GNU make is known to work.
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
7
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
8 To see if a quick build will work, just type "make". If it works, you're
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
9 ready to go ahead with "make install". This will install in /usr/local/bin.
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
10
176
03f425c6c39c Added note about "make test" to readme
lost@l-w.ca
parents: 18
diff changeset
11 If you feel adventurous, you can also run the test suite by running "make
03f425c6c39c Added note about "make test" to readme
lost@l-w.ca
parents: 18
diff changeset
12 test". However, be warned that it is likely not going to work unless you are
03f425c6c39c Added note about "make test" to readme
lost@l-w.ca
parents: 18
diff changeset
13 running on a fairly standard unix system with perl in /usr/bin/perl.
03f425c6c39c Added note about "make test" to readme
lost@l-w.ca
parents: 18
diff changeset
14
0
2c24602be78f Initial import from lwtools 3.0.1 version, with new hand built build system and file reorganization
lost@l-w.ca
parents:
diff changeset
15 See docs/ for additional information.
322
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
16
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
17 CONTRIBUTING
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
18 ============
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
19
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
20 If you wish to contribute patches or code to lwtools, please keep the
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
21 following in mind.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
22
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
23 Style
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
24 -----
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
25
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
26 The code formatting style must match the rest of the lwtools code. Code
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
27 submitted in the "1TBS" will be rejected out of hand. Attempts to convince
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
28 me to change my mind on this point will be routed to /dev/null at best and
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
29 likely met with extreme rudeness.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
30
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
31 C code should be formatted as follows:
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
32
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
33 * All indentation uses a single TAB character for each step. That is a HARD
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
34 tab, not a series of spaces. TABs are assumed to be 4 characters though
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
35 that will largely impact only lining up comments and tabular code. If the
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
36 actual formatting of the code is critical, spaces may be used for that
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
37 formatting but the actual initial indentation of the lines MUST use TAB
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
38 characters.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
39 * The opening brace for a block appears on the line below the control
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
40 structure that introduces it. It appears lined up with the preceding line
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
41 and nothing else appears on the same line.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
42 * Closing braces appear on a line by themselves ordinarily. The exception is
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
43 the "while" keyword in a "do-while" statement appears on the same line as
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
44 the closing brace for the block.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
45 * Case labels are lined up with the enclosing block (one level back from the
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
46 code of the block). The same guideline applies for ordinarily labels.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
47 * No spaces surround parentheses, brackets, or the dot operator. No space
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
48 precedes a comma but a space should follow it. Other operators should
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
49 usually be surrounded by spaces. A space should separate a keyword from
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
50 any surrounding except for sizeof() which should be written like a
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
51 function call. There is no space between a function name and the start of
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
52 its parameter list.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
53
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
54 In general, study the existing source formatting and copy the style. This is
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
55 what you should do anyway and the above should not be required.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
56
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
57 For code accepted to the contrib/ hierarchy, application of the above coding
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
58 style may be less strict.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
59
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
60 Submitting
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
61 ----------
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
62
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
63 When submitting code to lwtools, it should be submitted as a patch file (hg
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
64 diff or diff -u). DO NOT submit entire source files. Remember, others may be
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
65 working on changes, too, and your complete source files are difficult to
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
66 merge with such situations. By submitting complete source files, you are
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
67 making far more work for the maintainer and it is generally considered rude.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
68
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
69 Always specify what version of the source you based your patch on. If
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
70 possible, work off the default branch in the mercurial repository. At the
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
71 very least, make sure you are working with the most recent release.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
72
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
73 It is also worth checking with the maintainer before submitting a patch.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
74 There may be some reason why your pet feature is not present in the official
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
75 release.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
76
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
77 Finally, be prepared to receive a list of deficiencies or requests for
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
78 improvements or clarification of why or how you did something.