# Inside ustcthesis: USTC format rules, build targets, and what make install skips > ustcthesis is the LaTeX class the University of Science and Technology of China uses for graduate and undergraduate theses, and its build files decide what a user ends up with after an install. Makefile targets that do not match the rest of the file, and an install step that copies a subset of the package. **ustctug/ustcthesis** — LaTeX template for USTC thesis - Repository: https://github.com/ustctug/ustcthesis - Website: https://gradschool.ustc.edu.cn/column/190 - Stars: 2,131 · Forks: 452 - Language: TeX - License: LPPL-1.3c - Published: 2026-10-14 · Updated: 2026-10-14 · Language: en - Canonical page: https://hysenlabs.com/projects/ustctug-ustcthesis ## Three USTC format rules collapse into a single class file A class file exists because the university does not publish one formatting rule. ustcthesis is written against three separate documents: the graduate school thesis writing template dated 2025-03-31, the undergraduate thesis quality standard numbered [2025]32 and issued as a trial measure, and the undergraduate format sample revised on 2026-04-24. Two of the three govern undergraduate work and the first governs graduate theses, so one class file serves both audiences, and any complaint about a layout has to be traced back to the right document. That split is a permanent obligation rather than a one-off conversion. Each of the three documents can be revised on its own schedule, and the class can only encode the most recent revision it was written against. The README states that the template follows the newest TeX Live, MacTeX and MiKTeX distributions and works across platforms, so the cross-platform claim sits with the toolchain, not with the layout rules it encodes. ## The class file, one settings file, and two bibliography style pairs At the repository root sit the class file ustcthesis.cls, a separate settings file ustcsetup.tex, and four bibliography style files in two matched pairs. The file names mark one numeric set, ustcthesis-numeric.bst with ustcthesis-numeric.cbx, and one author-year set, ustcthesis-authoryear.bst with ustcthesis-authoryear.cbx, and the Makefile keeps the two .bst files as a single unit in its BSTFILES variable. Chapter text belongs in chapters/, figures in figures/, bibliography entries in references.bib, with main.tex as the entry document. Alongside them the class ships ustcthesis-doc.tex for the manual, build.lua and tests/ for the test suite, and latexmkrc plus a Makefile to drive the build. Nothing in the README enumerates the keys inside ustcsetup.tex, so the bundled manual is the only described place to find them, and the README asks readers to read it before touching the template. ## From the download page to a first XeLaTeX build Five places to obtain the archive appear in the README. The GitHub releases page comes first, and the graduate school copy at gradschool.ustc.edu.cn/column/65 is offered with a warning that the version there may be older. A TexPage entry, a LoongTeX copy and an Overleaf template fill the space between them. The toolchain floor matters more than the download location. TeX Live, MacTeX or MiKTeX from the 2021 distributions or newer is the stated requirement, upgrading to the newest available is encouraged, and the CTeX suite is marked unsupported. On a machine above that floor, three commands cover the whole cycle, compiling the manual, compiling the thesis, and clearing the intermediate files. ```bash latexmk -xelatex ustcthesis-doc.tex latexmk -xelatex main.tex latexmk -c ``` An xelatex flag on the command line picks the engine rather than a setting in ustcsetup.tex, and latexmk reads the latexmkrc file sitting in the repository root, so the build behaves the same whether it starts in a terminal or from an editor front end. ## The Makefile reads its own version out of the class file In the Makefile, LATEXMK is set to latexmk -xelatex and the same three operations repeat as targets, which gives a second route to identical output. ```bash make doc make make clean ``` Beyond those targets, the archive version number is not stored in the Makefile at all. It is scraped out of ustcthesis.cls with egrep, matching the ustcthesisversion macro and keeping digits, dots, lowercase letters and dashes, while the install root comes from kpsewhich --var-value TEXMFHOME. The consequence is narrow but real: the version stamped on a distributed archive is only as dependable as that regex, and a class file edited by hand yields an archive name that can drift away from the version inside it. Two target names do not line up with the rest of the file. The .PHONY line names distclean, yet no distclean recipe exists anywhere below it, so asking for that target stops with a missing target error, while cleanall carries a recipe and never appears in .PHONY. FORCE_MAKE is named in .PHONY and attached to both PDF rules without a recipe of its own, which is how the file forces main.pdf and ustcthesis-doc.pdf to rebuild on every run. ## A system-wide install leaves four bibliography files behind An install run depends on cls and doc, so the manual is compiled before a single file gets copied, and the recipe shows exactly what lands where. ```bash install : cls doc mkdir -p $(TEXMF)/{doc,source,tex}/latex/$(NAME) ``` The two .bst files are copied into the bibtex/bst directory under TEXMFHOME, the class file into tex/latex, and the manual into doc/latex renamed from ustcthesis-doc.pdf to ustcthesis.pdf. None of the four .bbx and .cbx files are copied, even though the zip target in the same Makefile globs them into the archive alongside the rest of the distribution. The brace expansion in that mkdir line creates a source subdirectory the recipe never fills, and it expands at all only because the file declares SHELL = bash at the top. A system-wide install is therefore not the same set of files as the zip archive, and anyone relying on the install target has to copy the four style files by hand or keep building from the unpacked directory. ## CTeX is refused and the school copy can drift Three failure modes come out of the project's own instructions. The explicit one is the CTeX suite, which the README marks unsupported, ruling out every setup built on that bundle. The second is version drift, since the graduate school copy is offered as possibly older, and the reporting procedure itself begins by telling a user with a problem to upgrade to the newest version and check whether the fault is already fixed. A stale copy typesets a different document than a current one, and that difference arrives dressed up as a bug report. The third is rule drift. When the school revises one of its three format documents, the class keeps producing the old layout until somebody rebuilds it, and the fix path in the README terminates in a person rather than a check: a new GitHub issue or a message to the template author Zeping Lee, carrying the distribution version, the symptom, the expected result and a source excerpt or screenshot. No automatic comparison of a finished thesis against those standards appears anywhere, so a committee deadline rests on the two document dates, 2025-03-31 and 2026-04-24. ## Four other routes to the same class file The same class is reachable without a local TeX installation through the TexPage entry, the LoongTeX site and the Overleaf template gallery. That matters because of the version floor: 2021 or newer is asked for and upgrading is urged, while the distribution version behind the hosted Overleaf route is not identified anywhere in the project documentation. On the local route the reader picks the distribution, and on the hosted route that choice is made somewhere else. Two differences matter more than the channel itself. Inside the archive, the manual travels as ustcthesis-doc.pdf and can be rebuilt from ustcthesis-doc.tex, so the settings keys the README leaves unlisted stay reachable even where the class cannot be installed. The other difference is the non-LaTeX path, and for a degree that accepts a Word document the undergraduate format sample dated 2026-04-24 is the authority the class is measured against, so the class earns nothing there beyond a description of the rules it implements. ## Tests run in CI but no case is listed Testing is part of the repository layout: a build.lua file for l3build, a tests/ directory, a make target running l3build check, and a save target running bash tests/save.sh to capture cases. A CI badge in the README points at a test workflow on the master branch. No test case is named, so the documentation does not say whether page geometry, the bibliography styles or the front matter sit under regression, and a reader cannot tell how far the check reaches. The class file carries the LPPL-1.3c identifier, and the last push to master was on 2026-09-27, a minute before v5.0.2 followed v5.0.1 from 2026-07-25 and v5.0.0 from 2026-07-19. The README does not say what a department should rename a modified copy to, which is the first thing to settle before adapting the class for a local requirement. ## Conclusion Take ustcthesis if your USTC degree accepts a LaTeX thesis and you can run TeX Live, MacTeX or MiKTeX from 2021 onward; leave it aside for a committee that expects a Word file, and never reach for it under CTeX, which the project refuses outright. Read ustcthesis-doc.pdf before editing anything, compare the result against the undergraduate format sample dated 2026-04-24, and confirm the four bibliography style files sit where BibTeX can find them, because make install copies the class and the bst files but leaves the bbx and cbx files out. ## FAQ ### Can I build ustcthesis with the CTeX suite? No. The README marks the CTeX suite as unsupported and points readers to a FAQ entry on the topic. The supported toolchains are TeX Live, MacTeX and MiKTeX from the 2021 distributions onward. ### Which TeX Live version does ustcthesis need? TeX Live, MacTeX or MiKTeX no older than the 2021 distributions, with upgrading to the newest available encouraged. Installation and upgrade instructions are kept in the project wiki guide rather than in the README itself. ### How do I compile ustcthesis and produce main.pdf? Run latexmk with the xelatex engine against main.tex, or use the Makefile target that does the same thing. The manual is built the same way from ustcthesis-doc.tex, and latexmk -c clears the intermediate files. ### Where can I get ustcthesis without installing TeX Live? The README points to a TexPage entry, a LoongTeX copy and an Overleaf template, all of which host the class away from a local installation. It does not state which distribution version the hosted copies run. ### How do I report a formatting problem in ustcthesis? Read the university standard, upgrade to the newest version, search the existing GitHub issues, then open a new issue or contact the template author Zeping Lee. The README asks for the distribution version, the symptom, the expected result and a source excerpt or screenshot. ### Does make install give me the whole ustcthesis package? No. The install target copies the class file, the two .bst files and the manual into TEXMFHOME, and leaves the four .bbx and .cbx files behind. The zip target in the same Makefile does include them. ## Sources - [License: LPPL-1.3c](https://github.com/ustctug/ustcthesis/blob/master/LICENSE) - [Project website](https://gradschool.ustc.edu.cn/column/190) - [README](https://github.com/ustctug/ustcthesis/blob/master/README.md) - [Releases](https://github.com/ustctug/ustcthesis/releases) - [ustctug/ustcthesis on GitHub](https://github.com/ustctug/ustcthesis) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ustctug-ustcthesis