[ANN] dev-utils v1.0

G

Gavin Sinclair

Hi all,

It's with great relief that I finally release dev-utils 1.0. Never
have I put so much effort into a project with so little code. (That's
because the effort was wasted on documentation...)

It's gem-only at the moment. Within a few days, I'll release 1.0.1
complete with tarball, and see its way clear to the RPA. For now,
though, it's 4am and I'm off to bed.

BTW, it depends on newly-released extensions-0.5. I'll be in touch,
Mauricio :)

Cheers,
Gavin


About dev-utils:

With dev-utils/debug you can:

* Escape to an IRB session from a running program.

breakpoint
breakpoint 'Person#name' # Identify it when it happens.
breakpoint { @name } # Default return value.

* Access a no-config logfile for debugging.

debug 'Database connection established' # Look in ./debug.log

* Trace expressions in that logfile.

trace 'x + y'
trace 'Process.pid'
trace 'names', :pp # Pretty-print.
trace 'page_structure', :yaml # YAML representation.

Home page: http://dev-utils.rubyforge.org
Project page: http://rubyforge.org/projects/dev-utils
Download: http://rubyforge.org/frs/?group_id=270
API Documentation: http://dev-utils.rubyforge.org/api
 
A

Aredridel

Totally looking forward to the tarball and RPA releases. .. I still
can't get RubyGems to work.
 
C

Chad Fowler

Totally looking forward to the tarball and RPA releases. .. I still
can't get RubyGems to work.

What issue are you having? I saw that you were joining the rubygems
developers list. Can you post your problem there? I apologize if
it's been mentioned and overlooked. It's been a hectic several weeks
leading up to RubyConf.

Chad
 
M

Mauricio Fernández

Hi all,

It's with great relief that I finally release dev-utils 1.0. Never
have I put so much effort into a project with so little code. (That's
because the effort was wasted on documentation...)

It's gem-only at the moment. Within a few days, I'll release 1.0.1
complete with tarball, and see its way clear to the RPA. For now,
though, it's 4am and I'm off to bed.

I've been waiting until the weekend was over to see if you released
1.0.1 :)

I know several people were waiting for this to enter RPA so I
tried to repackage the gem. I have to thank you for following
(maybe unknowingly) most of the good practices described in
http://rpa-base.rubyforge.org/wiki/wiki.cgi?GoodPractices ; this made
repackaging your gem easier.

Plz find below a minor patch I had to apply to make the documentation
generator work (I have removed the RPA specific part).


batsman@tux-chan:~/src/rpa/ports$ rpa update --no-proxy
Getting port info from http://rpa-base.rubyforge.org/ports/ports.info.
100% [========================================] 88230 bytes

Ports added since the last 'rpa update'
dev-utils 1.0-1 Debugging utilities: breakpoints, debugging, and tracing.

(the following was run with an early version of the 0.3 branch after install)
batsman@tux-chan:~/src/rpa/rpa-base$ rpa show dev-utils
Port: dev-utils
Classification: Top.Library.Development
Available-Version: 1.0-1
Installed-Version: 1.0-1
RPA-Version: 0.0
Updated: Mon, 11 Oct 2004 00:43:25 +0200
Source-URL: http://rpa-base.rubyforge.org/ports/dev-utils_1.0-1.rps
Build-Requires: cstemplate, redcloth
Requires: extensions
Description:
Debugging utilities: breakpoints, debugging, and tracing.
 
C

Chad Fowler

I know several people were waiting for this to enter RPA so I
tried to repackage the gem. I have to thank you for following
(maybe unknowingly) most of the good practices described in
http://rpa-base.rubyforge.org/wiki/wiki.cgi?GoodPractices ; this made
repackaging your gem easier.

So, Mauricio, this is a repackage to RPA of a gem? Any
rubygems-related issues in the process? Did the fact that there was
already some metadata present help you at all?

I'm still interested in the possibility to script rubygems -> rpa-base
conversion and would like to hear your stories.

Chad
 
M

Mauricio Fernández

So, Mauricio, this is a repackage to RPA of a gem? Any
rubygems-related issues in the process?

As I said above, the process was relatively easy because Gavin followed
many of the good practices documented in rpa-base's wiki. This doesn't
mean that the conversion was automatic (or could be automated for the
matter), though. There were dependencies on RubyGems I had to remove,
and the documentation was generated with a custom script so I had to
adapt it; I also had to discover the "build dependencies" (I found them
in the documentation later) and fix some issues...
Did the fact that there was already some metadata present help you at all?

