-
Notifications
You must be signed in to change notification settings - Fork 26
/
faq.html
1442 lines (1353 loc) · 63.5 KB
/
faq.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
layout: default
title: "FAQ (archive)"
---
<h1>Frequently Asked Questions about Harbour</h1>
<h2>David G. Holm <a href="mailto:[email protected]"><[email protected]></a></h2>
<strong>Revision:</strong> 1.45 <strong>Date:</strong> 2004-05-03 19:00:32
<h3>1. <a href="#1">Legal Stuff</a></h3>
<dl>
<dd>1.1. <a href="#2">Copyright</a></dd>
<dd>1.2. <a href="#3">License</a></dd>
<dd>1.3. <a href="#4">Warranty</a></dd>
<dd>1.4. <a href="#5">Trademarks</a></dd>
</dl>
<h3>2. <a href="#6">About Harbour</a></h3>
<dl>
<dd>2.1. <a href="#7">What is Harbour?</a></dd>
<dd>2.2. <a href="#8">Why develop Harbour?</a></dd>
<dd>2.3. <a href="#9">Who is developing Harbour?</a></dd>
<dd>2.4. <a href="#10">Who owns Harbour?</a></dd>
<dd>2.5. <a href="#11">So who do I blame when it all goes wrong?</a></dd>
<dd>2.6. <a href="#12">How did Harbour get started?</a></dd>
<dd>2.7. <a href="#13">What is "free software"?</a></dd>
<dd>2.8. <a href="#14">So is Harbour in the public domain?</a></dd>
<dd>2.9. <a href="#15">What is the GPL?</a></dd>
<dd>2.10. <a href="#16">Why was the GPL chosen as the license for Harbour?</a></dd>
<dd>2.11. <a href="#17">What is the Harbour exception?</a></dd>
<dd>2.12. <a href="#18">So why don't you use the LGPL?</a></dd>
<dd>2.13. <a href="#19">Will my applications be affected by the GPL?</a></dd>
</dl>
<h3>3. <a href="#20">Helping develop Harbour</a></h3>
<dl>
<dd>3.1. <a href="#21">How do I get started?</a></dd>
<dd>3.2. <a href="#22">What C compiler should I use?</a></dd>
<dd>3.3. <a href="#23">What other tools do I need?</a></dd>
<dd>3.4. <a href="#24">Where can I find the source?</a></dd>
<dd>3.5. <a href="#25">What is CVS and how do I use it?</a></dd>
<dd>3.6. <a href="#26">How do I build Harbour?</a></dd>
<dd>3.7. <a href="#27">What needs working on?</a></dd>
<dd>3.8. <a href="#28">Are there any development guidelines?</a></dd>
<dd>3.9. <a href="#29">Is it ok to extend the language with some spiffy new feature?</a></dd>
<dd>3.10. <a href="#30">So what's with all these language extensions then?</a></dd>
<dd>3.11. <a href="#31">I cannot code C, how can I help development?</a></dd>
<dd>3.12. <a href="#32">I've got loads of Clipper code I can donate, what shall I do?</a></dd>
<dd>3.13. <a href="#33">I cannot submit Clipper code either, can I still help anyway?</a></dd>
</dl>
<h3>4. <a href="#34">The Harbour mailing lists</a></h3>
<dl>
<dd>4.1. <a href="#35">Is there a developer's mailing list?</a></dd>
<dd>4.2. <a href="#36">Is there a user's mailing list?</a></dd>
<dd>4.3. <a href="#37">Is there a general discussion mailing list?</a></dd>
<dd>4.4. <a href="#38">How do I remove myself from the mailing lists?</a></dd>
<dd>4.5. <a href="#39">Are there any rules on the lists?</a></dd>
<dd>4.6. <a href="#40">Are the lists archived anywhere?</a></dd>
<dd>4.7. <a href="#41">Are there any newsgroups for Harbour?</a></dd>
</dl>
<h3>5. <a href="#42">Installing Harbour</a></h3>
<dl>
<dd>5.1. <a href="#43">Where can I get pre-built binaries?</a></dd>
</dl>
<h3>6. <a href="#44">General Harbour questions</a></h3>
<dl>
<dd>6.1. <a href="#45">When will Harbour be finished?</a></dd>
<dd>6.2. <a href="#46">Are applications <attribute> than CA-Clipper applications?</a></dd>
<dd>6.3. <a href="#47">What advantages does Harbour have over other Clipper compilers?</a></dd>
<dd>6.4. <a href="#48">What advantages do other Clipper compilers have over Harbour?</a></dd>
<dd>6.5. <a href="#49">Will Harbour support existing CA-Clipper 3rd party products?</a></dd>
<dd>6.6. <a href="#50">Is Harbour a Windows development tool?</a></dd>
<dd>6.7. <a href="#51">What platforms are supported by Harbour?</a></dd>
</dl>
<h3>7. <a href="#52">Pointers and links</a></h3>
<dl>
<dd>7.1. <a href="#53">Harbour related links</a></dd>
<dd>7.2. <a href="#54">Articles about Harbour</a></dd>
<dd>7.3. <a href="#55">Free (in either sense of the word) development tool links</a></dd>
<dd>7.4. <a href="#56">Clipper related links</a></dd>
<dd>7.5. <a href="#57">Free software related links</a></dd>
<dd>7.6. <a href="#58">Other handy links</a></dd>
</dl>
<h3>8. <a href="#59">Administrative information</a></h3>
<dl>
<dd>8.1. <a href="#60">Document URL.</a></dd>
<dd>8.2. <a href="#62">Feedback about the FAQ.</a></dd>
<dd>8.3. <a href="#63">Document history</a></dd>
</dl>
<hr>
<h3><a id="1"></a>1. Legal Stuff</h2>
<hr>
<h2><a id="2"></a>1.1. Copyright</h2>
<p>This document as a whole is copyrighted © 1999–2004 David G. Holm.
Some portions of the document may be copyright other individual authors
and are used with their permission. This document would not exist were
it not for the efforts of the original maintainer, Dave Pearson.
</p>
<hr>
<h2><a id="3"></a>1.2. License</h2>
<p>This document should be considered as free software, distributed under the
terms of the GNU General Public License, version 2. For details see the file
LICENSE.txt.
</p>
<hr>
<h2><a id="4"></a>1.3. Warranty</h2>
<p>This document is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
</p>
<hr>
<h2><a id="5"></a>1.4. Trademarks<a id="Trademarks"></a></h2>
<p>This document may make reference to various trademarks, these trademarks are
acknowledged and are only used for reference purposes.
</p>
<hr>
<h3><a id="6"></a>2. About Harbour</h2>
<hr>
<h2><a id="7"></a>2.1. What is Harbour?<a id="WhatIsHarbour"></a></h2>
<p>Harbour is a
<a href="#FreeSoftware">free software</a> compiler for the
xBase superset language often referred to as Clipper (the language that is
implemented by the compiler
<a href="#Trademarks">CA-Clipper</a>).
Harbour's chosen base implementation is, for the moment, the 5.2e version of
<a href="#Trademarks">CA-Clipper</a>. This isn't to say that the
additions found in 5.3 won't make it into Harbour, it simply reflects the
fact that many Clipper programmers see 5.2e as the "last best"
implementation of Clipper.
</p>
<p>If the 5.3 extensions to the language are important to you please feel free
to
<a href="#WhenFinished">contribute to the project</a>.
</p>
<hr>
<h2><a id="8"></a>2.2. Why develop Harbour?</h2>
<p>There are probably more reasons for developing Harbour than there are
Harbour developers. To gain a better understanding of why some
<a href="#FreeSoftware">free software</a> gets developed you might want to
have a read of
<a href="https://web.archive.org/web/catb.org/~esr/writings/cathedral-bazaar/">The Cathedral and the Bazaar</a>.
</p>
<hr>
<h2><a id="9"></a>2.3. Who is developing Harbour?<a id="WhoDevelopers"></a></h2>
<p>Many people. There are a small handful of people who could be called the
"core development team" but the actual set of people who are
contributing to the project is constantly in flux. Anyone can join the
"development team" and, if you've got something to offer the
project, you'll be more than welcome.
</p>
<p>Anyone wondering who the core developers are should pop over to the
<a href="/">Harbour project website</a> and look at the
<a href="/crew.htm">crew list</a>.
</p>
<hr>
<h2><a id="10"></a>2.4. Who owns Harbour?</h2>
<p>Nobody <em>owns</em> Harbour but many people hold the copyright on portions of
Harbour.
</p>
<hr>
<h2><a id="11"></a>2.5. So who do I blame when it all goes wrong?<a id="Warranty"></a></h2>
<p>Harbour is
<a href="#FreeSoftware">free software</a> and comes with
<strong>no warranty</strong>. The warranty statement is that which is
provided by the
<a href="#GPL">GPL</a>:
<blockquote>
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
</blockquote>
</p>
<hr>
<h2><a id="12"></a>2.6. How did Harbour get started?</h2>
<p>The idea of a
<a href="#FreeSoftware">free software</a> Clipper compiler
has been floating around for a long time and the subject has often cropped
up in discussion on <a href="news:comp.lang.clipper">comp.lang.clipper</a>.
Actual work to get something developed started
early in 1999 when Antonio Linares <a href="https://groups.google.com/forum/#!msg/comp.lang.clipper/D6_Q5GUKae8/T1AG-P2WSVsJ">started a thread</a> to
discuss some ideas about developing a Clipper grammar using Lex and Yacc.
</p>
<p>The rest, as they say, is history (that history might form the basis of
another document should I ever get the time to compile it).
</p>
<hr>
<h2><a id="13"></a>2.7. What is "free software"?<a id="FreeSoftware"></a></h2>
<p>In general terms free software is one phrase for describing software that
comes with certain freedoms, the free doesn't speak about the price, it
speaks about your freedoms to use the software. A common suggestion is that
you think "free speech" instead of "free beer".
</p>
<p>See <a href="https://www.gnu.org/philosophy/free-sw.html">https://www.gnu.org/philosophy/free-sw.html</a> for the Free
Software Foundation's definition of "free software".
</p>
<p>A related term is OpenSource, you can find out more about the idea of
OpenSource at
<a href="https://www.opensource.org/">https://www.opensource.org/</a>. You
might also want to note that the FSF don't consider OpenSource and Free
Software to be the same thing, see
<a href="https://www.gnu.org/philosophy/free-software-for-freedom.html">https://www.gnu.org/philosophy/free-software-for-freedom.html</a>
for more details.
</p>
<hr>
<h2><a id="14"></a>2.8. So is Harbour in the public domain?</h2>
<p>No, Harbour isn't in the
<a href="https://www.gnu.org/philosophy/categories.html">public domain</a>.
Most parts of Harbour are copyrighted works and you should respect those
copyrights as you would any other copyright. With a small number of exceptions
each of the <a href="#WhoDevelopers">Harbour authors</a> have placed their
code under Harbour's chosen license, currently that license is the
<a href="#GPL">GPL</a> and/or the GPL with
<a href="#HarbourException">Harbour exception</a>.
</p>
<p>Note, however, that some files that are part of harbour have been placed in
the public domain.
</p>
<hr>
<h2><a id="15"></a>2.9. What is the GPL?<a id="GPL"></a></h2>
<p>The <a href="https://www.gnu.org/licenses/license-list.html#GPLv2">GPL</a> is
the license of the <a href="https://www.gnu.org/">GNU system</a>, it is a
<a href="#FreeSoftware">free software</a> license. You might also hear it
referred to as the
<a href="https://www.gnu.org/copyleft/copyleft.html">Copyleft</a>.
</p>
<p>The GPL is currently the license under which parts of Harbour are released,
other parts of Harbour are under the GPL plus the
<a href="#HarbourException">Harbour exception</a>.
</p>
<hr>
<h2><a id="16"></a>2.10. Why was the GPL chosen as the license for Harbour?<a id="WhyGPL"></a></h2>
<p>That's really a question best asked of each of the Harbour copyright
holders. A simple answer would be that the GPL is seen as one of the more
restrictive <a href="#FreeSoftware">free software</a> licenses and, for
that reason more than any other, it appeared to give the maximum amount of
freedom and at the same time the correct degree of control over use and
distribution.
</p>
<hr>
<h2><a id="17"></a>2.11. What is the Harbour exception?<a id="HarbourException"></a></h2>
<p>There is one small wrinkle regarding the use of the GPL as the license for
Harbour. Harbour comes in a number of parts, these can best be described as
the compiler (including pre-processor), the virtual machine and the run-time
library. The GPL dictates that anyone distributing binary versions of GPLd
code must make an offer of providing the source and that the code linked
against the GPLd code must also fall under the GPL. Failure to do so is a
breach of license.
</p>
<p>In Harbour terms this means different things depending on which portion of
Harbour you are considering. The compiler itself can live under the GPL, it
isn't part of the run-time and so poses no problem. This isn't true for the
<a href="https://github.com/{{ site.repo_slug }}/tree/{{ site.repo_branch }}/src/vm">HVM</a>
and
<a href="https://github.com/{{ site.repo_slug }}/tree/{{ site.repo_branch }}/src/rtl">RTL</a>
because they get linked into your application and so would require that your
code be distributed under a compatible license. While the Harbour developers
would like to see you develop <a href="#FreeSoftware">free software</a> they
have decided to let you make this choice.
</p>
<p>To solve this problem the developers have employed the "Harbour
Exception". This idea comes from the GPL exception used by <a href="https://www.gnu.org/software/guile/guile.html">guile</a>. In effect,
the exception states that you must observe the GPL except when the code in
question is being used as the HVM and RTL of an application compiled with
Harbour.
</p>
<p>The wording of the exception currently reads:
<blockquote>
The exception is that, if you link the Harbour libraries with other files to
produce an executable, this does not by itself cause the resulting executable
to be covered by the GNU General Public License. Your use of that executable
is in no way restricted on account of linking the Harbour library code into
it.
</blockquote>
<blockquote>
This exception does not however invalidate any other reasons why the
executable file might be covered by the GNU General Public License.
</blockquote>
<blockquote>
This exception applies only to the code released by the Harbour Project under
the name Harbour. If you copy code from other Harbour Project or Free
Software Foundation releases into a copy of Harbour, as the General Public
License permits, the exception does not apply to the code that you add in
this way. To avoid misleading anyone as to the status of such modified
files, you must delete this exception notice from them.
</blockquote>
<blockquote>
If you write modifications of your own for Harbour, it is your choice
whether to permit this exception to apply to your modifications.
If you do not wish that, delete this exception notice.
</blockquote>
Please note that the original wording of the exception was based on an
earlier version of the guile exception. That version of the exception was
less verbose and less clear. The wording of that version read:
<blockquote>
The exception is that if you link the Harbour Runtime Library (HRL) and/or
the Harbour Virtual Machine (HVM) with other files to produce an executable,
this does not by itself cause the resulting executable to be covered by the
GNU General Public License. Your use of that executable is in no way
restricted on account of linking the RTL and/or HVM code into it.
</blockquote>
The Harbour sources are being converted over to the new exception as each
copyright holder makes the change. The intention is that every item of
source that uses the Harbour exception will clearly use the more verbose
version.</p>
<hr>
<h2><a id="18"></a>2.12. So why don't you use the LGPL?</h2>
<p>Given
<a href="#HarbourException">the above</a> it might be reasonable to
ask why the Harbour developers didn't elect to use the
<a href="https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">LGPL</a>
instead. The reason simply comes down to the requirements of the LGPL and
what can be reasonably asked of anyone who wishes to make use of Harbour.
</p>
<p>The LGPL requires that any binary distribution of the LGPLd code (in other
words, an application compiled with Harbour and linked against the HVM and
RTL) should be distributed in a method that allows the user to re-link the
application against different and/or later copies of the code under the
LGPL. This is an unreasonable and unworkable requirement as far as the
Harbour developers are concerned.
</p>
<p>For the most part it would be fine on platforms where an application can be
linked against a dynamic version of the HVM and RTL, but any platform that
doesn't support dynamic linking (PC/MS/DR/Open/Free-DOS for example) would
be effectively shut out of Harbour usage. The Harbour developers consider
this to be a reduction of freedom and this isn't acceptable for free
software.
</p>
<hr>
<h2><a id="19"></a>2.13. Will my applications be affected by the GPL?</h2>
<p>No, the
<a href="#HarbourException">Harbour exception</a> seeks to ensure
that, when you build an application with Harbour, compiling with the Harbour
compiler and linking against the HVM and RTL, your rights to license your
own code are not in any way affected.
</p>
<p>Harbour's license is there to try and protect the freedom offered by the
Harbour developers. Harbour's license isn't there to try and force you to
choose a specific license.
</p>
<p>Be assured that it isn't the intention of the
<a href="#WhoDevelopers">Harbour developers</a> that your applications will
have to be released as
<a href="https://www.gnu.org/philosophy/free-sw.html">free software</a>.
Supporting free software would be the right thing to do but the Harbour
developers have decided not to insist on this; we think it is more useful in
this situation to set up Harbour's license so that it does not make any
conditions on the status of your work that was built with and against
Harbour.
</p>
<p>As always, don't take anyone else's word for this stuff, when in doubt, read
the license. If you're still in doubt pay someone who knows what they are
doing to read the license for you. Hopefully you do this with licenses for
your other development tools, Harbour is no different, it has a license that
you need to understand.
</p>
<hr>
<h3><a id="20"></a>3. Helping develop Harbour</h2>
<hr>
<h2><a id="21"></a>3.1. How do I get started?</h2>
<p>The first thing you should do is join the
<a href="#DevMailList">developer's mailing list</a> and read the mail for
a few days to get a feel for what is going on. You might also want to take
a look at <a href="#MailArchives">the archives</a> too.
</p>
<hr>
<h2><a id="22"></a>3.2. What C compiler should I use?<a id="WhatC"></a></h2>
<p>What C compiler do you want to use?</p>
<p>The
<a href="#WhoDevelopers">Harbour developers</a> consider GNU
<a href="https://www.gnu.org/software/gcc/">GCC</a> to be <em>the</em>
supported compiler of the Harbour project, use of the
<a href="https://www.gnu.org/software/gcc/">GCC</a> port for your chosen
platform is encouraged.
</p>
<p>However, should you wish to use a different C compiler your contribution to
make it work is more than welcome. Currently the following C compiler and
platform combinations are supported by someone in the development team:
<ul>
<li>
Microsoft Windows
<ul>
<li><a href="https://www.gnu.org/software/gcc/">GCC</a>
(<a href="https://sourceforge.net/projects/mingw-w64/">mingw-w64</a>)
</li>
<li>Microsoft Visual C++ 10/11/12</li>
<li>IBM Visual Age for C++</li>
</ul>
</li>
<li>
DOS 32-bit
<ul>
<li><a href="https://www.gnu.org/software/gcc/">GCC</a> (<a href="https://www.delorie.com/djgpp/">DJGPP</a>)</li>
<li>Watcom C/C++</li>
</ul>
</li>
<li>
<a href="https://en.wikipedia.org/wiki/Linux">GNU/Linux</a>
<ul>
<li><a href="https://www.gnu.org/software/gcc/">GCC</a> (various versions).</li>
</ul>
</li>
<li>
macOS/iOS
<ul>
<li><a href="https://developer.apple.com/xcode/">Xcode</a></li>
</ul>
</li>
</ul>
Instructions on how to build Harbour with the above compilers should reside
in the <code>doc</code> directory of the Harbour source tree. If such
documentation is missing please consider asking about it on the
<a href="#DevMailList">development mailing list</a> and, once you've got the
information, formatting it and placing it in the <code>doc</code> directory
to help others who may wish to ask the same question.</p>
<hr>
<h2><a id="23"></a>3.3. What other tools do I need?</h2>
<p>To build Harbour you'll need the following tools:</p>
<p>
<ul>
<li>
A C compiler.
<p>Please see the FAQ section entitled
<a href="#WhatC">What C compiler should I use?</a> for more details on choosing a C compiler.
</p>
</li>
<li>
A make utility.
<p>Most platform/compiler combinations within Harbour make use of <a href="https://www.gnu.org/software/make/">GNU make</a>, some developers
use other make utilities, you'll need to speak to them if you want to ignore
the GNU make files.
</p>
<p>You should be able to find GNU make at:</p>
<p>
<ul>
<li>
Microsoft Windows
<p><a href="https://www.steve.org.uk/Software/make/">https://www.steve.org.uk/Software/make/</a></p>
</li>
<li>
GNU/Linux and macOS
<p>Most (if not all) GNU/Linux distributions come with GNU make.</p>
</li>
<li>
DOS
<p><a href="https://mirrorservice.org/sites/ftp.delorie.com/pub/djgpp/deleted/v2gnu/mak379b.zip">https://mirrorservice.org/sites/ftp.delorie.com/pub/djgpp/deleted/v2gnu/mak379b.zip</a></p>
</li>
</ul>
</p>
</li>
<li>
A copy of flex:
<p>
<ul>
<li>
Windows
<p>See the <a href="https://sourceforge.net/projects/harbour-project/files/">harbour download page</a>.</p>
</li>
<li>
GNU/Linux
<p>Most GNU/Linux distributions come with a copy of flex.</p>
</li>
<li>
DOS
<p>The <a href="https://mirrorservice.org/sites/ftp.delorie.com/pub/djgpp/current/v2gnu/">DJGPP</a> distribution of
GNU tools for DOS includes a port of flex.
</p>
</li>
</ul>
</p>
</li>
<li>
A copy of <a href="https://www.gnu.org/software/bison/bison.html">bison</a>:
<p>
<ul>
<li>
Windows
<p>See the <a href="https://sourceforge.net/projects/harbour-project/files/">harbour download page</a>.</p>
</li>
<li>
GNU/Linux
<p>Most GNU/Linux distributions come with a copy of bison.</p>
</li>
<li>
DOS
<p>The <a href="https://mirrorservice.org/sites/ftp.delorie.com/pub/djgpp/current/v2gnu/">DJGPP</a> distribution of
GNU tools for DOS includes a port of bison.
</p>
</li>
</ul>
</p>
</li>
<li>
A CVS client for your chosen platform.
<p>Please see the FAQ section entitled
<a href="#WhatIsCVS">What is CVS and how do I use it?</a> for more details
on getting a CVS client for your environment.
</p>
</li>
</ul>
</p>
<hr>
<h2><a id="24"></a>3.4. Where can I find the source?</h2>
<p>There are three methods of getting the source for harbour, which method you
use will depend on how up-to-date you feel you need to be.
<ul>
<li>
The unstable snapshot
<p>A snapshot of the source is made available on the
<a href="https://sourceforge.net/projects/harbour-project/files/">Harbour
project download web page</a>. Please be aware that this is an
<strong>unstable</strong> snapshot. Using this source could make all sorts
of horrible things happen - it might not even compile. You have been warned.
</p>
</li>
<li>
The stable snapshot
<p>Once in a while a stable snapshot of the Harbour source is made available
from the
<a href="https://sourceforge.net/projects/harbour-project/files/">download page</a>
of the <a href="/">Harbour project website</a>. These snapshots are referred
to as "releases" and are considered stable in that the source will
compile and there are no known showstoppers in the compiler, virtual machine
or run-time library.
</p>
<p>If you like to play with alpha quality software but want to feel safe doing
so then a stable release is for you.
</p>
</li>
<li>
Direct CVS access
<p>The best and most direct method of getting Harbour source is from the CVS
server. This is where the
<a href="#WhoDevelopers">Harbour developers</a>
work on the source for Harbour (actually, they all work on their own
machines, this server gives them, in effect, a virtual shared directory).
</p>
<p>If you intend to work with Harbour built from the CVS itself you should
really consider subscribing to the
<a href="#DevMailList">developer's mailing list</a>.
</p>
</li>
</ul>
</p>
<p>Please note that if you do want to help develop Harbour then the last option
is the best option (and, in the long term, the only useful option for all
concerned).
</p>
<hr>
<h2><a id="25"></a>3.5. What is CVS and how do I use it?<a id="WhatIsCVS"></a></h2>
<p>Before proceeding you should probably have a good read of the
<a href="https://web.archive.org/web/20140418005034/ximbiot.com/cvs/cvshome/docs/blandy.html">introduction to CVS by Jim Blandy</a>.
Reading this document should save you a lot of confusion later
on.
</p>
<p>To use the CVS server you first need to get a copy of the CVS client
software for your operating system:
</p>
<p>
<ul>
<li>
Microsoft Windows
<p>See <a href="https://web.archive.org/web/19990429101637/www.cyclic.com/cvs/windows.html">www.cyclic.com/cvs/windows.html</a> for more details.</p>
</li>
<li>
GNU/Linux
<p>Many GNU/Linux distributions come with the CVS client packaged as part of
the distribution.</p>
</li>
<li>
macOS
<p>See <a href="https://brew.sh/">Homebrew</a> for more details.</p>
</li>
<li>
DOS 16-bit/32-bit
<p>See the DOS section at <a href="https://web.archive.org/web/19990429101637/www.cyclic.com/cvs/other.html">www.cyclic.com/cvs/other.html</a>.</p>
</li>
<li>
Other
<p>If you are building Harbour with an operating system not listed then please
contact the FAQ maintainer with full details so that this list can be
updated.
</p>
</li>
</ul>
</p>
<p>Once you have got your CVS client installed you can gain anonymous access to
the Harbour CVS server. Depending on platform, the first thing you need to
do is set the <code>CVSROOT</code> environment variable to:
</p>
<p>
<blockquote>
<code>
<pre>
:pserver:[email protected]:/cvsroot/harbour-project
</pre>
</code>
</blockquote>
</p>
<p>In addition to the above some environments might require extra information.
For example, the DOS, Windows and OS/2 CVS clients need to be given two
extra environment variables, <code>HOMEDRIVE</code> and <code>HOMEPATH</code>. These two
environment variables tell the CVS client where the source will live
locally. For example, if your Harbour development directory is at
<code>S:\FREESOFT\HARBOUR</code> you'd set:
</p>
<p>
<blockquote>
<code>
<pre>
SET HOMEDRIVE=S
SET HOMEPATH=\FREESOFT\HARBOUR\
</pre>
</code>
</blockquote>
</p>
<p>Users of the Windows client have reported that the <code>HOMEPATH</code> environment
variable must start with and finish with a directory separator. Users of the
DOS client have reported that the <code>HOMEDRIVE</code> environment variable must
end with a colon.
</p>
<p>Ensure that your harbour directory is created and change into it. Then run:</p>
<p>
<blockquote>
<code>
<pre>
cvs login
</pre>
</code>
</blockquote>
</p>
<p>and press enter when prompted for a password. Now run:</p>
<p>
<blockquote>
<code>
<pre>
cvs extract -P harbour
</pre>
</code>
</blockquote>
</p>
<p>to get a copy of the Harbour CVS repository (users of the DOS client have
reported that it doesn't have the <code>extract</code> command and that the
<code>checkout</code> command should be used instead, I'm also told that the CVS
client on GNU/Linux requires that you use <code>checkout</code>).
</p>
<p><strong>Note</strong>: The CVS commands and directories are case sensitive: <code>harbour</code>
must be in all lower case.
</p>
<p>Later, when you want to get changes from the CVS, you can do one of two
things:
</p>
<p>
<ul>
<li>Repeat the <code>extract</code> command from your Harbour directory.</li>
<li>From your Harbour directory run '<code>cvs update</code>'.</li>
</ul>
</p>
<p>If you have problems after reading the above please consider reading the
<a href="https://web.archive.org/web/20140418005034/ximbiot.com/cvs/cvshome/docs/blandy.html">CVS introduction</a>
and also the documentation for the CVS client you've installed. If, after
reading both those documents, you are still having problems you should drop
a polite message into the <a href="#DevMailList">developer's mailing list</a>
detailing your platform, environment, all the steps you performed and the
exact nature of the problem.
</p>
<hr>
<h2><a id="26"></a>3.6. How do I build Harbour?</h2>
<p>The method used to build Harbour may differ from platform to platform and
even from tool set to tool set. Please have a good read of the files in the
<code>doc</code> directory of the Harbour source.
</p>
<hr>
<h2><a id="27"></a>3.7. What needs working on?<a id="WhatToDo"></a></h2>
<p>See <a href="https://raw.githubusercontent.com/{{ site.repo_slug }}/{{ site.repo_branch }}/doc/todo.txt">TODO</a> in the root directory of the harbour sources.</p>
<p>If you're looking to get stuck into some Harbour development you'd do
well to subscribe to the
<a href="#DevMailList">developer's mailing list</a>, hang out there for a few days to get a feel for what is going on and
then either start contributing bug fixes (always a good way of getting
started) or simply announce your intention to work on an entry on the TODO list.
</p>
<hr>
<h2><a id="28"></a>3.8. Are there any development guidelines?</h2>
<p>Not as such no. That said, if you are going to cut some code for Harbour you
might want to consider the following random observations:
<ul>
<li>Harbour is written in both C and itself. As much as possible we stick
with ANSI C (any non ANSI code should be guarded with pre-processor
directives).
</li>
<li>Too many comments are better than too few comments.</li>
<li>An ounce of testing can save a ton of debugging. Please ensure that,
when you change code, you attempt to compile and use Harbour before
submitting changes.
</li>
<li>English is the nearest we've got to a common language. Where possible
please code in, comment in and document in English.
</li>
<li>Please don't make use of code you don't have the right to use. For
example, don't go copying
<a href="#Trademarks">CA-Clipper</a> header
files to make Harbour header files.
</li>
<li>Have fun.</li>
</ul>
</p>
<hr>
<h2><a id="29"></a>3.9. Is it ok to extend the language with some spiffy new feature?</h2>
<p>As a rule, no. As
<a href="#WhatIsHarbour">stated earlier</a> Harbour is
designed, as much as possible, to be a
<a href="#Trademarks">CA-Clipper</a> 5.2e compatible Clipper compiler (with some 5.3 bits
thrown in when it makes sense). As such, until such a time as we're all done
on the compatibility front, the
<a href="#WhoDevelopers">Harbour developers</a> would prefer to keep the language as "pure" as
possible.
</p>
<p>That said, if you've got an idea for something you think should be added to
the language please feel free to make your case on the
<a href="#DevMailList">developer's mailing list</a>. Please note that emails along the lines of
"I want feature <em>X</em> because I'd like to have it" don't cut
much ice. Emails to that effect that actually offer a working patch might
cut a little ice. Preferably, you'll come to the list with a well thought
out and documented case for the addition of a new language extension and
you'll be willing to discuss the proposal.
</p>
<p>Also, don't be upset if it is rejected, this is
<a href="#FreeSoftware">free software</a> after all, if you really feel that the extension is
required you can maintain a patch in parallel or, if you really must (but
we'd prefer if you didn't), you could maintain a forked distribution of
Harbour.
</p>
<hr>
<h2><a id="30"></a>3.10. So what's with all these language extensions then?</h2>
<p>Hey, come on, there aren't that many!</p>
<p>Seriously, ok, hands up, you've got us bang to rights. Harbour does include
some extensions to "standard" Clipper but you'll notice that
these extensions are, on the whole, either replacements for "must
have" 3rd party add-ons that people used with
<a href="#Trademarks">CA-Clipper</a> or they are a feature that is native to
<a href="#ClipperCompilers">other Clipper compiler implementations</a>.
</p>
<hr>
<h2><a id="31"></a>3.11. I cannot code C, how can I help development? </h2>
<p>How about doing some Clipper (the language) coding? Parts of Harbour have
been and can be written in itself. Why not look at
<a href="#WhatToDo">what needs doing</a> in the run-time library and seeing what could be
coded using normal Clipper code?
</p>
<p>Don't worry about speed for the moment, chances are the functions you're
thinking about are not speed critical, even if they are someone can come
along and, using your implementation as the base design, re-code it in C for
extra speed (if re-coding will speed it up).
</p>
<hr>
<h2><a id="32"></a>3.12. I've got loads of Clipper code I can donate, what shall I do?</h2>
<p>Harbour isn't a project to create a repository of free Clipper code so,
unless your code directly implements a core Clipper run-time library
function it probably isn't a lot of use to Harbour.
</p>
<p>However, don't let your code go to waste, why not consider starting a
non-compiler specific but cross-platform free software Clipper library that
will benefit programmers using any of the
<a href="#ClipperCompilers">Clipper compiler implementations</a>?
</p>
<hr>
<h2><a id="33"></a>3.13. I cannot submit Clipper code either, can I still help anyway?</h2>
<p>You could help out any number of ways. Documentation is one area where
volunteers are needed (it's a dirty job but someone has to do it). Perhaps
you could help maintain the
<a href="#WhatToDo">TODO list</a>?
How about creating and maintaining binary snapshots of each of the releases?
</p>
<p>Simply put, if you really want to help Harbour development, you'll find a
way.
</p>
<hr>
<h3><a id="34"></a>4. The Harbour mailing lists</h2>
<hr>
<h2><a id="35"></a>4.1. Is there a developer's mailing list?<a id="DevMailList"></a></h2>
<p>Yes, the list lives at <a href="mailto:[email protected]">[email protected]</a>. To subscribe to the Harbour development mailing
list simply send an email to
<a href="mailto:[email protected]">[email protected]</a> and in the email say
"subscribe". Alternatively you can subscribe via the World Wide
Web at <a href="https://web.archive.org/web/20041015022612/www.matrixlist.com/mailman/listinfo/harbour/">www.matrixlist.com/mailman/listinfo/harbour/</a>.
</p>
<hr>
<h2><a id="36"></a>4.2. Is there a user's mailing list?<a id="UserMailList"></a></h2>
<p>Yes, the list lives at <a href="mailto:[email protected]">[email protected]</a>. To subscribe to the Harbour user's mailing
list simply send an email to
<a href="mailto:[email protected]">[email protected]</a> and in the email say
"subscribe". Alternatively you can subscribe via the World Wide
Web at <a href="https://web.archive.org/web/20041015112423/www.matrixlist.com/mailman/listinfo/harbourusers/">www.matrixlist.com/mailman/listinfo/harbourusers/</a>.
</p>
<hr>
<h2><a id="37"></a>4.3. Is there a general discussion mailing list?<a id="DisMailList"></a></h2>
<p>Yes, the list lives at <a href="mailto:[email protected]">[email protected]</a>. To subscribe to the Harbour discussion mailing
list simply send an email to
<a href="mailto:[email protected]">[email protected]</a> and in the email say
"subscribe". Alternatively you can subscribe via the World Wide
Web at <a href="https://web.archive.org/web/20041015111853/www.matrixlist.com/mailman/listinfo/harbourtalk/">www.matrixlist.com/mailman/listinfo/harbourtalk/</a>.
</p>
<hr>
<h2><a id="38"></a>4.4. How do I remove myself from the mailing lists?</h2>
<p>Every email that comes from the Harbour mailing lists contains instructions
for unsubscribing. The information is in the header of the email. For those
people with MUAs that don't allow them to read such vital information here
are the headers at the time of writing:
</p>
<p>
<dl>
<dt><strong>harbour</strong>
<dd>
<p>
<blockquote><code>
<strong>List-Unsubscribe:</strong> <a href="https://web.archive.org/web/20041015022612/www.matrixlist.com/mailman/listinfo/harbour/">www.matrixlist.com/mailman/listinfo/harbour</a>, <a href="mailto:[email protected]?subject=unsubscribe">mailto:[email protected]?subject=unsubscribe</a>
</code>
</blockquote>
</p>
<dt><strong>harbourusers</strong>
<dd>
<p>
<blockquote><code>
<strong>List-Unsubscribe:</strong> <a href="https://web.archive.org/web/20041015112423/www.matrixlist.com/mailman/listinfo/harbourusers/">www.matrixlist.com/mailman/listinfo/harbourusers</a>, <a href="mailto:[email protected]?subject=unsubscribe">mailto:[email protected]?subject=unsubscribe</a>
</code>
</blockquote>
</p>
<dt><strong>harbourtalk</strong>
<dd>
<p>
<blockquote><code>
<strong>List-Unsubscribe:</strong> <a href="https://web.archive.org/web/20041015111853/www.matrixlist.com/mailman/listinfo/harbourtalk/">www.matrixlist.com/mailman/listinfo/harbourtalk</a>, <a href="mailto:[email protected]?subject=unsubscribe">mailto:[email protected]?subject=unsubscribe</a>
</code>
</blockquote>
</p>
</dl>
No matter what mailing list you are on it is always a good idea to never
subscribe unless you know how to unsubscribe. This can be as simple as
keeping the subscription confirmation message that many lists send out (they
often include instructions on how to unsubscribe).</p>
<hr>
<h2><a id="39"></a>4.5. Are there any rules on the lists?</h2>
<p>There are no <em>rules</em> as such but you might want to consider the following
guidelines:
</p>
<p>
<ul>
<li>Try to stay on topic. The
<a href="#DevMailList">developer's list</a> is for Harbour design and development issues, the
<a href="#UserMailList">user's list</a> is for Harbour usage discussion and
the
<a href="#DisMailList">discussion list</a> is for general Harbour
discussion.
</li>
<li>Try not to mail binaries. Sometimes it is necessary on the development
list, if so, try to keep the size down, the developer's list is <strong>very
busy</strong>.
</li>
<li>Stick to plain text formatted email,
<a href="https://web.archive.org/web/20081204041319/www.expita.com/nomime.html">turn off</a> any HTML
"features", content is far more important than form in the
Harbour lists.
</li>
<li>Stick to English. This isn't a UK/US/AU-centric thing, it just so
happens that English is more widely comprehended than any other language
available on the lists. If you use English you'll be read by the maximum
number of people.
</li>
<li>Don't use the subject as the message. Single line messages where the
message is in the subject don't carry a lot of information. Be verbose,
you'll stand a better chance of being understood.
</li>
<li>Do use the subject to outline a message. A descriptive subject is more
likely to catch the eye of the people whose eye you wanted to catch.
</li>
</ul>
</p>
<p>The above isn't an exhaustive list of guidelines, neither are any of the
above actually "enforced" (although you might find one or two
people politely suggesting you consider abiding by them). Generally speaking
the <em>rules</em> on the Harbour lists are those that apply to good email
composition in general.
</p>
<hr>
<h2><a id="40"></a>4.6. Are the lists archived anywhere?<a id="MailArchives"></a></h2>
<p>You can access the developer's list at <a href="https://web.archive.org/web/20110716032711/www.matrixlist.com/pipermail/harbour/">www.matrixlist.com/pipermail/harbour/</a>,
the user's list at <a href="https://web.archive.org/web/20060307012652/www.matrixlist.com/pipermail/harbourusers/">www.matrixlist.com/pipermail/harbourusers/</a>
and the discussion list at <a href="https://web.archive.org/web/20060307012639/www.matrixlist.com/pipermail/harbourtalk/">www.matrixlist.com/pipermail/harbourtalk/</a>.
</p>
<hr>
<h2><a id="41"></a>4.7. Are there any newsgroups for Harbour?</h2>
<p>No, there are no newsgroups specific to Harbour. However, Harbour is a
Clipper compatible compiler which means that Harbour is an on-topic subject
for the Usenet group <a href="news:comp.lang.clipper">comp.lang.clipper</a>.
</p>
<hr>
<h3><a id="42"></a>5. Installing Harbour</h2>
<hr>
<h2><a id="43"></a>5.1. Where can I get pre-built binaries?</h2>
<p>While Harbour is still in development the preferred method of getting a
Harbour binary is to download the source and build it yourself because this
aids the development effort.
</p>
<p>However, the
<a href="#WhoDevelopers">Harbour developers</a> also
appreciate the efforts of people who don't want to develop Harbour itself
but do want to test it and report bugs. To this end some people maintain
Harbour binaries that are ready to be installed.
</p>
<p>Please keep in mind that the following may not be the very latest cut of
Harbour (Harbour changes by the hour while in this early phase of
development) and that some platforms might be better supported than others.
If you see that a platform isn't supported or is out of date please consider
stepping in and making available binaries for that platform.
</p>
<p>
<ul>
<li>The
<a href="https://sourceforge.net/projects/harbour-project/files/">downloads page</a>
on the <a href="/">Harbour project's website</a>
contains a number of binary builds of the latest stable snapshot.
</li>
<li><a href="mailto:[email protected]">David G. Holm</a> is
maintaining a repository of binary builds of stable (and sometimes, in
parallel, unstable) releases at <a href="https://web.archive.org/web/20050909125654/harbour.netfang.net/">harbour.netfang.net/</a>.
</li>
</ul>
</p>
<p>If you cannot find binaries for your environment via the above links then
this means that someone isn't contributing for that environment, perhaps
you'd care to step in and fill that gap?
</p>
<hr>
<h3><a id="44"></a>6. General Harbour questions</h2>
<hr>
<h2><a id="45"></a>6.1. When will Harbour be finished?<a id="WhenFinished"></a></h2>
<p>"When it's finished".</p>
<p>Seriously, Harbour will be finished when it is finished. If the pace of
Harbour development isn't fast enough for you you can always contribute
something to the project to make it go faster. Such contributions could be
code, documentation, faster machines for the
<a href="#WhoDevelopers">key developers</a> (but one suspects a free supply of pizza would be
more welcome) or even an offer to employ one or more of the key developers
to work on Harbour full time.
</p>
<hr>
<h2><a id="46"></a>6.2. Are applications <attribute> than CA-Clipper applications?</h2>
<p>Or, to put it another way, will your application be bigger, smaller, slower,
faster, sexier, etc.... Generally, at least at this stage in the life of
Harbour, any given body of code that can be compiled with Harbour and with
<a href="#Trademarks">CA-Clipper</a>, on the same machine and with the
same environment (it wouldn't be much of a comparison otherwise would it?)
will run slower and will probably be "bigger" when compiled with
Harbour.
</p>
<p>The same is probably true when comparing Harbour compiled code with other
Clipper compatible compilers.
</p>
<p>The reasons for this are many and varied and, as is pointed out in many
places in this document, Harbour is still early in its life and continuing
development and Clipper compatibility are of greatest importance. The issue
of "performance" will be addressed when it is most appropriate
to do so, and when people are available to look into it.
</p>
<p>As always, if the performance of Harbour is an issue for you now and you
want to see Harbour perform as per your expectations then
<a href="#WhenFinished">contributions</a> speak louder than benchmark results.
</p>
<hr>
<h2><a id="47"></a>6.3. What advantages does Harbour have over other Clipper compilers?</h2>
<p>The main advantage Harbour has over
<a href="#ClipperCompilers">other Clipper compilers</a> is that it is
<a href="#FreeSoftware">free software</a>. Harbour also attempts to remove some of the limits imposed by
the base implementation but the extent of this will depend on your chosen
platform.
</p>
<p>The
<a href="#WhoDevelopers">Harbour developers</a> make no claim that
Harbour is better or worse than
<a href="#ClipperCompilers">any other implementation of the language</a>, however, at the same time, each individual
developer can probably sing the praises regarding the area of Harbour they
have worked on.
</p>
<p>Most importantly, try Harbour for yourself, decide for yourself why it has
advantages for <strong>you</strong>.
</p>
<hr>
<h2><a id="48"></a>6.4. What advantages do other Clipper compilers have over Harbour?</h2>
<p>Currently the advantages
<a href="#ClipperCompilers">other Clipper compilers</a> have over Harbour are:
<ul>
<li>They are available and working (for various values of "working").</li>
<li>They are supported.</li>
<li>They are documented.</li>
<li>They, to some degree, give you
<a href="#Warranty">someone to blame</a>.
</li>
</ul>
</p>
<p>As time passes most of the above advantages will be eroded. Note that the
documentation process is well under way and that support is simply a
<a href="news:comp.lang.clipper">comp.lang.clipper</a> post away.
The only advantage that won't be eroded is the last one in the list.