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.

Sign up for GitHub

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

Jump to bottom

proposal for documenting fields and files #518

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

proposal for documenting fields and files #518

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4c7b682
proposal for documenting fields and files
ouabache Sep 18, 2019
3b89a83
added docs for all library file types
ouabache Sep 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
266 changes: 266 additions & 0 deletions dev/doxygen/pages/library.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,272 @@ There exist two types of categories, while all regular element types use exactly
- librepcb::library::Package


# Field Formats {#doc_library_field_formats}



- TEXT: strings are always enclosed in double quotes. "TEXT"
- Use A through Z,a through z and 0-9.
- Use comma,space,dash,underscore and period.
- Any field may impose additional restrictions (IE: no spaces).


- RICH_TEXT: All characters are allowed
- / used as the escape character.


- NUMERIC: numbers are never enclosed in double quotes.
- Use 0-9, dash and period


- UUID: Universal unique identifiers are used to track objects:
- version 4 (random).
- use lower case hexidecimal digits.
- use form hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh.

- TIME: Always use international date/time formats in files:
- Use the [ISO 8601] format for date/time in all files.
- Use UTC time in all files, e.g. `2014-12-20T14:42:30Z`.



- FIXED: Chose from a set of defined offerings.
- true/false.



# File formats {#doc_library_file_formats}




- component_category.lp

(librepcb_component_category UUID LP_COMP_CAT_UUID
(name "TEXT") LP_COMP_CAT_NAME
(description "RICH_TEXT") LP_DESCRIPTION
(keywords "TEXT") LP_KEYWORDS
(author "TEXT") LP_AUTHOR
(version "TEXT") LP_VERSION
(created TIME) LP_TIME
(deprecated FIXED) LP_DEPRECATED
(parent UUID) LP_COMP_CAT_UUID
)





- package_category.lp

(librepcb_package_category UUID LP_PACK_CAT_UUID
(name "TEXT") LP_COMP_CAT_NAME
(description "RICH_TEXT") LP_DESCRIPTION
(keywords "TEXT") LP_KEYWORDS
(author "TEXT") LP_AUTHOR
(version "TEXT") LP_VERSION
(created TIME) LP_TIME
(deprecated FIXED) LP_DEPRECATED
(parent UUID) LP_PACK_CAT_UUID
)



- symbol.lp


(librepcb_symbol UUID LP_SYMBOL_UUID
(name "TEXT") LP_SYMBOL_NAME
(description "RICH_TEXT") LP_DESCRIPTION
(keywords "TEXT") LP_KEYWORDS
(author "TEXT") LP_AUTHOR
(version "TEXT") LP_VERSION
(created TIME) LP_TIME
(deprecated FIXED) LP_DEPRECATED
(category UUID) LP_CATEGORY_UUID

[
(pin UUID LP_SYMBOL_PIN_UUID
(name "TEXT") LP_SYMBOL_PIN_NAME
(position NUMERIC NUMERIC) LP_POSITION_X LP_POSITION_Y
(rotation NUMERIC) LP_ROTATION
(length NUMERIC) LP_LENGTH
) ] repeat 0 or more times

[
(polygon UUID LP_GRAPHIC_UUID
(layer FIXED) LP_GRAPHIC_LAYER
(width NUMERIC) LP_GRAPHIC_WIDTH
(fill FIXED) LP_GRAPHIC_FILL
(grab_area FIXED) LP_GRAPHIC_GRAB
[
(vertex
(position NUMERIC NUMERIC) LP_POSITION_X LP_POSITION_Y
(angle NUMERIC) LP_ANGLE
) ] repeat 2 or more times

) ] polygon repeat 0 or more times

[
(circle UUID LP_GRAPHIC_UUID
(layer FIXED) LP_GRAPHIC_LAYER
(width NUMERIC) LP_GRAPHIC_WIDTH
(fill FIXED) LP_GRAPHIC_FILL
(grab_area FIXED) LP_GRAPHIC_GRAB
(diameter NUMERIC) LP_GRAPHIC_DIAMETER
(position NUMERIC NUMERIC ) LP_POSITION_X LP_POSITION_Y
) ] circle repeat 0 or more times

[
(text UUID LP_TEXT_UUID
(layer sym_names) LP_GRAPHIC_LAYER
(value "TEXT") LP_VALUE
(align FIXED) LP_ALIGN
(height NUMERIC) LP_HEIGHT
(position NUMERIC NUMERIC) LP_POSITION_X,LP_POSITION_Y
(rotation NUMERIC) LP_ROTATION
)
] text repeat 2 or more times. must have {{NAME}} and {{VALUE}}
)





- component.lp