Honestly, not really. The only piece of metadata I reused was
'Debugging utilities: breakpoints, debugging, and tracing.'. Since that
is not an acceptable description in RPA, I had to look for a better one
elsewhere. As far as I'm concerned, the rest of the metadata (with
the exception of the author, dep, email and homepage) consists only of
implementation details of RubyGems and is hence useless to me:
s.description = s.summary
s.files = FileList['[A-Z]*', '{etc,examples,lib,test}/**/*'].to_a
s.require_path = 'lib'
s.autorequire = nil
s.has_rdoc = true
s.extra_rdoc_files = FileList['*.txt'].to_a
s.rdoc_options << '--main' << 'README.txt' << '--title' << 'dev-utils API Documentation'
s.test_files = []
do not bring me that much useful information.

Moreover, it lacks information about the "build dependencies" (required
to generate the documentation).
I'm still interested in the possibility to script rubygems -> rpa-base
conversion and would like to hear your stories.

The conversion of dev-utils was relatively easy, and yet impossible to
automate. I had to read and understand the Rakefile and adapt
documentation generation. Plus remove the dependency on RubyGems and
correct the associated problems ("shadow requires").
I would *really* love to see you come up with a script able to
do what I did manually, but it would have to read and understand
Rakefiles/documentation/etc so it's probably as hard a problem as you
can get.

I'd like to remind you once again that the conversion involves much
more than a simple change in the package format. In general, systems
with a package manager have some associated policies, which determine
the quality of packages in that context --- besides being just "legal"
as far as the format it concerned. In the case of RubyGems, you have
decided to keep it "policy free", which means that you just cannot target
systems with a policy automatically, at least with the current metadata[1]:
such a script would really have to be "intelligent" (say, comparable
to a FreeBSD developer :) to create policy-compliant packages/ports for
other systems.

[1] if you managed to find a way to define the whole "gem build" process
in the gemspec and hence REMOVE altogether the reliance on external
processes, plus mark all files "semantically" (e.g.: example, test,
documentation, configuration, shared data) AND standardize the build
scripts, it could become possible. Note that the latter is essentially at
least as hard as (and actually more difficult than) post-install scripts;
so far, the only working design that could solve the latter completely is
http://rubyforge.org/pipermail/rubygems-developers/2004-October/001081.html
as far as I know.
 
C

Chad Fowler

As I said above, the process was relatively easy because Gavin followed
many of the good practices documented in rpa-base's wiki.

So by that you mean to use obvious directory names, don't do anything
fancy with test suites, and use rdoc for documentation. Is that it?
Pretty much exactly what it says in the gems chapter of the Pickaxe,
it turns out ;)
This doesn't
mean that the conversion was automatic (or could be automated for the
matter), though. There were dependencies on RubyGems I had to remove,
and the documentation was generated with a custom script so I had to
adapt it; I also had to discover the "build dependencies" (I found them
in the documentation later) and fix some issues...
Moreover, it lacks information about the "build dependencies" (required
to generate the documentation).

What do you mean by "build dependencies" in this context?
I'd like to remind you once again that the conversion involves much
more than a simple change in the package format. In general, systems
with a package manager have some associated policies, which determine
the quality of packages in that context --- besides being just "legal"
as far as the format it concerned.

Obviously. But if you could run a script and have everything setup
for an inspection/sign-off, I imagine it would make things easier. I
guess it's really not worth the effort.

By "remove rubygems dependencies" are you saying you had to remove
"require 'rubygems'" and a few "require_gem" statements or was it
something somehow more involved?

Chad
 
B

Brian Palmer

I love it, the breakpoints feature is going to get heavy use right here,
let me tell you. As a quick note, you might put a mention in your docs
for us poor Windows Rubyists that ^Z is in fact the EOF character in
Windows/DOS, not ^D. Cheers.

- Brian Palmer
 
G

Gavin Sinclair

I've been waiting until the weekend was over to see if you released
1.0.1 :)

And I was waiting for your comments (not necessarily your actions)
before doing so :) Well, that's my excuse and I'm sticking to it.
I know several people were waiting for this to enter RPA so I
tried to repackage the gem. I have to thank you for following
(maybe unknowingly) most of the good practices described in
http://rpa-base.rubyforge.org/wiki/wiki.cgi?GoodPractices ; this made
repackaging your gem easier.

I try my best :)
Plz find below a minor patch I had to apply to make the documentation
generator work (I have removed the RPA specific part).

