Re^13: 5.10 imminent?

[BrowserUk]

You're right anonymonk, thanks. And, when I re-read the instructions again from the beginning, right there, just 1 paragraph above is:

This will ask you a bunch of questions, for most of them you want to use the defaults. About the only ones you will need to hand edit will be the location of the build directory and the email addresses you want to CC your smoke reports to. For perl-current I use D:\smoke\perl-current once this is done you will find that you have three files in your run directory, one is a build config file, the other is a smoke config file and the last is a batchfile. Once all of this is done in order to run a smoke you simply execute this batch file.

All the info I require is right there. Except, you don't read this type of instructions as a linear flow from top to bottom. You read a bit and do a bit. You read a bit and do a bit. And in between, you do other things. And when you return, you scan down skipping the bits you've down and look for the next bit to do. So, terminology introduced in one paragraph doesn't survive whatever many other things you have done during the interim.

But here the crux. There are 3 files: smokecurrent.cmd, smokecurrent_config, w32current.cfg. Why introduce 3 "terms": "one is a build config file, the other is a smoke config file and the last is a batchfile" to refer to these files? Why not just use their shorter and unambiguous actual name? Eg.

Oh one thing you might want to do is edit the build config file and make sure that something like:

Oh one thing you might want to do is edit w32current.cfg and make sure that something like:

-DINST_DRV=D: -DINST_TOP=$(INST_DRV)\smoke\inst\current

And this is how good documentation comes into being. Everyone knows that I'm far from being a technical author, but I was lucky enough to work with a few, including one extremely good one for several years, and this is the process. He would act as a complete novice, and ask every "stupid" question possible. Believe me, it's not easy to do if you have any knowledge of the subject at all. It requires you to force yourself to not make any assumptions, and to ignore whatever you do know. It is laborious and tedious. But oh so worth the effort whenit is done correctly.

Can I do that? We'll see :)

[demerphq]

Why not just use their shorter and unambiguous actual name?

Well, two reasons, the most important being I was in a rush (relatively speaking -- i was procrastinating doing something with a deadline at the time) and couldn't be bothered to look up the /actual/ names. (Sorry about that.) But the other reason is that you can actually control the names of the files, by using the -p option with configsmoke. Try doing perldoc lib\configsmoke from the run directory for more options.

Regarding your friend the technical author, i know what you mean. Its hard to document/explain something that you know really well without falling into these types of traps. Review by third parties is always useful.

Anyway, do remember that not a lot of people have set up smoke, and even less on win32, and that the package is a work in progress. Contributing back improved documentation would be very useful. :-)

[BrowserUk]

(Sorry about that.)

Again, unnecessary. My words were more of a defense of my acting "stupid", than any critism of your timely intervention in this thread. I have to wonder about the need for the ability to change the names, but there is undoubtedly some system somewhere where the default names happens to coincide with the system command for formatting the hard drive or some such :)

Anyway, do remember that not a lot of people have set up smoke, and even less on win32,

Understood. I started the process at 18:22:14, and I'm trying to take notes as I go. I didn't expect it to take this long or require this amount of manual intervention.

The problem is that the test suite makes several calls to system functions that cause my firewall to intervene with popups requesting authorisation. Pre-authorising perl.exe and miniperl.exe doesn't help much because it also detects changes in authorised executables and as the smoketest keeps rebuilding them--it still keeps prompting. Still doesn't allow unattended operation.

This is the same problem I encountered when I considered setting up smoke testing on win32 some some 4 years ago.

Alternatives:

1. Disconnect from the internet and disable the firewall.

   The tests will still fail.

   Many years ago, crazyinsomniac or podmaster suggested (in a post I can't now find), that he had tried to float the idea of removing/disabling these tests that cause internet access with p5p, but it fell on deaf ears.

2. Leave the internet connection active and disable the firewall.

   Not an option. My firewall logs record some 280+ attempted incoming scans of various ports in the 7 hours this has been running.

3. Other...?

[demerphq]

I have to wonder about the need for the ability to change the names

Well, I have two sets in my smoke directory, one for "maint" (Aka Perl 5.8.x) and one for "current" (Aka Perl 5.9.x). You didnt run perldoc yet did you? :-)

The problem is that the test suite makes several calls to system functions that cause my firewall to intervene with popups requesting authorisation.

Personally I'd just tell your firewall to ignore anything in the smoke tree. Alternatively just let the tests fail i guess. If anybody wants to know why they will ask.