(librepcb_component UUID LP_COMPONENT_UUID
(name "TEXT") LP_COMPONENT_NAME
(description "RICH_TEXT") LP_DESCRIPTION
(keywords "TEXT") LP_KEYWORDS
(author "TEXT") LP_AUTHOR
(version "TEXT") LP_VERSION
(created TIME) LP_TIME
(deprecated FIXED) LP_DEPRECATED
(category UUID) LP_CATEGORY_UUID
(schematic_only FIXED) LP_COMPONENT_SCHEMATIC_ONLY
(default_value "TEXT") LP_COMPONENT_DEFAULT_VALUE
(prefix "TEXT") LP_COMPONENT_DEFAULT_NAME
[
(signal UUID LP_COMPONENT_SIGNAL_UUID
(name "TEXT") LP_COMPONENT_SIGNAL_NAME
(role FIXED) LP_COMPONENT_SIGNAL_ROLE
(required FIXED) LP_COMPONENT_SIGNAL_REQUIRED
(negated FIXED) LP_COMPONENT_SIGNAL_NEGATED
(clock FIXED) LP_COMPONENT_SIGNAL_CLOCK
(forced_net "TEXT") LP_COMPONENT_SIGNAL_FORCED_NET
) ] signal repeat 0 or more times
[
(variant UUID LP_COMPONENT_VARIANT_UUID
(norm "TEXT") LP_NORM
(name "TEXT") LP_COMPONENT_VARIANT_NAME
(description "RICH_TEXT") LP_DESCRIPTION
(gate UUID LP_COMPONENT_GATE_UUID
(symbol UUID) LP_SYMBOL_UUID
(position NUMERIC NUMERIC) LP_POSITION_X LP_POSITION_Y
(rotation NUMERIC) LP_ROTATION
(required FIXED) LP_REQUIRED
(suffix "TEST") LP_SUFFIX
[
(pin UUID LP_SYMBOL_PIN_UUID
(signal UUID ) LP_COMPONENT_SIGNAL_UUID
(text FIXED/"TEXT") LP_TEXT
)
] pin repeat 0 or more times
)
)
] gate repeat 1 or more
)

- package.lp

(librepcb_package UUID LP_PACKAGE_UUID
(name "TEXT") LP_PACKAGE_NAME
(description "RICH_TEXT") LP_DESCRIPTION
(keywords "TEXT") LP_KEYWORDS
(author "TEXT") LP_AUTHOR
(version "TEXT") LP_VERSION
(created TIME) LP_TIME
(deprecated FIXED) LP_DEPRECATED
(category UUID) LP_PACKAGE_CATEGORY_UUID
[
(pad UUID LP_PACKAGE_PAD_UUID
(name "TEXT") LP_PACKAGE_PAD_NAME
) ] pad repeat 0 or more times

[
(footprint UUID LP_FOOTPRINT_UUID
(name "TEXT") LP_FOOTPRINT_NAME
(description "RICH_TEXT") LP_DESCRIPTION
[
(pad UUID LP_PACKAGE_PAD_UUID
(side FIXED) LP_SIDE
(shape FIXED) LP_SHAPE
(position NUMERIC NUMERIC) LP_POSITION_X LP_POSITION_Y
(rotation NUMERIC) LP_ROTATION
(size NUMERIC NUMERIC) LP_SIZE_X LP_SIZE_Y
(drill NUMERIC) LP_DRILL
) ] pad repeat 0 or more times
) ] text repeat 0 or more times
[
(polygon UUID LP_GRAPHIC_UUID
(layer FIXED) LP_LAYER
(width NUMERIC) LP_WIDTH
(fill FIXED) LP_FILL
(grab_area FIXED) LP_GRAB
[
(vertex
(position NUMERIC NUMERIC) LP_POSITION_X LP_POSITION_Y
(angle NUMERIC) LP_ANGLE
) ] vertex repeat 0 or more times
) ] polygon repeat 0 or more times

[
(stroke_text UUID LP_STROKE_UUID
(layer NUMERIC) LP_LAYER
(height NUMERIC) LP_HEIGHT
(stroke_width NUMERIC) LP_STROCK_WIDTH
(letter_spacing FIXED) LP_LETTER_SPACING
(line_spacing FIXED) LP_LINE_SPACING
(align FIXED) LP_ALIGN
(position NUMERIC NUMERIC) LP_POSITION_X LP_POSITION_Y
(rotation NUMERIC) LP_ROTATION
(auto_rotate FIXED) LP_AUTO_ROTATE
(mirror FIXED) LP_MIRROR
(value "TEXT") LP_
) ] stroke repeat 2 or more times
) ] footprint repeat 0 or more times
)



- device.lp


(librepcb_device UUID LP_DEVICE_UUID
(name "TEXT") LP_DEVICE_NAME
(description "RICH_TEXT") LP_DESCRIPTION
(keywords "TEXT") LP_KEYWORDS
(author "TEXT") LP_AUTHOR
(version "TEXT") LP_VERSION
(created TIME) LP_TIME
(deprecated FIXED) LP_DEPRECATED
(category UUID) LP_CATEGORY_UUID
(component UUID) LP_COMPONENT_GATE_UUID
(package UUID) LP_PACKAGE_UUID
[
(pad UUID LP_PACKAGE_PAD_UUID
(signal UUID) LP_COMPONENT_SIGNAL_UUID
) ] pad repeat 0 or more times
)








# Dependencies {#doc_library_dependencies}

A library can have dependencies to other libraries. Therefore, a library needs to provide a list of
Expand Down