I am attempting to formalize a directory structure for my
ruby projects. Below is a first attempt. I am interested
in what others think. It would be nice if we could
generate a common directory structure for projects as this
would facilitate install packages, docs and such.
I am attempting to formalize a directory structure for my
ruby projects. Below is a first attempt. I am interested
in what others think. It would be nice if we could
generate a common directory structure for projects as this
would facilitate install packages, docs and such.
It actually annoys me that rdoc uses the ‘doc’ directory by default.
I happen to have doc directories already and they contain source
documentation. How about ‘rdoc’ for rdoc directories, or ‘browse’ for
processed documentation in general.
‘examples’ are usually listed as ‘samples’, although I don’t know why.
I am attempting to formalize a directory structure for my
ruby projects. Below is a first attempt. I am interested
in what others think. It would be nice if we could
generate a common directory structure for projects as this
would facilitate install packages, docs and such.
I’m a little unhappy with having ‘docs’ and ‘doc’, since it looks like
two things that are kinda-sort-of the same. I would prefer to have all
documentation under one directory, with subdirs under it.
That’s very close to what I use, but I’ve never used a src/ dir for a
ruby project. What’s that for?
I’ve seen the src directory for things like .y files.
It is source that does not necessarily belong to an
extension and is never pushed out to an install lib.
Also, I would add RELEASE-NOTES or ChangeLog or CHANGES.
How about putting the release-notes in the readme (this being
different than the change log).
···
On Tuesday, 27 May 2003 at 3:23:31 +0900, Joel VanderWerf wrote:
–
Jim Freeze
Pure drivel tends to drive ordinary drivel off the TV screen.
It actually annoys me that rdoc uses the ‘doc’ directory by default.
I happen to have doc directories already and they contain source
documentation. How about ‘rdoc’ for rdoc directories, or ‘browse’ for
processed documentation in general.
Are your doc directories browsable or do they just
contain documentation source?
I think this is the stickiest issue. If we use
doc # doc source
rdoc # rdoc - browsable
Where to you put your browsable source?
man/ ??
‘examples’ are usually listed as ‘samples’, although I don’t know why.
I’ve seen both. There is also the issue of plurality.
Let’s take a quick vote. Make your choice:
sample
samples
example
examples
···
On Tuesday, 27 May 2003 at 4:01:25 +0900, MikkelFJ wrote:
–
Jim Freeze
Common sense is instinct, and enough of it is genius.
– Josh Billings
That’s very close to what I use, but I’ve never used a src/ dir for a
ruby project. What’s that for?
I’ve seen the src directory for things like .y files.
It’s widely used for C source code. There isn’t really a convention for
mixed language directories,
but you might find ./ruby instead of ./src, or just source code in the
current directory (but that tends to backfire as the project grows).
One could have ./src normally and ./src/ruby, ./src/ocaml, … for mixed
language.
It is source that does not necessarily belong to an
extension and is never pushed out to an install lib.
I have adopted the directory name ‘exo’ for external language bindings to a
project. Sane persons would normally use ‘bindings’. I then have ./exo/ruby
…/exo/com, ./exo/ocaml, … . In this case where ruby is an extension to
another project, I might then adopt the suggested directory structure within
ruby: ./exo/ruby/src, ./exo/ruby/doc, … .
Also, I would add RELEASE-NOTES or ChangeLog or CHANGES.
There’s also INSTALL
readme.txt is friendly for windows users because you can than click directly
and open the text in notepad and sometimes it gets highlighted by file
browsers as an important file.
I happen to have doc directories already and they contain source
documentation. How about ‘rdoc’ for rdoc directories, or ‘browse’ for
processed documentation in general.
Are your doc directories browsable or do they just
contain documentation source?
They contain document source, but are human readable. They are intended to
be readable without a special tool. docbook is a bit controversial - I think
it would be better off in in a ‘docbook’ directory because it isn’t really
that readable, or doc/docbook, doc/latex, …
I have my own format I’m working on called step. It’s mostly very readable,
but can be categorized in line with xml-doc, so I guess it would be either
…/doc or ./doc/step (in analogy with ./src or ./src/ruby).
I think this is the stickiest issue. If we use
doc # doc source
rdoc # rdoc - browsable
Where to you put your browsable source?
man/ ??
perhaps it should be generalized - it’s not really important that the
browsable html is generated by rdoc, so I guess my rdoc proposal isnt’ that
clever after all.
…/browse/html
…/browse/xml (this is browsable xml, as in xhtml, not doc-book).
…/browse/man (or ./browse/text)
or replace ./browse with ./view/… or ./help/… or ./online/… or
…/read/…
I guess there is no established standard.
‘./processed-doc/…’ may be more informative.
‘examples’ are usually listed as ‘samples’, although I don’t know why.
I’ve seen both. There is also the issue of plurality.
Let’s take a quick vote. Make your choice:
sample
samples
example
examples
I prefer examples but tend to find samples more widely used, so I won’t
argue either way.
RDoc won’t write into an existing doc/ directory if it thinks that it
didn’t produce it in the first place.
Thats good to know. What will it do, complain?
No, it reformats the disk partition containing the directory, so that
the directory no longer exists. It then continues, safe in the knowledge
that it won’t overwrite any existing content.
Directory doc already exists, but it looks like it
isn’t an RDoc directory. Because RDoc doesn’t want to risk
destroying any of your existing files, you’ll need to
specify a different output directory name (using the
–op option).
Thanks everyone for your input so far.
Below is the latest directory structure.
It looks complete. If anyone has strong objections
or sees glaring ommissions, please let me know.
CHANGELOG
INSTALL # optional
LICENSE
Manifest
README # if multi lang, README.en, README.ja, etc
setup.rb
bin/
# ruby executables
# other executables
doc/ # If multi lang, then use doc.en, doc.ja, etc
/man
/rdoc
/rd
examples/
ext/
/ext_name?
extconf.rb
… other source
lib/
# .rb files that go into RUBY_LIB
# may want to use parallel directory structure below
# site_ruby//
src/
/<other_lang_name>
test/
# test suites
I removed the /packages directory because I don’t see a need
for it now. However, the racc library from the raa has divided
its source into four packages and essentially pushes the
directories I have listed above down two levels under
/packages/package_name.
···
–
Jim Freeze
What good is a ticket to the good life, if you can’t find the
entrance?
Thanks everyone for your input so far.
Below is the latest directory structure.
It looks complete. If anyone has strong objections
or sees glaring ommissions, please let me know.
CHANGELOG
INSTALL # optional
LICENSE
Manifest
README # if multi lang, README.en, README.ja, etc
setup.rb
bin/
# ruby executables
# other executables
On Tue, 27 May 2003 09:57:30 +0900, Jim Freeze wrote:
CHANGELOG
INSTALL # optional
LICENSE
Manifest
README # if multi lang, README.en, README.ja, etc
setup.rb
bin/
# ruby executables
# other executables
doc/ # If multi lang, then use doc.en, doc.ja, etc
/man
/rdoc
/rd
examples/
ext/
/ext_name?
extconf.rb
… other source
lib/
# .rb files that go into RUBY_LIB
# may want to use parallel directory structure below
# site_ruby//
src/
/<other_lang_name>
test/
# test suites
Questions for a small ruby application. The application will not result
in a ruby library at all.
Hope your “Ruby Project Directory Structure” is also valid for a simple
application.
a) There are a couple of .rb files which hold the ruby classes for the
application. Where do these files go to? bin/ or lib/
b) A ruby file is called start1.rb and start2.rb which starts the
applications (each creates an instance object of the main application,
sort of client-server). Does this file go into bin/ or does it go into
examples as it showes how to start the application or is it a
replacement for the setup.rb file?
Also there are a couple of data (input files) for the application.
Where do those data (input files) go?
Kind regards
Sacha
···
On Tue, 2003-05-27 at 07:57, Jim Freeze wrote:
Thanks everyone for your input so far.
Below is the latest directory structure.
It looks complete. If anyone has strong objections
or sees glaring ommissions, please let me know.
CHANGELOG
INSTALL # optional
LICENSE
Manifest
README # if multi lang, README.en, README.ja, etc
setup.rb
bin/
# ruby executables
# other executables
doc/ # If multi lang, then use doc.en, doc.ja, etc
/man
/rdoc
/rd
examples/
ext/
/ext_name?
extconf.rb
… other source
lib/
# .rb files that go into RUBY_LIB
# may want to use parallel directory structure below
# site_ruby//
src/
/<other_lang_name>
test/
# test suites
I removed the /packages directory because I don’t see a need
for it now. However, the racc library from the raa has divided
its source into four packages and essentially pushes the
directories I have listed above down two levels under
/packages/package_name.
–
Sacha Schlegel
4 Warwick Str, 6102 St. James, Perth, Australia
sacha@schlegel.li www.schlegel.li
public key: www.schlegel.li/sacha.gpg
Minor points if this is going to be a “complete” recommendation:
I sometimes/often use a TODO file at top-level.
LICENSE is sometimes called COPYING. I think LICENSE is better though.
Regards,
Robert
···
On Tue, 27 May 2003, Jim Freeze wrote:
CHANGELOG
INSTALL # optional
LICENSE
Manifest
README # if multi lang, README.en, README.ja, etc
setup.rb
bin/
# ruby executables
# other executables
doc/ # If multi lang, then use doc.en, doc.ja, etc
/man
/rdoc
/rd
examples/
ext/
/ext_name?
extconf.rb
… other source
lib/
# .rb files that go into RUBY_LIB
# may want to use parallel directory structure below
# site_ruby//
src/
/<other_lang_name>
test/
# test suites
I suppose that the contents under contrib vary wildly
depending upon the library and what is contributed. I think
the only contrib I’ve seen is for irb and rdoc.
···
On Tuesday, 27 May 2003 at 11:22:40 +0900, David A. Black wrote:
Hi –
On Tue, 27 May 2003, Jim Freeze wrote:
Thanks everyone for your input so far.
Below is the latest directory structure.
It looks complete. If anyone has strong objections
or sees glaring ommissions, please let me know.
CHANGELOG
INSTALL # optional
LICENSE
Manifest
README # if multi lang, README.en, README.ja, etc
setup.rb
bin/
# ruby executables
# other executables
contrib/
–
Jim Freeze
Under a government which imprisons any unjustly, the true place for a
just man is also in prison.
– Henry David Thoreau
What does “recipy” mean? It’s not an English word.
I don’t think there’s any problem with ‘src’, ‘doc’, ‘bin’, ‘ext’. If you’re
a newbie, you’re going to have to learn what those things stand for anyway.
I think Jim is documenting current best practice, not trying to invent
something which is different and incompatible with current practice.
Regards,
Brian.
···
On Tue, May 27, 2003 at 03:04:10PM +0900, Simon Strandgaard wrote:
abbreviated names is NOT userfriendly to newbies.
I prefer long names (at least in the top-level dir):
