Design #1124
Move examples directory into doc -- or just change makefile?
Description
After having improved the installation procedure for CoCoALib, it seems better/cleaner/more natural to put the directory examples/
inside the directory doc/
.
Is this really a good idea? If so, let's do it!
Related issues
History
#1 Updated by John Abbott over 6 years ago
- Category set to Documentation
- Status changed from New to In Progress
- Target version set to CoCoALib-0.99600
- % Done changed from 0 to 10
Anna was concerned that "hiding" examples/
inside doc/
might make it less visible; but apart from that doubt she liked the suggestion.
Maybe we can move it immediately after the next (imminent) release, and then see if it works OK for us...
#2 Updated by John Abbott over 6 years ago
- Related to Support #574: Tidy CoCoA root directory added
#3 Updated by John Abbott over 6 years ago
- Related to Support #1058: CoCoALib version in Documentation and Examples added
#4 Updated by John Abbott over 6 years ago
If we do move examples/
into doc/
then presumably this should also be the case for an installed version of CoCoALib;
currently examples/
is copied "beside" doc/
#5 Updated by Anna Maria Bigatti about 6 years ago
- Related to Support #1148: Release CoCoA-5.2.4 added
#6 Updated by Anna Maria Bigatti about 6 years ago
- Related to deleted (Support #1148: Release CoCoA-5.2.4)
#7 Updated by John Abbott almost 6 years ago
- % Done changed from 10 to 20
Anna now likes the idea.
It may also help solve nicely a silly but annoying problem with the compilation of CopyInfo.C
(currently the Makefile
in examples/
needs libcocoa.a
to exist before compiling anything,
incl. CopyInfo
)
#8 Updated by John Abbott almost 6 years ago
I have added a dirty hack to doc/Makefile
so that CopyInfo
can be compiled even when libcocoa.a
does not exist
This hack works only if the attempt to compile CopyInfo
comes from doc/Makefile
; it does not work if
the attempt to compile comes from examples/Makefile
.
This dirty hack must be removed when we move examples/
into doc/
#9 Updated by John Abbott almost 6 years ago
- Target version changed from CoCoALib-0.99600 to CoCoALib-0.99650 November 2019
#10 Updated by John Abbott almost 6 years ago
One problem is that the Makefile
in the examples/
directory states explicitly that all executables depend on CoCoALib
; this is very handy when developing prototypes etc.
The problem is that CopyInfo
should not depend on CoCoALib
. So an (ugly?) workaround would be to change the name of the source file to CopyInfo.cpp
; this would not then trigger the automatic dependency. Any name will work provided it does not end in .C
#11 Updated by Anna Maria Bigatti over 5 years ago
- Subject changed from Move examples directory into doc to Move examples directory into doc -- or just change makefile?
- Status changed from In Progress to Feedback
- Assignee set to Anna Maria Bigatti
- Target version changed from CoCoALib-0.99650 November 2019 to CoCoALib-0.99600
- % Done changed from 20 to 90
- Estimated time set to 5.01 h
After a long design discussion, John Abbott and I decided to try, as a first step, to separate from the examples makefile the makefile for making the documentation.
I've implemented and tested it:
It is in Makefile-indexhtml, and is called by Makefile.
In practice it is used in the same way (make index.html, ...) but CopyInfo.C no longer has the dependency on libcocoa.a, which is necessary for all example C files.
It makes the index of any ex-***.C file in the example directory, and this might actually turn out useful.
#12 Updated by John Abbott over 5 years ago
- Status changed from Feedback to Closed
- % Done changed from 90 to 100
SUMMARY: we leave examples/
directory where it is (as it is more visible to the user), and have created a special Makefile
for compiling CopyInfo
The "new Makefile" solution is better than the previous arrangement. Time will tell if it is good enough.
Closing.