[CEDET-devel] EDE documentation

[Alastair R. <ala...@gi...>]

David/Eric,

I’ve just committed (finally!) the additional documentation required for compdb projects. For now I’ve just converted the existing documentation into texinfo, and inserted it in a single section underneath “Miscellaneous commands”. Please review and let me know any comments.

In doing this, I’ve had a few thoughts about the current documentation. More specifically, I’m not sure that the current document structure is ideal, and I’d like to explore some alternatives.

The way I think about EDE project types is that there are two main categories. Firstly there is the “generic” project which is the most useful when you are the creator of the project. In this case, the Project.ede file is the canonical source of build information, and it generates the relevant Makefiles needed.

In the other category we have project types which derive their content from existing build files. My own compdb project is an obvious example, but I think others such a Linux, Arduino, perhaps Automake, also fall into this category. The key distinction here is that there is no canonical Project.ede file, instead the existing build files are the source of project information.

To my mind, which EDE project type you use for a given source base depends on whether you are the owner or not. If you are, you are free to choose the generic project type - and hence commit all of your Project.ede files and make them part of the build process. If you are not the project owner - or you choose not to have an EDE dependency - you may wish to use one of the non-generic (let’s call them “non-owning”) project types.

Hence in the documentation I think there should be a clear distinction between these two types of projects. Some of us - who aren’t willing/able to commit to Project.ede files for project maintenance - aren’t going to use the generic project type, and should be steered towards the use of ‘non-owning’ project types. The current EDE documentation - specifically the quickstart section - pretty much assumes that you’re going to use the generic project type.

Instead, I’d like the documentation to accomodate the following use case: as a new user of EDE, I want to be able to set it up to work with an *existing* codebase, build system, etc. Ideally the documentation should introduce the different types of project early in the document, and how to choose between them.

As always, I may be thinking about this completely the wrong way - in which case please feel free to enlighten me!

Cheers,