Horde3D
http://horde3d.org/forums/

Improper paths and documentation
http://horde3d.org/forums/viewtopic.php?f=3&t=1008		 Page 1 of 1
Author:  Svenstaro [ 14.11.2009, 00:58 ]
Post subject:  Improper paths and documentation
Hi,

I just saw this project and was delighted to find a rather small yet complete 3D engine. Needless to say I wanted to try it out but hit a few roadblocks here and there. I want to suggest to fix these to make it easier for inexperienced users to set this up.

No standard project documentation files
In the SVN checkout, I wasn't able to spot any of the usual files like README, COMPILE, TODO, CHANGES, AUTHORS, BUGS, HCAKING, etc, they just weren't here. For people who know how to colaborate or how to compile with CMake and find out dependencies by trial and error this might be alright but other people will be confused by this. Create some initial file documentation for that. If you don't know what should be in there, look up just about any open-source project and have a look at their root documentation.

API-incompatible tutorials
The sole tutorial which seems to be copied from the wiki to the main site (not a good idea, it makes stuff go out of sync) is old and API-incompatible with the SVN API. Please update those. Also, the tutorials are incomplete in so far as they don't give you the ability to download the complete tutorial files (along with headers and main.cpp) and thus you are unable to directly test whether everything is working.
EDIT: I'd also appreciate *more* tutorials.

Improper CMake installation directories or improper #include paths
Either CMake installs includes to wrong directores or your #include paths on the samples are wrong. For example, glfw.h does not reside in /usr/include/glfw.h but in /usr/include/GL/glfw.h on any standard Linux system since it is part of OpenGL. Also, your CMake configuration installs itself to /usr/include/horde3d/Horde3D.h which seems wrong because you #include <Horde3D.h>, not #include <horde3d/Horde3D.h>.
Additionally, why does your CMake configuration not install any samples? I suggest an optional CMake flag for installing samples to /opt/Horde3D/.

Don't take any offense in this, just trying to improve the project :). If you have any questions about my points feel free to ask me about anything.
Author:  Volker [ 14.11.2009, 18:16 ]
Post subject:  Re: Improper paths and documentation
I ported some of the documentation to the wiki not from the wiki, so forum members can update the documentation as well, since our resources are quite limited, so we hope the community can help here and there. If you think documentation can be improved, feel free to update the corresponding wiki pages or create new ones.

You are right, that the installation pathes for the CMake configuration is not well configured. In fact, I didn't care about it at all, since I'm not a fan of installing an SDK somewhere on the system. I prefer if I can compile and run it where I've downloaded it, instead of spreading the files, all over my Linux installation, but that's something I hate about Linux anyway. Every application you install places it's dependencies and files all over your disk, and if you want to remove it, you can only bet, that the package managment cleanly removes all things correctly.... well, maybe I'm only not that familiar with Linux :-)