This makes me curious. Reading through the RPA transcript, it's not
clear that the non-RDoc documentation is actually built. There's
copious details of everything else, yet no mention of that. Yet the
dev-utils RPA, as opposed to the dev-utils gem, specifies a dependency
on cstemplate and redcloth. Are they actually used?

This is interesting as a matter of packaging policy. I'd like to
assist users in building local documentation, but in this era of
universal Internet access, people (I think) tend to just hit the
website, which has exactly the same information.

Cheers,
Gavin

BTW, I can't install dev-utils with rpa-base 0.2.2. I know earlier
versions had an issue with Cygwin, but thought that was resolved.
Besides, I don't see any error messages during the install:

$ rpa install dev-utils
Installing ports
Getting port dev-utils from http://rpa-base.rubyforge.org/ports/dev-utils_1.0-1.rps.
100% [========================================] 30720 bytes
Building dev-utils (1.0-1).
Installing pre-dependencies cstemplate redcloth.
Reusing cached package /usr/local/lib/ruby/rpa0.0/packages/cstemplate_0.5.1-3_i686-pc-cygwin.rpa.
Starting lightweight (metadata only) transaction for cstemplate
Checking for file conflicts in cstemplate.
Starting transaction for cstemplate
Package /usr/local/lib/ruby/rpa0.0/packages/cstemplate_0.5.1-3_i686-pc-cygwin.rpa unpacked.
Finished transaction for cstemplate
Finished lightweight (metadata only) transaction for cstemplate
Reusing cached package /usr/local/lib/ruby/rpa0.0/packages/redcloth_2.0.11-2_i686-pc-cygwin.rpa.
Starting lightweight (metadata only) transaction for redcloth
Checking for file conflicts in redcloth.
Starting transaction for redcloth
Package /usr/local/lib/ruby/rpa0.0/packages/redcloth_2.0.11-2_i686-pc-cygwin.rpa unpacked.
Finished transaction for redcloth
Finished lightweight (metadata only) transaction for redcloth
Building dependencies extensions.
/usr/local/lib/ruby/site_ruby/1.8/rpa/helper.rb:513: warning: Insecure world writable dir /d/Softwar
e/MikTex/Main/miktex, mode 040777
Generating RI data files.
Generating RDoc HTML documentation.

$ rpa list
Installed ports:
4 stopped transaction(s):
cstemplate 0.5.1-3 metadata
cstemplate 0.5.1-3 cleanup
redcloth 2.0.11-2 metadata
redcloth 2.0.11-2 cleanup

Restoring state...
Restoring state...
Restoring state...
Restoring state...
rpa-base 0.2.2-1 A port/package manager for the Ruby Production Archive (RPA)
 
A

Alexander Kellett

versions had an issue with Cygwin, but thought that was resolved.
Besides, I don't see any error messages during the install: [snip]
$ rpa install dev-utils [snip]
Generating RDoc HTML documentation.

umm thats totally freaky

looks like it just stops during the rdoc creation
maybe ruby is segfaulting or something under cygwin?
maybe --debug would provide some more information?

Alex
 
G

Gavin Sinclair

versions had an issue with Cygwin, but thought that was resolved.
Besides, I don't see any error messages during the install: [snip]
$ rpa install dev-utils [snip]
Generating RDoc HTML documentation.
umm thats totally freaky
looks like it just stops during the rdoc creation
maybe ruby is segfaulting or something under cygwin?
maybe --debug would provide some more information?

Here you go:

