All options
-b --test-circuit | <path_to_circ> | Opens a file and runs the test bench circuit inside it, then exits. | The bench is a circuit named logisim_test_verif with output pins test_bench_done_o and test_bench_ok_o. Our four bench files never finished: a folder chooser stayed open (F103). Exit codes 0 (pass) and 255 (fail) are from the code in the jar. | Not completed (F103) |
--clear-prefs | none | Clears the saved preferences at startup. | Not run. The preference folders are listed on the Windows and Linux install pages. | Not run |
-f --test-fpga | <circ_input> <circuit_name> <board> [tick frequency] [HDLONLY] | Builds the HDL for a board and, without HDLONLY, synthesises and downloads. | 31 boards in the jar. On a file with no saved I/O mapping it builds the netlist, passes the DRC and stops with exit 255 (F51). Run under Xvfb in our test. | Tested (F51) |
--fpga-cable | <name> | Chooses the Intel/Altera Quartus cable for --test-fpga by its exact name from quartus_pgm --list. | Needs a board and Quartus; we have neither. | Not testable |
-g --gates | <shape>: ANSI or IEC | Sets the gate symbol style. | Another value prints "Argument for --gates option must be “ANSI” or “IEC”." and exits 10 (F108). | Tested (error) |
-h --help | none | Prints the option summary. | Exit 0 (F01, F108). | Tested |
-l --load | <file> [label] | Loads a memory image into all RAM and ROM parts, or only those with the label. May be repeated. | Works with --tty only. It takes every following word as its own value, so put the circuit before it (F16); before the circuit it prints "Invalid arguments for “--load”" and exits 10. Ignored by a --tty table run without a halt pin (F13). | Tested (F13, F16, F108) |
-m --geometry | WIDTHxHEIGHT[+X+Y] | Sets the main window size and position. | Not run. | Not run |
-n --new-file-format | <circ_input> <circ_output> | Opens a file of any Logisim version and writes it in the current format. | Needs a display; a classic file stops at a dialog (F18). Our run on a 5.0.0 file wrote a 4,241-byte file and exited 0 (F92). | Tested (F18, F92) |
--no-splash | none | Hides the splash screen. | Used in every window run we made. | Used |
-o --locale | <lang> | Sets the interface language. | An unsupported value prints the supported locales and exits 10 (F108). | Tested (error) |
-s --substitute | <lib1> <lib2> | When loading, replaces library lib1 with lib2. | Works when lib1 is written as the circuit file stores the library name; the original library must exist. | Tested (F135) |
--save | <file> | Saves RAM contents to an image file after a --tty run. | With --tty only. On a circuit with no RAM it prints "No RAM was found for the “--save” option." and exits 255; we did not run it on a circuit with RAM (F92, F108). | Partly tested |
-t --tty | <format> | Runs without a window. See the formats below. | An unknown format exits 10 and lists the nine names (F108). | Tested (F05, F19, F91) |
--toplevel-circuit | <circuit_name> | Uses that circuit instead of the file's main circuit. | Printed the truth table of a subcircuit in our test; an unknown name throws a NullPointerException and exits 255 (F92, F108). | Tested |
-u --user-template | empty, plain or a file name | Chooses the template for new projects. | Not run. | Not run |
-v --version | none | Prints the version, build and Java runtime, then exits. | Exit 0 (F108). | Tested |
-w --test-vector | <circuit_name> <test_vector> <circ_file> | Runs a test vector and prints Passed and Failed counts. | Exit 0 even when tests fail; needs a display (F17, F18). See the test vector guide. | Tested (F17, F18, F102) |
No options match.
The count is 18, the same as the usage line of --help (F01). GUI equivalents: -g and -o are in File, Preferences, International; -n is opening the file and File, Save As; -w is Simulate, Test Vector…; --clear-prefs has no menu item (F46).
–tty formats
The format is a comma-separated list of these nine names. An unknown name prints the list and exits 10.
table | The full truth table, one row per input combination, column names from the pin labels. With a halt pin it simulates instead (F05, F13). | Exits on its own (no halt pin) |
table,csv | The same table with commas between the values. | Exits |
table,hex | Identical to table for 1-bit pins; we did not check wider pins. | Exits |
binary, hex, csv, tabs alone | Nothing on our full adder, which has no halt pin; the run kept going until we killed it at 12 s. They change how other formats print values. | No |
halt | halted due to halt pin, logged at ERROR level, when the halt pin reads 1. | Exit 0 at the halt |
speed | 33250 Hz (399 ticks in 12 milliseconds) on a 200-count counter. On a 16-bit counter 5.0.0 ran at 405 to 465 kHz and classic 2.7.1 at 112 to 138 kHz (F19). | Exits at the halt pin |
stats | A component count table: Pin 2, Clock 1, Constant 1, Comparator 1, Counter 1; total 6. | Exits at the halt pin |
tty | What a TTY component prints, and it feeds the keyboard to a Keyboard component. With neither: No TTY or Keyboard component was found. and exit 255. | Exit 255 without them |
No rows match.
The halt pin
An output pin labelled exactly halt. The run ticks the clock until the pin reads 1, then stops. Our 200-count counter used it (F91).
What “tty” is not
The TTY component in the Input/Output library is a character display. The --tty option shares only the name.
Exit codes
--help, --version | 0 | F01, F108 |
--tty table, and --tty halt at the halt pin | 0 | F91 |
| Unknown option, or a value 5.0.0 rejects | 10 | F108 |
--tty tty with no TTY or Keyboard, --save with no RAM | 255 | F108 |
| Circuit file missing | 255 | F92 |
--toplevel-circuit with an unknown name (NullPointerException) | 255 | F92 |
--test-vector: pass, fail, load error, circuit not found | 0 every time | F17, F102 |
--test-vector with no display | 1 (HeadlessException) | F18 |
--test-fpga … HDLONLY on a file with no I/O mapping | 255 | F51 |
--test-circuit pass or fail | 0 or 255, from the code in the jar; not run | F103 |
No rows match.
Recipes
Print a truth table
java -jar logisim-evolution-5.0.0-all.jar --tty table full-adder.circ
Output: A B Cin S Cout
Output: 0 0 0 0 0
Output: 0 0 1 1 0
Output: 0 1 0 1 0
Output: 0 1 1 0 1
Output: 1 0 0 1 0
Output: 1 0 1 0 1
Output: 1 1 0 0 1
1 1 1 1 1
exit: 0
Classic 2.7.1 prints the outputs for the current inputs and keeps simulating until a halt pin goes high, so without one it never exits (F05).
Truth table as CSV for a spreadsheet
java -jar logisim-evolution-5.0.0-all.jar --tty table,csv full-adder.circ
Output: A,B,Cin,S,Cout
Output: 0,0,0,0,0
Output: 0,0,1,1,0
Output: 0,1,0,1,0
Output: 0,1,1,0,1
Output: 1,0,0,1,0
Output: 1,0,1,0,1
Output: 1,1,0,0,1
1,1,1,1,1
Measure simulation speed
Put a halt pin on a counter and run --tty speed. Output: 33250 Hz (399 ticks in 12 milliseconds) on our 200-count counter. The numbers on a 16-bit counter, and the comparison with classic 2.7.1, are in the clock guide (F19).
Run a circuit with a program in a ROM
The circuit goes first, then --load, then the file and the label of the memory:
java -jar logisim-evolution-5.0.0-all.jar --tty halt cpu.circ --load program.txt PROG
Images that load and images that fail are in ROM and loading memory and the memory image tool. Do not combine --load with a plain --tty table run: the table is computed before memories load, so the ROM reads zeros (F13).
Save RAM after the run
Add --save ram.txt to a --tty run. We checked only the error case: on a circuit with no RAM it prints No RAM was found for the “--save” option. and exits 255 (F108). Saving from a circuit that has RAM is not tested here.
Run a test vector in CI
Two lines: put xvfb-run -a in front of java, and read Passed: N, Failed: 0 from the output, not the exit code. Details in the autograder recipe.
Convert an old file to the current format
xvfb-run -a java -jar logisim-evolution-5.0.0-all.jar -n old.circ new.circ
It needs a display. A classic-format file stops at a compatibility dialog, and the process does not exit after it writes the file, so kill it once the output file exists (F18). See the .circ file.
Generate HDL without synthesis
java -jar logisim-evolution-5.0.0-all.jar --test-fpga full-adder.circ main BASYS3 HDLONLY
Output: Building netlist for sheet “main”
Output: Circuit “main” has 8 nets and 0 buses.
Output: Circuit “main” passed DRC check.
Output: The Board BASYS3 has:
Output: 51 Pin(s)
Output: 21 Button(s)
Output: 28 Led(s)
Output: Not all IO components have been mapped to the board “BASYS3”; please map all components to continue!
exit: 255
Map every input and output to the board in the window once and save the file first. Without that the command stops as above (F51). We did not run it on a mapped file, so we do not say where the HDL files are written. The FPGA guide shows the mapping window.
Use the app’s own launcher instead of java -jar
On Windows
C:\Program Files\logisim-evolution\> logisim-evolution.exe --version
On macOS
/Applications/Logisim-evolution.app/Contents/MacOS/Logisim-evolution --tty table full-adder.circ
On Linux
/opt/logisim-evolution/bin/logisim-evolution --tty table full-adder.circ
These launchers accepted the options in our runs (F28, F33), so no separate Java is needed.
Run on a server or in WSL
--tty works with no display. --test-vector and --new-file-format need one: use xvfb-run -a (F18). Java 21 is required for the jar (Java requirements).
Classic Logisim 2.7.1 options
Single dash and no long forms. This is the -help output of logisim-generic-2.7.1.jar:
-tty format | Run without graphical interface. |
-load file | Load image file into RAM (works with -tty only). |
-sub file1 file2 | Load file replacing library file1 with file2. |
-empty, -plain, -template file | Use the empty template, the standard template, or a file. |
-gates shaped|rectangular | Use the specified gate style. |
-locale str | Use the locale given in str. |
-accents yes|no | Use accented characters or ASCII equivalents. |
-nosplash, -version, -help | Hide the splash screen; display the version and exit; display the summary and exit. |
-clearprops | Clear application preferences at startup. |
No rows match.
Only -tty table was run on 2.7.1 (F05, F93); the other rows are the help text, not tests. There is no test vector option (F106). More on classic Logisim 2.7.1.
The --test-fpga … HDLONLY form that writes VHDL or Verilog is described in VHDL and Verilog.