Allow carton to use a provided HTML template file

[aaronjedwards]

Allow carton to use a provided HTML template file

[MaxDesiatov]

I did a quick test yesterday and left my comments in #38, you actually can get the path to your resource if you know its filename, it would look like Bundle.module.path(forResource: "logo", ofType: "png"). The paths and module declarations are automatically generated by SwiftPM.

After sleeping on it, I think we have multiple orthogonal features to implement here:

1. Ability to provide a custom index.html into which the dev.js and bundle.js (the latter is relevant after #97 is merged) entrypoints will be always injected automatically. I'm working on a prototype for it right now, my current thinking it is that a path to this custom index.html would be given to a new --custom-index-page option passed to carton dev and carton bundle. Feedback very welcome as usual if you'd like to see it work differently.
2. Module resources specified in Package.swift, these will require new SwiftWasm snapshots, which takes a lot of time, but I'm working on it in background.
3. Ability to inject links to resources from the 2nd point, either into the standard index.html supplied with carton or into a custom index.html provided in the 1st point.
4. More sophisticated processing of resources, this could include not only compression/slicing of image files, but also CSS minification, TypeScript transpilation etc. This one is a biggie and certainly out of scope of this issue.

I think what you describe in the original post is the 1st point, the 2nd point is being addressed in #38, and points 3 and 4 are useful, but definitely need their own issues created here on GitHub if there's enough interest in resolving those soon. WDYT?

[MaxDesiatov]

This is a great idea and I planned to get to it after #38 is implemented. I personally think that index.html should be just one of the resources provided by a given package that carton dev, and carton bundle from #97 would have special handling for.

We also need to thoroughly specify different edge cases that could appear in this scenario. Most probably they should be handled as a part of the bigger picture needed for #38, specifically:

• What happens to static files with same names from different targets? Most probably we'd gather those into subdirectories for disambiguation. Which exact index.html we use as a template if multiple are present? Most probably we would take only one shipped with the executable product or target. These are just example answers and in no way are final, I'm very open to suggestions here.
• Should we automatically embed links to other resources in this index.html file? Some resources that could be linked are .js, .css and font files.

All PRs are very welcome, but I think it would be great to get some consensus on these questions either here or in #38.

CC @j-f1 as the author of #38

[j-f1]

We could allow specifying *.tmpl template files (like index.html.tmpl) that would allow people to dynamically embed the URL for a given resource file.

[aaronjedwards]

I'm impartial to where the files are held but I'm in favor of the following concepts:

• I can point carton to a specific HTML file to use as a template. Carton could then inject a reference to scripts it generates as part of the build process as well as other resources.
• There should be an option for explicit inclusion of other resources (not solely a dynamic process without user control, although there is probably a default that would fit most scenarios)

[MaxDesiatov]

The mechanism for configuring your resources in Package.swift is specified in the Package Manager Resources proposal, which I recommend checking out. I hope we could follow this proposal as closely as possible. There isn't much to follow at this point really (at least I hope so), SwiftPM already picks up the resources, we just need to check where they are copied (probably to the .build directory somewhere) and handle that properly in carton itself.

[j-f1]

Perhaps we could override the .process rule to mean that the file should be linked into the HTML file while .copy would simply make it available to bundles?

[MaxDesiatov]

That's an interesting suggestion, I initially thought that process would be used only for image slicing/compression. As far as I understand, the processing rules are not very customizable, so ultimately we'll need some flags passed to carton to control it.

[aaronjedwards]

If I'm understanding it correctly, the proposal makes it clear that its primary goal is to bundle resources together with the package somewhere in the build output for easy access during runtime, which isn't of particularly value to carton if we can't easily/reliably known where they will be. Now the process api could help, but seems like the only real tool available at build time that could be leveraged.

[aaronjedwards]

I agree. I feel the 1st point is an issue that has little to do with SwiftPM resources and can be handled separately.

For the 3rd point, things get tricky because while the files are something that we want available at runtime, we also will want Carton to be aware of them and either:

• inject them into the HTML template
• (or) bundle them in a public folder.

There would need to be a standard way to do this, which almost border the territory of something a framework should handle.

But I agree, the 3rd and 4th point should be handled with their own issues.

[MaxDesiatov]

There would not to be a standard way to do this, which almost border the territory of something a framework should handle.

Totally, we've discussed this in relation to Tokamak in TokamakUI/Tokamak#269 recently.

[MaxDesiatov]

A simple implementation to resolve this is available in #101, but it depends on #97 as it's implemented for both carton dev and carton bundle.