Separating between Development and Release

[mottosso]

Hi @ocornut,

I had a quick thought about how to potentially improve how imgui is developed and how it is used.

The end result is meant to be..

1. Simpler to develop
2. Simpler to use

### Motivation

At the extreme, there are two major ways of distributing any library; as a single file (such as stb), or as multiple files (like most other projects). Each of which has a few pros and cons.

Single, header-only library

Mode	Mood
Using
Developing

Multiple files

Mode	Mood
Using
Developing

And at the moment, I feel there is some tension between which of these routes to take.

### Implementation

The idea is to combine the best of both by introducing a release step.

1. Maintain a project of multiple files
2. Distribute a single file

The single file would be automatically merged at the time of producing a GitHub release such that (1) the end-user can simply drop-in the file into any project, almost like they can today but easier, and (2) developers of the project can split source code up into however many files and folders is necessary to make better sense out of things.

The advanced user would then be able to use the project as-is and cut down on things not required for a particular tasks.

### Example

Development files are divided.

Development	Description
logic.cpp	Logical operations
drawing.cpp	Drawing operations
text.cpp	Text rendering
light.cpp	Light functions
...	...

A single release file is built.

Release	Description
imgui.h	Merged end-user file for distribution

logic.cpp

void someLogic()
{
  std::cout << "Thinking.." << std::endl;
}

drawing.cpp

void someDrawing()
{
  std::cout << "Drawing.." << std::endl;
}

imgui.h

void someDrawing()
{
  std::cout << "Drawing.." << std::endl;
}

void someLogic()
{
  std::cout << "Thinking.." << std::endl;
}

[unpacklo]

Unless I'm misunderstanding something, I am highly against this idea.

It's very important to me that what I see in the repo and what I see in the
release are the same thing so it's easy to go directly into the code and
point out problems. No translation required.

This would make the code base be two different ones even though they are
"identical". More mental load that's not necessary, in my opinion.

On Thu, Apr 21, 2016 at 12:31 AM, Marcus Ottosson notifications@github.com
wrote:

Hi @ocornut https://github.com/ocornut,

I had a quick thought about how to potentially improve how imgui is
developed and how it is used.

The end result is meant to be..

1. Simpler to develop
2. Simpler to use

Motivation

At the extreme, there are two major ways of distributing any library; as a
single file (such as stb), or as multiple files (like most other projects).
Each of which has a few pros and cons.

Single, header-only library
Mode Mood
Using
https://cloud.githubusercontent.com/assets/2152766/14698555/f09c3ec2-0787-11e6-8688-0452cbde0aa3.png
Developing
https://cloud.githubusercontent.com/assets/2152766/14698495/6346742a-0787-11e6-9374-a44ecc4faa56.png

Multiple files
Mode Mood
Using
https://cloud.githubusercontent.com/assets/2152766/14698495/6346742a-0787-11e6-9374-a44ecc4faa56.png
Developing
https://cloud.githubusercontent.com/assets/2152766/14698555/f09c3ec2-0787-11e6-8688-0452cbde0aa3.png

And at the moment, I feel there is some tension between which of these
routes to take.

Implementation

The idea is to combine the best of both by introducing a release step.

1. Maintain a project of multiple files
2. Distribute a single file

The single file would be automatically merged at the time of producing a
GitHub release such that (1) the end-user can simply drop-in the file into
any project, almost like they can today but easier, and (2) developers of
the project can split source code up into however many files and folders is
necessary to make better sense out of things.

The advanced user would then be able to use the project as-is and cut down
on things not required for a particular tasks.

Example

Development files are divided.
Development Description
logic.cpp Logical operations
drawing.cpp Drawing operations
text.cpp Text rendering
light.cpp Light functions
... ...

A single release file is built.
Release Description
imgui.h Merged end-user file for distribution

logic.cpp

void someLogic()
{
std::cout << "Thinking.." << std::endl;
}

drawing.cpp

void someDrawing()
{
std::cout << "Drawing.." << std::endl;
}

imgui.h

void someDrawing()
{
std::cout << "Drawing.." << std::endl;
}
void someLogic()
{
std::cout << "Thinking.." << std::endl;
}

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
#599

[dumganhar]

Agree with @Roflraging
+1 for not to separate code base to two different ones.

[mottosso]

