Document usage scenarios

[fredemmott]

Outside of Facebook, by default:

• the typechecker is automatically ran on page requests
• a typechecker error is fatal

This means that this code can not be ran if there are any references to undefined classes in the tree, including classes that are generated by codegen, so, it seems that:

• codegen files should be committed to the repo
• codegen files need to be created before any references to them are added

By comparison, https://github.com/hhvm/user-documentation approach (which has a much less clean implementation than this) is:

• manually written .hhi files are committed to the repo, and do not use hack-specific features
• PHP code is generated as a build step

[gauravkdeo]

The codegen is supposed to be used for generating files which are version controlled. It actually allows to make changes on codegen, without worrying about breaking the code dynamically or worrying about push safety.

[alejandromarcu]

codegen files should be committed to the repo
Can't you just commit them after running codegen?

codegen files need to be created before any references to them are added
Isn't that up to the user of codegen to do that?

I'm not sure what you need, can you clarify?

[fredemmott]

"Don't commit build output" is a common philosophy; I think it would be useful to document that:

• this project is incompatible with that
• why the approach this project takes can be the right decision sometimes

[alejandromarcu]

I think the only limitation that Hack Codegen is currently imposing is that you can't use "<?php", but that's easy to fix if you want to us this library.

You could accomplish it using Hack Codegen doing as follow:
Each build step class would need a boolean parameter, e.g. $is_skeleton. When this is true, then codegen should generate the files that would be commited, such as https://github.com/hhvm/user-documentation/blob/master/src/codegen-hhi/PHPDotNetAPIIndex.hhi
When the paramater is false, it would do the whole code generation. In that case, in codegen_file, you can use setIsSignedFile(false) to avoid signing it.

Then, in build.php you could add a parameter to generate the skeleton.

Would something like that be good?

[alejandromarcu]

Oh, I thought that the written file was overwriting the existing one, but doesn't seem to be the case. Anyway, I think that what I described above should work as well, except that you need 2 paths.
You could also just write the codegen to write the php file ignoring the hhi file, but you risk inconsistencies.

[fredemmott]

It generating '<?hh' means that outside of Facebook (where the auto-typechecking behavior is disabled) means that if you do not commit the build results, you can not generate them unless they are unused, as the typechecker will say there are undefined classes, which will raise a fatal the moment that any hack code is executed, including the hack code in this project during the build process.

Yep, being able to choose between '<?hh', '<?hh // decl' (hhi), and '<?php' would make this more flexible.

[alejandromarcu]

Cool, I'll take care of allowing for '<?hh', '<?hh // decl' (hhi), and '<?php'.