Generating RI data files.
Generating RDoc HTML documentation.
Running task RPA::Helper::Installman.
Running task RPA::Helper::Installexamples.
Running task RPA::Helper::Compress.
Running task RPA::Helper::Installtests.
Running task RPA::Helper::Installmodules.
Running task RPA::Helper::Installexecutables.
Running task RPA::Helper::Installextensions.
Running task RPA::Helper::Moduledeps.
Running task RPA::Helper::Fixperms.
Running task RPA::Helper::Fixshebangs.
Running task RPA::Helper::Task.
/usr/local/lib/ruby/site_ruby/1.8/i386-cygwin/celsoft.com/template.so: dlopen: Win32 error 5 - /usr
local/lib/ruby/site_ruby/1.8/i386-cygwin/celsoft.com/template.so (LoadError)
from /usr/local/lib/ruby/site_ruby/1.8/rubygems/loadpath_manager.rb:5:in `require'
from ./etc/doc/generate.rb:14
from /usr/local/lib/ruby/site_ruby/1.8/rubygems/loadpath_manager.rb:5:in `require__'
from /usr/local/lib/ruby/site_ruby/1.8/rubygems/loadpath_manager.rb:5:in `require'
from /f/TEMP/RPA_1097498956.951070/dev-utils/install.rb:28
from /f/TEMP/RPA_1097498956.951070/dev-utils/install.rb:24:in `instance_eval'
from /usr/local/lib/ruby/site_ruby/1.8/rpa/helper.rb:707:in `instance_eval'
from /usr/local/lib/ruby/site_ruby/1.8/rpa/helper.rb:707:in `run'
... 12 levels...
from /usr/local/lib/ruby/site_ruby/1.8/rpa/frontend.rb:27:in `initialize'
from /usr/local/lib/ruby/site_ruby/1.8/rpa/rpafrontend.rb:34:in `initialize'
from /usr/local/bin/rpa:12:in `new'
from /usr/local/bin/rpa:12

The fact that it borked on celsoft.com/template (the cstemplate
package) indicates that it's trying to build the extra documentation
(not that it says so explicitly).

The cstemplate gem has a problem: it comes packaged with a binary,
even though it's meant to be a source gem. I'm working on that. It
seems the cstemplate RPA has a problem of some kind as well, at least
on Cygwin.

Gavin
 
M

Mauricio Fernández

This makes me curious. Reading through the RPA transcript, it's not
clear that the non-RDoc documentation is actually built. There's
copious details of everything else, yet no mention of that. Yet the
dev-utils RPA, as opposed to the dev-utils gem, specifies a dependency
on cstemplate and redcloth. Are they actually used?

They are :) The generation of the other docs isn't reported because...
well, I just didn't add anything to report it in the associated task *g*.
Note that redcloth and cstemplate are "build dependencies", i.e. only
needed to build the package. rpa-base knows that and can remove them
afterwards since they are no longer needed.
This is interesting as a matter of packaging policy. I'd like to
assist users in building local documentation, but in this era of
universal Internet access, people (I think) tend to just hit the
website, which has exactly the same information.

rpa-base can be used to install from local repositories (will have to
document this though :) when the user has got no internet connection...
BTW, I can't install dev-utils with rpa-base 0.2.2.

Thank you for reporting the problem.
I had failed to declare the "build dependency" on 'extensions'.

I believe the issue is solved in the newly uploaded dev-utils 1.0-2. I
also solved the 'Win32 error 5', so the following should work:

rpa clean
rpa update
rpa install dev-utils

Please report any other problem you might experience; it is hard to
get all details right, even when you've packaged quite some libs/apps
before...
 
M

Mauricio Fernández

So by that you mean to use obvious directory names, don't do anything
fancy with test suites, and use rdoc for documentation. Is that it?

You're missing some details specified in

http://rpa-base.rubyforge.org/wiki/wiki.cgi?GoodPractices
Pretty much exactly what it says in the gems chapter of the Pickaxe,
it turns out ;)

As I've said before, I would have liked that chapter to include more
general information about good practices wrt. packaging, which would
benefit all systems. The <1 page "package layout" section in that
chapter isn't quite enough IMHO. It is also a pity that you couldn't
document the "Rational Versioning Policy" which was presented by
Jim Weirich in his RubyConf talk and first described by Eivind Eklund
in April
(http://rubyforge.org/pipermail/rubygems-developers/2004-April/000294.html).

It would be nice it you could list the expectations/assumptions of
RubyGems (the software) since that would help shape up RubyGems' policy
and foster fruitful interaction between the two projects.
What do you mean by "build dependencies" in this context?

Other libraries/applications that are only needed to build the package:
they are not required to *use* it and can be safely removed afterwards
(and rpa-base's package GC does remove them).

RubyGems doesn't have an equivalent concept because the 'gem build'
process must be performed by the original developers themselves, as
the rest of the packaging.
Obviously. But if you could run a script and have everything setup
for an inspection/sign-off, I imagine it would make things easier. I
guess it's really not worth the effort.

This would work much better if the "standard" directory structure (the
one that setup.rb has used for years) was promoted more actively and
more gems respected it. I understand it can be difficult for RubyGems to
adopt any policy (since you always depend on 3rd parties) but it would
become much easier if the gem build process encouraged it actively,
just like original developers are encouraged to use "require 'rubygems'"
because otherwise their software won't work once gemified ;-)
By "remove rubygems dependencies" are you saying you had to remove
"require 'rubygems'" and a few "require_gem" statements or was it
something somehow more involved?

Something a bit less obvious (the "shadowed requires" problem).
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Similar Threads


Members online

Forum statistics

Threads
473,744
Messages
2,569,483
Members
44,901
Latest member
Noble71S45

Latest Threads

Top