It's very important to me that what I see in the repo and what I see in the release are the same thing so it's easy to go directly into the code and point out problems.

Thanks for chiming in. The goal would to reduce the amount of problems you would need to point out in the first place.

It's possible that the larger and more intertwined the existing file gets, the more difficult it might get to maintain and understand. Breaking it up into smaller chunks might make it easier to spot unintended coupling and also communicate the library more easily to newcomers.

@Roflraging and @dumganhar is it possible that you are not the target audience for such a feature? The end result would be a release header-only file for (a majority of) newcomers and hobbyists, and a full project of multiple source and headers files for advanced users. If you fall into the advanced category, you might even benefit from the change.

[ocornut]

I also have to agree with roflraging etc. above and think it creates more problems that it solves it. The library is in active development and I wouldn't want users to stumble on code in an amalgamated file that was different from the development one. It also create an extra barrier between being a user and being a developer, and hopefully there shouldn't be such barrier. It would create extra confusion on the repository itself. There's no release step and I'd prefer users just getting master which is the best way as a community to catch bugs early.

A)
Single-file doesn't make a difference with "using", it makes a difference with "getting started the first time" which is a one time thing. That difference exist but it is minor and easily amortized. The reason people like stb library isn't because they are one file, it is because THEY WORK, they compile, they link, you don't get any of the usual library/dependency hell and that partly because of the way they are written. ImGui intentionally doesn't come with build files to signify that the user can drag/include the files in their project.

If it is a matter of adding files to a project, you can use this imgui_in_one_file.h

#include "imgui.h"
#ifdef IMGUI_IMPLEMENTATION
#include "imgui.cpp"
#include "imgui_draw.cpp"
#include "imgui_demo.cpp"
#endif

Done!

B)
My intuition is that from your angle you are mainly desirous of splitting the library into more files than currently so it would be more approachable? (if that's the case, I think it would be better to just state your own desire bluntly before rationalizing it into something for everyone!). That's totally understandable but I don't feel it'll bring a lot of value.

You give the example of logic.cpp drawing.cpp imgui.h and this is exactly what imgui.cpp imgui_draw.h imgui.h are! And you'd be surprised at how not trivial it would be to split imgui.cpp into natural components. When I split the library from 2 to 5 files I did this research and it was surprinsingly unobvious how to split imgui.cpp further in a reasonable way (also see #219 ).

It would bring more value to improve comments, improve the general structure documentation, keep massaging the code, and maybe add a developer guide on the wiki to describe some the architecture.

I think there is a point where we have to accept that a given library is written in a certain style which make some developers more or less comfortable with working on it. The performance-oriented coding style of imgui is very specific and splitting into more file wouldn't make that easier?

[mottosso]

Thanks @ocornut, I appreciate that you took the time to consider this. I am of course much too new to the project to know what's best, but wanted to explore the option.

And you'd be surprised at how not trivial it would be to split imgui.cpp into natural components. When I split the library from 2 to 5 files I did this research and it was surprinsingly unobvious how to split imgui.cpp further in a reasonable way.

I think you've hit the nail on the head here. See, this doesn't surprise me. It sounds like a side effect of developing with too many globals. I'm not sure it will ever get easier unless deliberate steps are taken to untangle the code.

In any case, it looks like a majority is in favour of keeping things as they are and you all may well be right. I look forward to learning more about the library and to experience things first hand!

[ocornut]

It's cool - proposals and ideas always welcome!

There's 1 global variable and it is a current context pointer. Development isn't really hard or bottlenecked because of the code base style. The reason I say I can't easily split the code much more is just the nature of the code, functions are rather flats, there aren't a lot of sensible "categories" that are big enough to warrant their own file. Some people would create extra files for 300 lines of code but I wouldn't do that (e.g. "all tree functions in imgui_tree.cpp", if you add up the line count that sort of category ends up being very small), so I think it would actually harm development to split, in addition to making inlining trickier.

That said, I am not against adding extra files if there are natural candidates but I don't see any right now (apart perhaps from all the text input stuff, which I aim to cleanup / refactor at some point after I can implement UTF-8 supporting changes in stb_textedit.h).

It's not easy partly because there's many users using the library so API can't be casually broken all the time and some things needs to be engineering accordingly to limit breakage. In addition, subtle things may break easily which I why I would really love to implement the test suite drafted at #435 this would definitively make it much more welcoming for new developers ihmo.