Non-zero exit code on failure

0 votes
asked Jan 22, 2014 in Bug by anonymous
I'm using plantuml in command line, and I've create a Makefile for "compiling" all iuml files.

The issue is that the "compilation" continues even when there is a bug in one iuml file.

5 Answers

0 votes
answered Jan 22, 2014 by plantuml (188,280 points)

In command line, PlantUML returns "1" as exit code when diagrams contains errors. So it looks like a bug.

Could you give us :

  • the version of PlantUML you are using,
  • the command line your are using,
  • Add -verbose in the command line and send us back the trace you've got ?

You can send all this by mail (plantuml@gmail.com) if you wish.

Regards,

0 votes
answered Jan 22, 2014 by anonymous
$ cat Temp.iuml 
@startuml
 
class {
}
 
@enduml
$ java -jar /scripts/plantuml.jar `find . -name '*.iuml' | xargs` -teps -charset UTF-8 -graphvizdot `which dot` -v
(0.000 - 81 Mo) 79 Mo - PlantUML Version 7986
(0.002 - 81 Mo) 79 Mo - GraphicsEnvironment.isHeadless() false
(0.007 - 81 Mo) 79 Mo - Setting current dir: .
(0.007 - 81 Mo) 79 Mo - Setting current dir: /Users/user/plantuml-bug-exitcode/.
(0.008 - 81 Mo) 79 Mo - Using charset UTF-8
(0.010 - 81 Mo) 79 Mo - Setting current dir: /Users/user/plantuml-bug-exitcode/.
(0.013 - 81 Mo) 79 Mo - Setting current dir: /Users/user/plantuml-bug-exitcode/.
(0.013 - 81 Mo) 79 Mo - Reading file: ./Temp.iuml
(0.435 - 81 Mo) 70 Mo - Creating file: /Users/kenji/plantuml-bug-exitcode/./Temp.eps
(1.209 - 81 Mo) 76 Mo - Number of image(s): 1
user@host:~/plantuml-bug-exitcode\$ echo $?
0
 
Temp.eps contains a nice red "Syntax Error?" :-)
 
Edit : same issue with Version 7991
0 votes
answered Jan 22, 2014 by rmric (2,790 points)

In order to get an exit code upon syntax failure, you can pass the option -failonerror.

Be aware in such a case, plantuml will stop processing on the first failing file. Any good file behind won't be processed.

 

commented Jan 22, 2014 by plantuml (188,280 points)
Thanks for the answer : as you can read, we are changing this slightly. Hope that you don't mind.
commented Jan 23, 2014 by rmric (2,790 points)
No problem, the new behavior is much preferable.
0 votes
answered Jan 22, 2014 by plantuml (188,280 points)

Ok, thanks for your input, we have figured out what's going on.

You should add -failonerror flag on your command line.

Actually, this flag has two different effects:
A) It change the status code to 1 (so that's what you are expecting)
B) It stops processing as soon as a syntax error occurs in some diagram

Imagine that you have a large amount of files to process (let's says 1000)
In some case you may want to process all your files, even if 3 of them have errors.
In other case, you may want to fail as soon as some syntax error occurs (because you do not want to wait for all files to be processed).
That's why the -failonerror flag is used for.

We understand that this is somehow confusing, and we'd like to improve this.

So here is what we are proposing for next versions:

1) Remove this confusing/misnamed -failonerror flag
2) Always return a status code of 1 when there are some syntax error (this is what you expecting) in command line & ant task.
3) Create a -failfast flag that would stop processing as soon as a syntax error occurs in some diagram.

(This would mean that the default behaviour would still be to process all diagrams, even when you do have syntax error)

To be complete, note that there is also a -checkonly flag that check diagrams syntax, without generating images (meaning it runs very fast), and that returns status code to 1 if needed.

So you may want to use this in your script:

#Quickly check that syntax are ok
java -jar /scripts/plantuml.jar `find . -name '*.iuml' | xargs` -checkonly
if ($? -q 0 );then
  #Syntax is ok, so let's really generates the diagrams now
  java -jar /scripts/plantuml.jar `find . -name '*.iuml' | xargs` -teps -charset UTF-8 -graphvizdot `which dot` -v
fi


What do you thing about it ?
 

0 votes
answered Jan 22, 2014 by anonymous
Your proposition seems good to me : make (or ant) will detect the failure, but I prefer keeping "failfast" mode by default : verbose indicates me which file failed, so I could get into it, if generating continues, I will have to search into output to find the "failing files".

To let the user be able to ignore failures and continue, maybe a -ignore-failures flag would be better.

My example is that I manage plantuml + latex document inside a simple Makefile (latex has dependency on uml, so no uml, no latex document generated :-) ).

 

