[llvm] [Remarks] Restructure bitstream remarks to be fully standalone (PR #156715)

[Florian Hahn via llvm-commits]

fhahn wrote:

> ## Upgrade notes for frontend authors
> 
> This change does not remove functionality. It fixes limitations of the bitstream remarks format (`Format::Bitstream`). You likely haven't been using this format, because this format was only usable with MachO binaries before this patch. The only reason `SerializerMode::Separate` needed to exist was due to those limitations, so we now don't need the separate mode anymore. If you encouter a `*.opt.bitstream` file, it is now always a fully standalone file of remarks (i.e. it contains all necessary information to deserialize the bitstream). Previously, with `SerializerMode::Separate` this file would have been missing important data, which would have prevented you from reading the file.
> 
> You have likely been using the YAML format (`Format::YAML`) only. The bitstream format exists, because it is 10-20x smaller than the YAML format. You can convert bitstream remark files to YAML using the llvm tool`llvm-remarkutil bitstream2yaml *.opt.bitstream`.
> ### What do I need to do?
> 
> We are now enforcing that the RemarkStreamer that gets installed into the LLVMContext does not point to a dangling file stream when it is destroyed. There is an assertion that will point out if this happens. Consult the updated documentation comments for `llvm::setupLLVMOptimizationRemarks()` and `llvm::finalizeLLVMOptimizationRemarks()` on the lifetime of the remark stream.
> #### I'm using `Expected<std::unique_ptr<ToolOutputFile>> llvm::setupLLVMOptimizationRemarks()`
> 
> Switch to `Expected<LLVMRemarkFileHandle> setupLLVMOptimizationRemarks()`. The LLVMRemarkFileHandle needs to be kept alive until all Remarks have been emitted. You can then let the handle go out of scope or use `LLVMRemarkFileHandle::releaseFile()` to extract the underlying ToolOutputFile.
> #### I'm using `Error llvm::setupLLVMOptimizationRemarks()`
> 
> You can continue using this function, but you have to call `llvm::finalizeLLVMOptimizationRemarks()` before your remark output stream is destroyed.
> #### I'm manually setting up Remarks using `createRemarkSerializer()`
> 
> You can safely remove `SerializerMode::Separate` from `createRemarkSerializer()`. If you move the created Serializer into LLVMRemarkStreamer, you will have to call `LLVMRemarkStreamer::releaseSerializer()` once you're done emitting Remarks. Calling `llvm::finalizeLLVMOptimizationRemarks()` can do this for you.

@tobias-stadler could you add a note to the release notes, and the FAQ to the remarks documentation somewhere?

https://github.com/llvm/llvm-project/pull/156715