Project

General

Profile

Design #1124

Move examples directory into doc -- or just change makefile?

Added by John Abbott over 6 years ago. Updated over 5 years ago.

Status:
Closed
Priority:
Normal
Category:
Documentation
Target version:
Start date:
16 Nov 2017
Due date:
% Done:

100%

Estimated time:
5.01 h
Spent time:

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

Related to CoCoALib - Support #574: Tidy CoCoA root directoryClosed2014-06-19

Related to CoCoALib - Support #1058: CoCoALib version in Documentation and ExamplesClosed2017-05-04

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

#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

#6 Updated by Anna Maria Bigatti about 6 years ago

#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.

Also available in: Atom PDF