The documentation on the web sites should correspond to the official release packages on SourceForge, if you check out the SVN trunk, chances are high that the documentation is not updated yet.
Author:  Svenstaro [ 15.11.2009, 10:44 ]
Post subject:  Re: Improper paths and documentation
Let's not have an OS argument here, it's silly. The Linux way of installing stuff is actually quite simple.
Your lib is called MyName
  • Put libs to /usr/lib/libMyName.so
  • Put includes to /usr/include/MyName.h if single header, otherwise /usr/include/MyName/*.h
  • Put docs to /usr/share/doc/MyName
  • Put any other stuff to /usr/share/MyName

I propose you try to make it easier for both, users and developers on all platforms you target. Currently, the whole package is rather Windows-centric and looks like it should only be used by developers (you think of it as an SDK, for example). While this makes sense seeing where you are coming from, it would be easy to improve the state of the project here. I'd actually be willing to help you guys out here if you let me.

In my opinion, you should set your project up like a proper open-source project complete with COPYING, README, etc, project files for more IDEs, official IRC channel and proper include paths.

Apart from that, where can I get most up to date documentation? When will be the next point release?
Author:  DarkAngel [ 15.11.2009, 11:47 ]
Post subject:  Re: Improper paths and documentation
Svenstaro wrote:
In my opinion, you should set your project up like a proper open-source project complete with COPYING, README, etc, project files for more IDEs, official IRC channel and proper include paths.
By "proper open-source project" you mean doing it the GNU way? Isn't that just as bad as doing it "the windows way"? Luckily CMake should let us be Windowsy on Windows and Unixy on Unix :wink:

I do think having the prominent "readme" group of files in the root directory, explaining how to go about building it, what the licensing terms are, etc, would be a good idea though.

Discussion about IRC is here: viewtopic.php?f=1&t=395
Quote:
I'd actually be willing to help you guys out here if you let me.
Improving the CMake files to be more unix'y on *nix systems has been discussed before, but I don't think much happened with it -- it could probably still use some work: viewtopic.php?f=1&t=378
Also a Mac thread: viewtopic.php?f=2&t=973

I can't find the thread where it was decided that horde would use CMake, but from what I remember, CMake was chosen because it's possible to get comfortable results for all operating systems. This requires volunteers on all OS's to volunteer to improve the CMake files though, so I'm sure some more effort on the *nix-specific parts would be appreciated. I think there are more Windows/Mac users than *nix users, which is why the Windows-specific parts of the CMake files are the most mature.
Quote:
Apart from that, where can I get most up to date documentation? When will be the next point release?
The manual is online: http://horde3d.org/docs/manual.html
Or in the SVN repo: https://horde3d.svn.sourceforge.net/svn ... rde3D/Docs

Supplemental material is on the wiki: http://horde3d.org/wiki/

Some community work was being tracked on this page, but it hasn't been updated for a while: http://horde3d.org/wiki/index.php5?titl ... ty_Roadmap

The last talk I saw regarding the next release was in the middle of this thread:
viewtopic.php?f=2&t=929&hilit=beta5

More up-to-date releases (than the downloadable packages) can be retrieved from the trunk directly :wink:
Author:  Svenstaro [ 15.11.2009, 13:04 ]
Post subject:  Re: Improper paths and documentation
So it appears there is no up-to-date documentation for trunk and I can't see any doxygen files for generating it myself :/. Whatever happened to the IRC channel then? It still doesn't appear to be official.

Quote:
By "proper open-source project" you mean doing it the GNU way? Isn't that just as bad as doing it "the windows way"?

While the Windows way is specific to Windows, the GNU way is supposed to satisfy all operating systems, even those that are not POSIX conform. Unless you can suggest a better project setup standard, I think we should go with the GNU way.

Waiting for a dev response on my suggestions... :)
Author:  Funto [ 15.11.2009, 15:06 ]
Post subject:  Re: Improper paths and documentation
Just giving my opinion : keep going with CMake, autotools are unintuitive, force people to install MSYS on Windows and create a bunch of useless files everywhere.

As a Linux user, I think some of the most important things lacking in terms of installation/compilation are support for a UNIX build system for the game engine in the community SVN, and up-to-date packages for the most important distributions.

Quote:
Put libs to /usr/lib/libMyName.so
Put includes to /usr/include/MyName.h if single header, otherwise /usr/include/MyName/*.h
Put docs to /usr/share/doc/MyName
Put any other stuff to /usr/share/MyName


Default behavior should not install all this stuff to /usr but to /usr/local. Installing to /usr should be possible via the command-line and should be done only when installing a package for the Linux distribution.
Author:  swiftcoder [ 15.11.2009, 15:10 ]
Post subject:  Re: Improper paths and documentation
Svenstaro wrote:
Waiting for a dev response on my suggestions... :)
It is an open-source project. Everyone in this thread so far is a developer.
Quote:
So it appears there is no up-to-date documentation for trunk and I can't see any doxygen files for generating it myself :/.
Doxygen hasn't been merged into the CMake build files, but it shouldn't be too hard to create a doxygen config file and add a CMake target - feel free to give it a shot.
Quote:
Whatever happened to the IRC channel then? It still doesn't appear to be official.
The official position on this subject is that discussions to do with development should occur on the forum. It leaves a 'paper-trail' for any decisions made, and makes the discussions a bit more coherent to outsiders. That said, a few of us do hang out in the IRC channel most of the time.
Quote:
Quote:
By "proper open-source project" you mean doing it the GNU way? Isn't that just as bad as doing it "the windows way"?
While the Windows way is specific to Windows, the GNU way is supposed to satisfy all operating systems, even those that are not POSIX conform. Unless you can suggest a better project setup standard, I think we should go with the GNU way.
Speaking from experience, the GNU way is very GNU-centric, and doesn't port particularly easily even to other (non-GNU) unix variants. If one has to pick a 'way' (and I see no reason why one should), the Google way or the Apple way both seem considerably more favourable…
Author:  Svenstaro [ 15.11.2009, 15:18 ]
Post subject:  Re: Improper paths and documentation
I think we're getting mixed up. I'm not suggesting changing to autotools by any means, I hate autotools.

Funto, I'm a packager so I put stuff to /usr/, of course. I hate locally installing packages without my system knowing about them.
swiftcoder, I just looked it up on Google's V8 and they are also using GNU autotools style info file setup: http://code.google.com/p/v8/source/browse#svn/trunk

I'm aware that technically everybody here is developer but effectively, only few people here possess the permissions to make anything "official".
Author:  swiftcoder [ 15.11.2009, 15:44 ]
Post subject:  Re: Improper paths and documentation
Svenstaro wrote:
Funto, I'm a packager so I put stuff to /usr/, of course. I hate locally installing packages without my system knowing about them.
I never really saw a need to install a self-contained dev SDK, but tastes differ. I am generally against the idea, because there is no cross-platform analogy to linux's concept of installing SDKs and related documentation/samples.
Quote:
I just looked it up on Google's V8 and they are also using GNU autotools style info file setup: http://code.google.com/p/v8/source/browse#svn/trunk
Sure, and I don't see any reason not to put a license.txt in the root directory, with possibly an abbreviated readme as well. The problem is, every information file we add, someone has to maintain, or they end up very quickly out of date.

And at this point, it is worth pointing out that Horde has exactly 1 (one) dependency, CMake, so that info file is unnecessary. In addition, building requires only a single CMake command, but after that it requires build-system specific interaction, which varies from platform to platform, making comprehensive compile instructions a little tricky. Authors file would just be duplicating information on the website, as would a changelog or bugs file.
Author:  Svenstaro [ 15.11.2009, 16:03 ]
Post subject:  Re: Improper paths and documentation
Putting the information into standard files has the advantage that I will always know where exactly to find this information. Sites differ from project to project and thus I can not retrieve a list of authors or changes from one standard location. It gets even harder when there are multiple releases: stable, testing, unstable and source checkout that might have different authors, changes or even licenses. Are you going to put that information on a site?

At any rate, I was just stating my thoughts. I don't have any permission to commit any changes so what you guys will decide will ultimately prevail. My three points would be: Establish consistency between site and project files as well as documentation, improve cross-platform support, create more documentation.
Author:  Volker [ 15.11.2009, 16:23 ]
Post subject:  Re: Improper paths and documentation
As mentioned by some of you, we should stick with CMake, since my experience is that it works on Mac, Linux and Windows and I had tested that already with XCode / GNU make / MSVC on those platforms.

I personally don't think that it makes to much sense to copy the libs and headers to your /usr/whatever directories for most of the Horde3D users.
First reason is that it seems (even in this thread), that it is not clear where those files should be copied to (q.e.d. to my first post :-) )
The second is that if you integrate Horde in your project, I guess that most developers are using a versioning system which probably also integrates the Horde source code, since it might be necessary to change something there for a specific project too. In this case it makes more sense to me, to hold the source code at one place instead of installing it in the system.

The only reason I see for installing it into the system is that if an official application needs Horde3D and does not ship with it and you only want to install the dependencies, it might be more "native" to do it with a "make install". That's also the reason why I think adding a proper INSTALL section to the CMake configuration would not be a bad idea, and if someone can help adding it, it would be much appreciated.
(e.g. by posting a patch here in the forum).

Concerning the README, AUTHORS, etc. files I very much agree with swiftcoders comment. A readme file is in the SVN and in the official packages, and compiling instructions can be found in the wiki. Maybe we should add a link to it to the readme file.

The reason why the GameEngine is not integrated into the build system is that it was mostly developed under MSVC while I was working for the university. Currently I don't use it in any of my projects anymore and as far as I know the people at the lab still stick with MSVC. So until some nix/Mac user want's to use it, I guess no one wants to spend time to make it usable under nix/mac systems. The GameEngine in the CB was integrated to show what can be done based on Horde, but it is not officially supported by me or marciano. That's also the reason why it is not integrated into the SF svn repository. I will always try to answer questions concerning the GameEngine or try to find a solution if something is not working that was ment to be running out of the box. But I currently don't have the time to add new things/features.

BTW, the editor is based on qmake and should be compileable under linux (although support for the new shader/material system is still missing). But I got some segfaults with the latest revision under linux. Running it under windows was no problem. If someone has some time to reproduce/debug that it would be great.
Author:  Volker [ 15.11.2009, 16:28 ]
Post subject:  Re: Improper paths and documentation
Svenstaro wrote:
My three points would be: Establish consistency between site and project files as well as documentation, improve cross-platform support, create more documentation.

If you could be little bit more precise what exactly you find inconsistent or not enough documented or where exactly you have problems to use Horde on your platform, we certainly can find a way to improve it.
Quote:
Either CMake installs includes to wrong directores or your #include paths on the samples are wrong. For example, glfw.h does not reside in /usr/include/glfw.h but in /usr/include/GL/glfw.h on any standard Linux system since it is part of OpenGL. Also, your CMake configuration installs itself to /usr/include/horde3d/Horde3D.h which seems wrong because you #include <Horde3D.h>, not #include <horde3d/Horde3D.h>.

GLFW should be included from the source that ships with Horde. Normally we test the CMake files under Ubuntu as mentioned in the wiki before we release the official packages. If something is not working as described there, we should fix it.
Author:  kornerr [ 09.02.2010, 12:53 ]
Post subject:  Re: Improper paths and documentation
I think I know what Svenstaro means.
Buy using AUTHORS, CHANGELOG, etc you stick with almost all standard *nix projects which also almost all happen to be cross-platform. So GNU way is cross-platform.
The standard files could be fetched by, say, automated script to create a distribution package, to create documentation for web, build instructions. He just talks about automation. The only reason wiki gets outdated is because it's duplication. Each duplication is evil.
One solution to this is to have contrib/ dir which could have sdl/, qt/ dirs which implement examples of qt + horde, sdl + horde. That code can be automatically posted to wiki at each revision update. And it can be automatically tested each release (create some testAll main script, for both Linux and Windows).
So, his points are these: exclude duplication, introduce automation. Then we get up-to-date docs, api, easy to fetch info about horde, etc.
Also, thank you Svenstaro, you opened my eyes to these files. I will try to automate my environment at my work with that in mind.
Author:  Volker [ 09.02.2010, 13:30 ]
Post subject:  Re: Improper paths and documentation
Automation of updates and tests is certainly something we should more focus on.
Page 1 of 1 All times are UTC + 1 hour
Powered by phpBB® Forum Software © phpBB Group
https://www.phpbb.com/