Thanks fo the checkonly flag (i'll integrate a new dependency on it in my Makefile).
commented Jan 22, 2014 by plantuml (188,280 points)
In the following beta:
https://dl.dropboxusercontent.com/u/13064071/plantuml.jar

We have:
- None-zero exit code on failure
- No more -failonerror flag
- Add a -failfast flag to fail quicly when there are syntax error
- Fixed the -checkonly issue (to print file where the error occurs)

We understant that you'd prefer -failfast by default, but we have to think about it before changing that.

Few tests have been done, so feedback welcome.
commented Jan 23, 2014 by anonymous
Tested and it look nice (I added a checkonly phase in my Makefile that runs for 1.286s), and then the generation phase that runs for 4.664s).
Does the failfast make a first run like the one I do by runing a first command with checkonly (in which case I will use it instead of adding a checkonly phase) ?
commented Jan 23, 2014 by plantuml (188,280 points)
No, the -failfast does not make a first run to check syntax only.

So we have added yet another flag called "-failfast2" flag.
The beta is available here:
https://dl.dropboxusercontent.com/u/13064071/plantuml.jar

This flags does the same thing that -failfast, except that it adds a first pass to quickly check syntax.
It means that, in case of error, it even run/fail faster than the -failfast option.
But if there are no syntax error, then this first run would have been useless, and in this case -failfast2 runs slower than -failfast

It really depends on your need.

We have also upgraded the -duration flag that print information about generation duration and specifically about this optional first pass.
So you can make tests & measures to decide which flag is best for you.
Note that you should not need -verbose option, since error are printed even in unverbose mode.
commented Jan 23, 2014 by anonymous
Nice idea, i'll use this -fastfail2 flag :

Check Duration = 1.311 seconds
Duration = 5.262 seconds

On another project similar to the current one (only class and sequence diagrams) :

Check Duration = 1.287 seconds
Duration = 6.096 seconds

By using -fastfail, if it fails after 4 seconds of generation, it would have been detected in the first "big" second by -fastfail2

My real need was to stop on first error (and have the filename that contains the syntax error).

Thank you for quick support
commented Jan 24, 2014 by rmric (2,790 points)
I tested the second beta, and I'm having a question.

Is the (new) default behavior be to process all the files, and the exit code to be 0 no matter what there's a syntax error ?

IOW, how to execute plantuml such that all the files are processed, regardless of syntax error, and have the exit code to be different than 0 in case of syntax error?

Rem: in the beta, plantuml -h is still showing the -failonerror option. Do I have the right file?
PlantUML version 7992beta (Tue Jan 21 20:16:10 CET 2014)

Rem: on a picky note, -failearly sounds better than -failfast :-)
commented Jan 24, 2014 by plantuml (188,280 points)
> Is the (new) default behavior be to process all the files, and the exit
> code to be 0 no matter what there's a syntax error ?
The (new) default behavior is to process all the files (even if there are errors), the exit code is 0 or 1, depending on syntax error.
There is (now) no way of having always 0 as exit code, when there are syntax error.

> how to execute plantuml such that all the files are processed,
> regardless of syntax error, and have the exit code to be different
> than 0 in case of syntax error?
This is exactly the new default behavior

-h option has been fixed in new beta.

Rem: Yes, -failfast sounds odd, but we like it :-)
commented Apr 1, 2014 by rmric (2,790 points)
In v7995, I'm still not getting an exit code of 1 upon syntax error (without any option):

$ java -jar plantuml.jar broken_diagram.pu
Error in file: broken_diagram.pu
$ echo $?
0

Is it the expected behavior?

Rem: I do get the expected exit code 1 with -checkonly, -failfast, and -failfast2.

BTW, could it be possible to have in the "Error in file: " message the line number of the syntax error ? This would come in handy for eclipse (or any other IDE) ErrorParser.

PS: there is a small typo in the -help message: the end of 'allow' is missing :
-overwrite        To all<ow> to overwrite read only files

Regards
commented Apr 2, 2014 by plantuml (188,280 points)
Hello,

Thanks for the report: we (should) have solved the 0 code status bug, in the following beta:
https://dl.dropboxusercontent.com/u/13064071/plantuml.jar

It would be nice if you could test -failfast2 -failfast and -checkonly flags,
because the code is not very pretty there, and we hope we did not break anything :-)

We have also fixed the typo in -help message, and will have a look on adding the line number in the error message.

Regards,
commented Apr 2, 2014 by rmric (2,790 points)
Hi! thanks for this beta.

It is working fine, with or without -failfast2 -failfast and -checkonly flags, against a single file (either good or broken) or two files (the first one broken and the second good). We've got a winner!

Regards
commented Apr 3, 2014 by plantuml (188,280 points)
Ok, great, and thanks for your tests.
We have added the line number in the last beta, so you can use it if you wish.

Regards,
...