Mercurial > hg > index.cgi

annotate 00README.txt @ 577:e49d24f4a9a5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Correct bug in the object file output code leading to stack corruption It turns out leaving a pointer to a stack allocated temporary in a persistent data structure is not conducive to correct program operation. Undo the export check setup in the object file output sequence so a pointer to stack allocated memory is not left hanging when the function returns. This seems to correct at least one mysterious crash bug, and possibly others. Thanks to Boisy Pitre for reporting the crash bug that led to this discovery, as well as a previous crash bug that likely has the same root cause. Additional thanks to Ciaran Anscomb whose debugger wielding wizardry revealed the exact location of this particular bit of unbrilliance.
author William Astle <lost@l-w.ca>
date Sat, 03 Aug 2024 14:30:06 -0600
parents a0c9433dc0d4
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
341
48b1cc3991d8 Provide link to the official site in the readme file.
William Astle <lost@l-w.ca>
parents: 322
diff changeset
1 The official distribution point for lwtools is
48b1cc3991d8 Provide link to the official site in the readme file.
William Astle <lost@l-w.ca>
parents: 322
diff changeset
2 http://lwtools.projects.l-w.ca/. If you obtained this distribution from any
48b1cc3991d8 Provide link to the official site in the readme file.
William Astle <lost@l-w.ca>
parents: 322
diff changeset
3 other place, please visit the official site. You may have a modified or out
48b1cc3991d8 Provide link to the official site in the readme file.
William Astle <lost@l-w.ca>
parents: 322
diff changeset
4 of date version.
48b1cc3991d8 Provide link to the official site in the readme file.
William Astle <lost@l-w.ca>
parents: 322
diff changeset
5
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
6 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
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 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
9 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
10 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
11 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
12
361
4130ffdeb5c8 Add contributed support for building with Microsoft's compiler
William Astle <lost@l-w.ca>
parents: 341
diff changeset
13 There is some source code support for building with Microsoft's compiler on
4130ffdeb5c8 Add contributed support for building with Microsoft's compiler
William Astle <lost@l-w.ca>
parents: 341
diff changeset
14 Windows. However, this has been contributed by interested users and is not
4130ffdeb5c8 Add contributed support for building with Microsoft's compiler
William Astle <lost@l-w.ca>
parents: 341
diff changeset
15 well tested. Indeed, the primary maintainer has no access to such a system.
4130ffdeb5c8 Add contributed support for building with Microsoft's compiler
William Astle <lost@l-w.ca>
parents: 341
diff changeset
16
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
17 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
18 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
19
176
03f425c6c39c Added note about "make test" to readme
lost@l-w.ca
parents: 18
diff changeset
20 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
21 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
22 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
23
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
24 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
25
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
26 CONTRIBUTING
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
27 ============
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
28
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
29 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
30 following in mind.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
31
574
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
32 Evangelism
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
33 ----------
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
34
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
35 Any communication that includes evangelism for alternate revision control
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
36 systems, coding styles, development methodologies, or similar will be
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
37 deleted with all other contents ignored. So just don't do it and save
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
38 yourself and the project maintainers time.
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
39
322
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
40 Style
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
41 -----
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
42
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
43 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
44 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
45 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
46 likely met with extreme rudeness.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
47
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
48 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
49
574
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
50 * In general, match the formatting of the surrounding code, whether that
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
51 uses spaces or tabs. Otherwise, all indentation uses a single TAB
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
52 character for each step. That is a HARD tab, not a series of spaces. TABs
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
53 are assumed to be 4 characters though that will largely impact only lining
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
54 up comments and tabular code. If the actual formatting of the code is
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
55 critical, spaces may be used for that formatting but the actual initial
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
56 indentation of the lines MUST use TAB characters.
322
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
57 * 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
58 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
59 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
60 * 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
61 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
62 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
63 * 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
64 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
65 * 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
66 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
67 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
68 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
69 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
70 its parameter list.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
71
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
72 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
73 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
74
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
75 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
76 style may be less strict.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
77
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
78 Submitting
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
79 ----------
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
80
574
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
81 Any attempts to evangelize git or any other alternative revision control
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
82 system will be deleted with *all* other contents ignored.
a0c9433dc0d4 Updated submission guidelines including notes about evangelism. TLDR: Don't.
William Astle <lost@l-w.ca>
parents: 361
diff changeset
83
322
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
84 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
85 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
86 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
87 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
88 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
89
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
90 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
91 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
92 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
93
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
94 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
95 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
96 release.
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
97
69adaab94ffd Add notes about coding style and submission guidelines.
William Astle <lost@l-w.ca>
parents: 176
diff changeset
98 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
99 improvements or clarification of why or how you did something.