Awesome
octool
A small project to help me continue my learning of the Rust language. All suggestions and criticisms are welcome (but that doesn't mean I'll get to them in a timely manner, I can be lazy at times)
You can build from the included source by running cargo build --release
(if you have the Rust environment installed) or you can use the binary from the Releases section on GitHub. Unlike my older OC-tool, this tool does not auto update itself to the latest version, but it will let you know if there is an update.
You can find a basic picture guide for the use of octool here https://rusty-bits.github.io/octool/
Command line options
./octool [options] [-V x.y.z] [INPUT_folder || config.plist]
-d use debug
versions for EFI instead of release
versions
-h print help/usage message then exit
-v print octool version information and booted OpenCore version if the var is in NVRAM then exit
-V x.y.z select OpenCore version number to use e.g. -V 0.9.7
- without this option octool will make a quick guess as to which version to use based on the INPUT config.plist, if no INPUT config.plist is provided, octool will default to the latest OpenCore version
octool takes a path to a folder whos name contains INPUT
at any point. This folder contains a config.plist and additional files for a specific build which allows the user to have numerous differing configs. octool will also take a direct path to a specific config.plist
to use if desired and will gather what is needed for that specific config in the generic INPUT
folder
If you run octool with no path provided ./octool
will look for config.plist
in the generic INPUT
folder, if it doesn't find it there it will use the OpenCorePkg/Docs/Sample.plist
file.
At startup, octool checks for a local copy of the builds branch of the Dortania/build-repo so it will know the urls and hashes of the prebuilt binary resources. Thank you dhinakg, hieplpvip, and khronokernel.
- It will update or download it to the
build-repo
into thetool_config_files
folder as needed.
Next, octool does the same thing for the master branch of the Acidanthera OpenCorePkg source files, thanks to the people of Acidanthera, in order to have the corresponding Sample.plist and Configuration.tex files, etc. for the version of OpenCore that you are building. They will be placed into the resources
folder along with the corresponding binaries from the Dortania builds. This will allow octool
to use Acidanthera tools while building the EFI, such as the ocvalitate and CreateVault tools. Thanks, again dhinakg.
Lastly, octool will run the input config.plist through ocvalitade and give you the option to quit or continue.
If you continue you then enter the
config.plist editor...
Navigation: arrow keys or some standard vi keys
'up'/'k' jump to top of section
^ 't'
| ^
'left'/'h' <-- --> 'right'/'l' |
| v
v 'b'
'down'/'j' jump to bottom of section
Usage:
'ENTER' will switch to edit mode for string, integer, or data fields. When editing a data field 'TAB' will toggle between editing the data as hex or as a string.
- 'ENTER' will save any changes made
- 'ESC' will discard and changes
- if the field being edited has values listed in the
Configuration.tex
file, octool will display a list of them
'SPACE' will toggles boolean value between true/false
- 'SPACE' will also toggle the Enabled status of kexts, drivers, tools, and amls when they are highlighted in the section list
- and will toggle binary values for fields that have bit values listed in the
Configuration.tex
file
'a' add
- if in a resource section there is option to select from a list of known resources, or add a blank resource template to the working plist
from the Sample.plist
- if in another section you can select a type and key name to add to the working plist
'ctrl-c' copy
- copy the highlighted field or section
'd' delete
- will delete the highlighted field or section after confirmation (dd
command). The deleted data can be replaced by using the 'p' paste command
'f' find
- find all occurances of a string in the plist
- if there is only one occurance, it will jump to the location
- if there is more than one occurance, it will present a list to select from
- 'n' can be used to go to the next item without needing to do another find command
'G' go
(capital G) - make an OUTPUT/EFI/OC folder from the config.plist
- if
OpenCanopy.efi
is enabled it will copy the OcBinaryData Resources toOUTPUT/EFI/OC/Resources
- if
Misc > Security > Vault
is set toBasic
orSecure
, octool will compute the required files and sign theOpenCore.efi
if needed - octool will ignore resources that it doesn't know unless they are placed in the INPUT folder, it will print out a warning, but it will not make a change to the config.plist for the unknown resource
- any file placed in the
INPUT
folder will take priority and will be used for theOUTPUT/EFI
, even if a more recent version of that resource is available elsewhere. This is good for using a specific version of a kext, for example, or for using a specific SSDT or USBMap - lastly, it will again validate the
OUTPUT/EFI/OC/config.plist
file with ocvalidate
'i' show info
of highlighted item.
- If item is resource such as a kext or driver, octool will show the source of the file it will place in the
OUTPUT/EFI
folder. - Otherwise, octool will show the description and info from the corresponding Acidanthera
Configuration.tex
file.
'I' - Capital I - Insert
- enter the path to a plist file, or drop it on the window, and octool will add the fields from that plist
- useful to add a plist that just contains Patches, for example the
patches_OC.plist
file created by CorpNewt's SSDTTime tool
'K' Key
- capital K - edit the name of the highlighted key
'M' merge
- capital M - will add missing fields to the config.plist
from the Sample.plist
without changing any existing fields.
- this command, coupled with its companion Purge command (capital P) will update a config.plist when OpenCore plist format changes occur
'n' next
- jump to the next found item if more than one occurance was found
'O' order
- Capital O - if currently in the Kernel > Add section the 'O' command will check the order and dependencies of kexts.
- If a kext is in the wrong order based on a dependency then octool will reorder them.
- If a required dependency is missing then octool will add and enable the required dependency.
- If there are any duplicate enabled kexts then octool will disable the duplicates.
'P' purge
- Capital P - removes fields from the config.plist
that are not in the Sample.plist
- this command, coupled with it's companion merge command (capital M) will update a config.plist when OpenCore plst format changes occur
'p' paste
- places the last deleted or modified etc. item into the plist (for those familiar with vi commands)
- if pasting into a dictionary,
octool
will append-copy
to the pasted item
'q' quit
- if unsaved changes were made to the config.plist
octool will show a warning so changes can be saved
'r' reset
- if a single item is selected, reset its value to the same as the Sample.plist
value
- if a section is highlighted, reset the whole section to the same as the section in the
Sample.plist
's' save
a copy of the config.plist
as INPUT/modified_config.plist
modified_
will be added to the begining of the saved file unless you are already working on amodified_
file- the saved file will be checked with
ocvalidate
for any errors
'V' Version
- Capital V - change the version of OpenCore that will be checked against and used in the OUTPUT
EFI
- or, if 'V' is used while a resource is highlighted, you can change the version of that specific resource
'ctrl-x' cut
- remove the highlighted field or section from the plist
'y' yank
- copy the highlighted field or section (included for those vim users used to 'y' for copying)
'ctrl-v' paste
- place the last cut, copied, etc. item into the plist
File and Folder Descriptions
tool_config_files
folder - contains various json formatted files
octool_config.json
- settings for octool itself, octool will create this if it doesn't existresource_list.json
- list of resources by full name e.g.Lilu.kext
and their parent resource, octool will create this if it doesn't existbuild-repo
folder - contains theconfig.json
file from the Dortania builds repo with url, version, hash, date created, etc. info for the parent resources. octool will download this from Dortania if it doesn't existother.json
- contains a list of additional parent resources not included in the Dortaniabuild--repo
, octool will create this if it doesn't exist
INPUT
folder - place your config.plist
here along with other files to be included in the OUTPUT/EFI
, such as custom SSDT files, custom Drivers, custom OpenCanopy themes, etc.
octool
will not overwrite the input config.plist on save, instead it will save a version calledmodified_config.plist
in this folder so the originalconfig.plist
can still be used if neededoctool
will also automatically save a config.plist titledlast_built_config.plist
when the build command is run for easy reference to a copy of the config.plist that is in the OUTPUT/EFI folder
OUTPUT
folder - location where octool
will put the created EFI
folder
resources
folder - location where octool
places the resources needed to create the OUTPUT/EFI
folder. Can be deleted if desired, octool will gather any resources it needs when run
To Do:
- change tool configuration from inside tool, the configuration file
tool_config_files/octool_config.json
contains vars to set up octool, for example the language versions of the audio files for OpenCanopy for e.g.en
- keep the highlighted item on screen while reading long info from the Configuration.tex so the user can edit the field while also reading the info
- fix some style formatting of the info screens so underline, bold, etc. looks better when it crosses multiple lines