Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove reference to fmt in docs #1547

Closed
1 task done
waymobetta opened this issue Jan 17, 2024 · 2 comments · Fixed by #1559
Closed
1 task done

Remove reference to fmt in docs #1547

waymobetta opened this issue Jan 17, 2024 · 2 comments · Fixed by #1559
Labels
📖 documentation Improvements or additions to documentation

Comments

@waymobetta
Copy link
Contributor

waymobetta commented Jan 17, 2024

Description

Presently, we find evidence of fmt and ufmt usage within the monorepo (both in tests as well as in realm instances). Until reflection is supported, we should remove fmt from being referenced within our documentation so as not to confuse people.

TODO:

  • remove instances of fmt usage within docs
@waymobetta waymobetta added the 📖 documentation Improvements or additions to documentation label Jan 17, 2024
@thehowl
Copy link
Member

thehowl commented Jan 17, 2024

imo better to explain it. There is a "test context" and a normal "execution context", and there will likely continue to be.

You can find a list of all of the "extra packages" and their functions here:

gno/gnovm/tests/imports.go

Lines 103 to 114 in b2046c5

if pkgPath == "os" || // special cases even when StdlibsOnly (for tests).
pkgPath == "fmt" || // TODO: try to minimize these exceptions over time.
pkgPath == "log" ||
pkgPath == "crypto/rand" ||
pkgPath == "crypto/md5" ||
pkgPath == "crypto/sha1" ||
pkgPath == "encoding/binary" ||
pkgPath == "encoding/json" ||
pkgPath == "encoding/xml" ||
pkgPath == "internal/os_test" ||
pkgPath == "math/big" ||
pkgPath == "math/rand" ||

The functions, variables and types they expose are below in the switch statement. Note that not all of the package names in the switch cases are available in test contexts; only the ones in the if statement.

Why is that?

Essentially, it's all a bit screwed, we have the directory gnovm/tests/files which works with the semantics of filetests, except it doesn't and it actually has some more superpowers. It has a bunch of stdlibs registered using "gonative", a system to run Go code in Gno (similar to native bindings) which is very problematic for a variety of reasons. fmt is currently implemented that way, and gonative is essentially the reason why fmt.Println(struct{a string}{"x"}) fails.

These work together with the "testing stdlibs", available here: https://github.com/gnolang/gno/tree/master/gnovm/tests/stdlibs -- currently it only covers a few functions in std.

The long term plan (2-3 months down the line, at least): have fmt use reflection, and not be "special" to test contests, together with other useful "test-specific" packages (crypto/md5 and sha1 maybe, encoding/binary, encoding/json, encoding/xml, math/big, math/rand).

We will continue having test-specific functions in std, and likely introduce debug which is also test-specific; so they have to be documented anyway. I suggest making a list of the functions that are currently exported in tests through gonative, and listing them referencing just the Go documentation directly, saying that most of them will eventually be ported over to Gno and be available for docs with gno doc.

Test specific stdlibs will also be available in gno doc eventually :)

@waymobetta
Copy link
Contributor Author

Irrespective of fmt involvement in tests, it's also referenced in a realm within the how-to guide. We can replace this specific usage with ufmt in the meantime until a more long-term solution is provided that addresses what you've touched on, etc. @thehowl

waymobetta added a commit that referenced this issue Jan 18, 2024
<!-- please provide a detailed description of the changes made in this
pull request. -->

In select places within the documentation, we still import `fmt` despite
this not being fully supported. This PR replaces `fmt` usage in those
select cases with `ufmt`.

Closes: #1547 

<details><summary>Contributors' checklist...</summary>

- [ ] Added new tests, or not needed, or not feasible
- [ ] Provided an example (e.g. screenshot) to aid review or the PR is
self-explanatory
- [ ] Updated the official documentation or not needed
- [ ] No breaking changes were made, or a `BREAKING CHANGE: xxx` message
was included in the description
- [ ] Added references to related issues and PRs
- [ ] Provided any useful hints for running manual tests
- [ ] Added new benchmarks to [generated
graphs](https://gnoland.github.io/benchmarks), if any. More info
[here](https://github.com/gnolang/gno/blob/master/.benchmarks/README.md).
</details>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
📖 documentation Improvements or additions to documentation
Projects
Development

Successfully merging a pull request may close this issue.

2 participants